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

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)