logo
Free, unlimited AI code reviews that run on commit
git-lrc git-lrc GitHub Install Now We'd appreciate a star git-lrc - Free, unlimited AI code reviews that run on commit | Product Hunt git-lrc - Free, unlimited AI code reviews that run on commit | Product Hunt

augprint - create an idempotent augtool script for a given file

Contents

Author

       George Hansper <george@hansper.id.au>

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

   Regexpoutput
       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.

   LimitationsAppend-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.

       RepeatedValuesaugprint 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

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

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"

   Defaultoutput
       "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'

   Verboseoutput
       "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'
         ...

   Rexexpoutput
       "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, --lenslensname 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)

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

Name

       augprint - create an idempotent augtool script for a given file

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

       -ttargetfile, --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 targetfiletargetfile 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)

See Also

augtool(1)

       Augeas project homepage <https://www.augeas.net/>

       Augeas path expressions <https://github.com/hercules-team/augeas/wiki/Path-expressions>

Augeas 1.14.1                                      2023-07-14                                        AUGPRINT(1)

Synopsis

       augprint [--pretty|-p] [--regexp[=n]|-r[n]] [--noseq|-s] [--verbose|-v] [--lens name|-l name] [--target
       /target|-t /target] FILE

See Also

Man Pages
regexp Man Pages
Man Pages
bashreadline.bt Man Pages
← View User commands Category← Back to Scripting languages🙏  Credits & Acknowledgments