Skip to content

Commit

Permalink
Fixes in exploring
Browse files Browse the repository at this point in the history
  • Loading branch information
@raphink
raphink committed Feb 26, 2013
1 parent f74453d commit f749de1
Showing 1 changed file with 51 additions and 37 deletions.
88 changes: 51 additions & 37 deletions en/chapters/exploring_augtool.tex
View file
Expand Up @@ -28,44 +28,53 @@ \section{Parsing your System Configuration Files}
\nopagebreak
\begin{augtoolsh}[]
augtool> help
Commands:
quit - exit the program
clear - clear the value of a node
defnode - set a variable, possibly creating a new node
defvar - set a variable
get - get the value of a node
ins - insert new node
insert - insert new node (alias of 'ins')
load - (re)load files under /files
ls - list children of a node
match - print matches for a path expression
mv - move a subtree
move - move a subtree (alias of 'mv')
print - print a subtree
dump-xml - print a subtree as XML
rm - delete nodes and subtrees
Admin commands:
help - print help
load - (re)load files under /files
quit - exit the program
retrieve - transform tree into text
save - save all pending changes
store - parse text into tree
transform - add a file transform
\end{augtoolsh}
\begin{augtoolsh}[]
Read commands:
dump-xml - print a subtree as XML
get - get the value of a node
label - get the label of a node
ls - list children of a node
match - print matches for a path expression
print - print a subtree
span - print position in input file corresponding to tree
\end{augtoolsh}
\begin{augtoolsh}[]
Write commands:
clear - clear the value of a node
clearm - clear the value of multiple nodes
ins - insert new node
insert - insert new node (alias of 'ins')
mv - move a subtree
move - move a subtree (alias of 'mv')
rename - rename a subtree label
rm - delete nodes and subtrees
set - set the value of a node
setm - set the value of multiple nodes
touch - create a new node
\end{augtoolsh}
\begin{augtoolsh}[]
save - save all pending changes
set - set the value of a node
setm - set the value of multiple nodes
clearm - clear the value of multiple nodes
span - print position in input file corresponding to tree
store - parse text into tree
retrieve - transform tree into text
touch - create a new node
help - print help
Path expression commands:
defnode - set a variable, possibly creating a new node
defvar - set a variable
Type 'help <command>' for more information on a command
\end{augtoolsh}
Augeas transforms your configuration files into a tree,
which has two nodes at its root: \texttt{/augeas} and \texttt{/files}.
Augeas transforms your configuration files into a tree with two nodes at its root: \texttt{/augeas} and \texttt{/files}.
The \texttt{/augeas} node contains metadata, which we will be looking at in chapter~\ref{chap:metadata},
while \texttt{/files} contains the representation of the files Augeas was able to parse.
You can see these two nodes by typing \verb!ls /!:
You can inspect these two nodes by typing \verb!ls /!:
\index{Commands!ls}
Expand All @@ -75,7 +84,7 @@ \section{Parsing your System Configuration Files}
files/ = (none)
\end{augtoolsh}
What does that mean? We see the two nodes at the top of the Augeas tree, and we see that neither of them has a value. In the Augeas tree, each node can have children and a value associated with it.
What does this mean? We see the two nodes at the top of the Augeas tree, and that neither of them has a value. In the Augeas tree, each node can have children and a value associated with it.
\verb!ls! is an \verb!augtool! command which lists the children of the given node and gives their value (if any).
Expand Down Expand Up @@ -126,6 +135,10 @@ \section{Parsing your System Configuration Files}
/files/etc/fstab/1/opt[3] = nosuid
\end{augtoolsh}
\begin{quote}
\info{In \texttt{augtool}, \texttt{match} returns values as well as found paths. In the API however, only paths are returned, without the associated values.}
\end{quote}
Now, you might want to get the value of the single node matching an expression, and make sure that this node is unique. For example, if we want the value of the first \verb!opt! node of this first line, we could use the \verb!get! command:
\begin{augtoolsh}[]
Expand All @@ -142,7 +155,7 @@ \section{Parsing your System Configuration Files}
\section{Using a Fakeroot}
It is often useful to play with \verb!augtool! when you want to understand the Augeas tree or try XPath expressions. However, you likely don't want to play with the files in your \texttt{/etc} directory and take the risk of ruining your system. Augeas lets you set a fakeroot so that the files parsed and modified by Augeas are taken from this root instead of the \texttt{/} directory of your system.
It is often useful to play with \verb!augtool! when you want to understand the Augeas tree or try XPath expressions. However, you likely don't want to play with the files in your \texttt{/etc} directory and take the risk of ruining your system. Augeas lets you set a fake root so that the files parsed and modified by Augeas are taken from this root instead of the \texttt{/} directory of your system.
\index{augtool!options!--root} \index{Environment variables!\textsc{augeas\_root}}
Expand All @@ -167,7 +180,7 @@ \section{Modifying Files}
We have seen already how Augeas lets you parse your configuration files in a unified way. The Augeas tree is not only a parsing facility as Augeas exposes commands to modify the tree and save the changes to the original files.
The fakeroot option will be useful for us here, in order to modify the files without affecting the system. We will also use the \verb!--backup! option in \verb!augtool! so that the original files are preserved with a \verb!.augsave! extension.
The \verb!--root! option will be useful for us here, in order to modify the files without affecting the system. We will also use the \verb!--backup! option in \verb!augtool! so that the original files are preserved with a \verb!.augsave! extension.
\index{augtool!options!--backup} \index{augtool!options!--root} \index{Commands!rm} \index{Commands!quit} \index{Commands!save} \index{Environment variables!\textsc{augeas\_root}}
Expand All @@ -183,7 +196,7 @@ \section{Modifying Files}
In listing \refandpage{lst:rm_fstab_opt} we change the filesystem options specified on the first line of \texttt{/etc/fstab} by removing the third \verb!opt! node. The \verb!rm! command on line 2 removes only the \verb!opt! node we specified. Line 3 tells us that the \verb!rm! command removed only one node, the \texttt{/files/etc/fstab/1/opt[3]} node. Lines 4 through 11 show us the \texttt{/files/etc/fstab/1} tree without the removed node.
On line 12, we call the \verb!save! command. This command tells Augeas to save the tree back to the configuration files. Augeas inspects the files and tries to apply the new tree to them. In our case, the \verb!save! command was successful as line 13 tells us, and one file was modified, which is what we expected. We can then quit the \verb!augtool! session by typing \verb!quit! on line 14. We can then quit the \verb!augtool! session by typing \verb!quit! on line 14.
On line 12, we call the \verb!save! command. This command tells Augeas to save the tree back to the configuration files. Augeas inspects the files and tries to apply the new tree to them. In our case, the \verb!save! command was successful as line 13 tells us, and one file was modified, which is what we expected. We can then quit the \verb!augtool! session by typing \verb!quit! on line 14.
We use the \verb!diff -u! command on line 15 to inspect the changes made by Augeas to the file. As expected, only the first line that is not empty or a comment was modified. Lines 22 and 23 in the listing show us the differences between the old and new lines. We can see that only the third option has been removed, and that the spaces have been strictly preserved. The rest of the file was left untouched.
Expand All @@ -197,17 +210,18 @@ \section{Preserving existing files}
\item
\verb!--backup! will save the original file with the extension .augsave and write the new file under the original file name;
\item
\verb!--new! will save the modified file with a .augnew extension and leave the original file untouched.
\verb!--new! will save the modified file with a \verb!.augnew! extension and leave the original file untouched.
\end{itemize}
These options actually modify the value of the \texttt{/augeas/save} node in the Augeas tree\footnoteref{sec:save_node}.
These options actually modify the value of the \texttt{/augeas/save} node in the Augeas tree.\footnoteref{sec:save_node}
\section{Locating nodes in files}
\label{sec:locating_nodes} \index{augtool!options!--span} \index{Flags!\textsc{aug\_enable\_span}}
The span metadata were added in Augeas 0.8.0. For performance reasons, they are not activated by default. This functionality can be activated by the \verb!AUG_ENABLE_SPAN! flag or the \verb!--span! flag in \verb!augtool!.
You can see if the \verb!span! functionality is activated in the current session by looking at the \texttt{/augeas/span} node\footnoteref{sec:span_node}:
You can see if the \verb!span! functionality is activated in the current session by looking at the \texttt{/augeas/span} node:\footnoteref{sec:span_node}
\index{Metadata!\slash{}augeas\slash{}span}
Expand Down Expand Up @@ -236,7 +250,7 @@ \section{Locating nodes in files}
\begin{itemize}
\item
The \verb!driftfile! label was found in the file between positions 67 and 76. This also means that \verb!driftfile! is a dynamic key, not a static label\footnote{It was declared with the \verb!key! keyword, not with \verb!label!. See chapter \refandpage{chap:writing_lenses}};
The \verb!driftfile! label was found in the file between positions 67 and 76. This also means that \verb!driftfile! is a dynamic key, not a static label;\footnote{It was declared with the \verb!key! keyword, not with \verb!label!. See chapter \refandpage{chap:writing_lenses}}
\item
The value of the \verb!driftfile! node was found between positions 77 and 99 in the file;
\item
Expand Down

0 comments on commit f749de1

Please sign in to comment.