Provided by: augeas-tools_1.14.0-1_amd64 
NAME
augprint - create an idempotent augtool script for a given file
SYNOPSIS
augprint [--pretty|-p] [--regexp[=n]|-r[n]] [--noseq|-s] [--verbose|-v] [--lens name|-l
name] [--target /target|-t /target] FILE
DESCRIPTION
augprint creates an augtool script for a given FILE consisting primarily of "set"
commands.
The resulting augtool script is designed to be idempotent, and will not result in any
changes when applied to the original file.
augprint replaces each numbered location in the tree with a path-expression that uniquely
identifies the position using the values within that position.
This makes the path-expression independant of the position-number, and thereby applicable
to files which in which the same data may exist at an alternate position-number
See "Examples" for sample output
Regexp output
By default augprint produces path-expressions made up of simple equality "=" comparisions
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/ipaddr '127.0.0.1'
The option --regexp changes the output to produce regular expression comparisions
set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\.0\\..*')]/ipaddr '127.0.0.1'
The minimum length N of the regular expression can be specified using "--regexp=N"
augprint will choose a longer regular expression than N if multiple values would match
using the N character regular expression.
Limitations
Append-only
The output is based primarily on set operations. The set operation can only:
a) change an existing value in-situ
b) append a new value after the last position in the group
This means that when an entry is re-created, it may not be in the same position as
originally intended. ie if the entry for 192.0.2.3 does not already exist, it will be
created as the last entry in /etc/hosts
Often, such out-of-sequence entries will not matter to the resulting configuration file.
If it does matter, further manual editing of the "augtool" script will be required.
Repeated Values
augprint is not always successful in finding a path-expression which is unique to a
position. In this case augprint appends a position to an expression which is not unique
This occurs in particular if there are repeated values within the file.
For an /etc/hosts file of
#------
192.0.2.3 defaultdns
#------
augprint would produce the output
set /files/etc/hosts/#comment[.='--------'][1] '--------'
set /files/etc/hosts/seq::*[ipaddr='192.0.2.3']/ipaddr '192.0.2.3'
set /files/etc/hosts/seq::*[ipaddr='192.0.2.3']/canonical 'defaultdns'
set /files/etc/hosts/#comment[.='--------'][2] '--------'
Notice how "#comment" paths have "[1]" and "[2]" appended respectively to the "[expr]"
Other paths which do have unique path-expressions are not directly affected
OPTIONS
-v, --verbose
Include the original numbered paths as comments in the output
-p, --pretty
Create more readable output by adding spaces and empty lines
-r, -rN, --regexp, --regexp=N
Generate regular expressions to match values, using a minumum length of N characters
from the value
N can be omitted and defaults to 8
-l, --lens=LENS
Use LENS for the given file; without this option, augprint uses the default lens for
the file
-t targetfile, --target=targetfile
Generate the script for the FILE specified as if its path was really targetfile
This will apply the lens corresponding to targetfile to FILE and modifying the
resulting path-expressions of FILE to correspond to targetfile
targetfile must be the full path name, starting with a '/'
See "Examples" for how --target can be used in practice
-s, --noseq
Do not use "seq::*" in the output, use "*" instead. For example
set /files/etc/hosts/*[ipaddr='127.0.0.1']/ipaddr '127.0.0.1'
IMPORTANT: The resulting output will no longer create a new entry for 127.0.0.1 if
none already exists. The "--noseq" option exists so that the resulting paths can be
used with augeas versions prior to 1.13.0 (subject to this limitation)
EXAMPLES
These examples use the following /etc/hosts file as the FILE
127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4
192.0.2.3 dns-a
192.0.2.4 dns-b
The output from "augtool 'print /files/etc/hosts'" would be
/files/etc/hosts
/files/etc/hosts/1
/files/etc/hosts/1/ipaddr = "127.0.0.1"
/files/etc/hosts/1/canonical = "localhost"
/files/etc/hosts/1/alias[1] = "localhost.localdomain"
/files/etc/hosts/1/alias[2] = "localhost4"
/files/etc/hosts/1/alias[3] = "localhost4.localdomain4"
/files/etc/hosts/2
/files/etc/hosts/2/ipaddr = "192.0.2.3"
/files/etc/hosts/2/canonical = "dns-a"
/files/etc/hosts/3
/files/etc/hosts/3/ipaddr = "192.0.2.4"
/files/etc/hosts/3/canonical = "dns-b"
Default output
"augprint /etc/hosts"
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/ipaddr '127.0.0.1'
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/canonical 'localhost'
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/alias[.='localhost.localdomain'] 'localhost.localdomain'
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/alias[.='localhost4'] 'localhost4'
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/alias[.='localhost4.localdomain4'] 'localhost4.localdomain4'
set /files/etc/hosts/seq::*[ipaddr='192.0.2.3']/ipaddr '192.0.2.3'
set /files/etc/hosts/seq::*[ipaddr='192.0.2.3']/canonical 'dns-a'
set /files/etc/hosts/seq::*[ipaddr='192.0.2.4']/ipaddr '192.0.2.4'
set /files/etc/hosts/seq::*[ipaddr='192.0.2.4']/canonical 'dns-b'
Verbose output
"augprint --verbose /etc/hosts"
# /files/etc/hosts
# /files/etc/hosts/1
# /files/etc/hosts/1/ipaddr '127.0.0.1'
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/ipaddr '127.0.0.1'
# /files/etc/hosts/1/canonical 'localhost'
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/canonical 'localhost'
# /files/etc/hosts/1/alias[1] 'localhost.localdomain'
set /files/etc/hosts/seq::*[ipaddr='127.0.0.1']/alias[.='localhost.localdomain'] 'localhost.localdomain'
...
Rexexp output
"augprint --regexp=4 /etc/hosts"
set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/ipaddr '127.0.0.1'
set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/canonical 'localhost'
set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/alias[.=~regexp('localhost\\..*')] 'localhost.localdomain'
set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/alias[.=~regexp('localhost4')] 'localhost4'
set /files/etc/hosts/seq::*[ipaddr=~regexp('127\\..*')]/alias[.=~regexp('localhost4\\..*')] 'localhost4.localdomain4'
set /files/etc/hosts/seq::*[ipaddr=~regexp('192\\.0\\.2\\.3')]/ipaddr '192.0.2.3'
set /files/etc/hosts/seq::*[ipaddr=~regexp('192\\.0\\.2\\.3')]/canonical 'dns-a'
set /files/etc/hosts/seq::*[ipaddr=~regexp('192\\.0\\.2\\.4')]/ipaddr '192.0.2.4'
set /files/etc/hosts/seq::*[ipaddr=~regexp('192\\.0\\.2\\.4')]/canonical 'dns-b'
Note that although a minimum length of 4 has been specified, augprint will choose longer
regular expressions as needed to ensure a unique match.
Using --lens
If a file is not assocatiated with a lens by default, --lens lensname can be used to
specify a lens.
When --lens is specified, the output is prefixed with suitable "transform" and
"load-file" statements, as required to complete the augtool script, and a setm statement
to exclude other autoloaded lenses.
"augprint --lens shellvars /etc/skel/.bashrc"
setm /augeas/load/*[incl='/etc/skel/.bashrc' and label() != 'shellvars']/excl '/etc/skel/.bashrc'
transform shellvars incl /etc/skel/.bashrc
load-file /etc/skel/.bashrc
set /files/etc/skel/.bashrc/#comment[.='.bashrc'] '.bashrc'
set /files/etc/skel/.bashrc/#comment[.='Source global definitions'] 'Source global definitions'
set /files/etc/skel/.bashrc/@if[.='[ -f /etc/bashrc ]'] '[ -f /etc/bashrc ]'
set /files/etc/skel/.bashrc/@if[.='[ -f /etc/bashrc ]']/.source '/etc/bashrc'
set /files/etc/skel/.bashrc/#comment[.='User specific environment'] 'User specific environment'
...
The lenses "simplelines" "shellvars" are most commonly useful as lenses for files that do
not have a specific lens
Using --target
In order to prepare an augtool script intended for a given file, it may be desired to copy
the file to another location, rather than editting the original file.
The option --target simplifies this process.
a) copy /etc/hosts to a new location
cp /etc/hosts ~
b) edit ~/hosts to suit
echo '192.0.2.7 defaultdns' >> ~/hosts
c) Run "augprint" as follows
augprint --target /etc/hosts ~/hosts
d) Copy the relevant part of the output to an augtool script or other Augeas client
set /files/etc/hosts/seq::*[ipaddr='192.0.2.7']/ipaddr '192.0.2.7'
set /files/etc/hosts/seq::*[ipaddr='192.0.2.7']/canonical 'defaultdns'
Notice that "augprint" has generated paths corresponding to --target (/etc/hosts) instead
of the FILE argument (~/hosts)
ENVIRONMENT VARIABLES
AUGEAS_ROOT
The effective file system root, defaults to '/'.
AUGEAS_LENS_LIB
Colon separated list of directories with lenses. Directories specified here are
searched before the default directories /usr/share/augeas/lenses and
/usr/share/augeas/lenses/dist
EXIT STATUS
The exit status is 0 when the command was successful and 1 if any error occurred.
FILES
Lenses and schema definitions in /usr/share/augeas/lenses and
/usr/share/augeas/lenses/dist
AUTHOR
George Hansper <george@hansper.id.au>
COPYRIGHT AND LICENSE
Copyright 2022 George Hansper
Augeas (and augprint) are distributed under the GNU Lesser General Public License (LGPL),
version 2.1
SEE ALSO
augtool(1)
Augeas project homepage <https://www.augeas.net/>
Augeas path expressions <https://github.com/hercules-team/augeas/wiki/Path-expressions>