1Config::Augeas(3)     User Contributed Perl Documentation    Config::Augeas(3)
2
3
4

NAME

6       Config::Augeas - Edit configuration files through Augeas C library
7

SYNOPSIS

9         use Config::Augeas;
10
11         my $aug = Config::Augeas->new( root => $aug_root ) ;
12
13         my $ret = $aug->get("/files/etc/hosts/1/ipaddr") ;
14         $aug->set("/files/etc/hosts/2/ipaddr","192.168.0.1") ;
15
16         my @a = $aug->match("/files/etc/hosts/") ;
17
18         my $nb = $aug->count_match("/files/etc/hosts/") ;
19
20         $aug->save ;
21

DESCRIPTION

23       Augeas is a library and command line tool that focuses on the most
24       basic problem in handling Linux configurations programmatically:
25       editing actual configuration files in a controlled manner.
26
27       To that end, Augeas exposes a tree of all configuration settings (well,
28       all the ones it knows about) and a simple local API for manipulating
29       the tree. Augeas then modifies underlying configuration files according
30       to the changes that have been made to the tree; it does as little
31       modeling of configurations as possible, and focuses exclusively on
32       transforming the tree-oriented syntax of its public API to the myriad
33       syntaxes of individual configuration files.
34
35       This module provides an object oriented Perl interface for Augeas
36       configuration edition library with a more "perlish" API than Augeas C
37       counterpart.
38

Constructor

new ( ... )

41       Creates a new Config::Augeas object. Optional parameters are:
42
43       loadpath
44           a colon-spearated list of directories that lenses should be
45           searched in. This is in addition to the standard load path and the
46           directories in specified "AUGEAS_LENS_LIB" environment variable.
47
48       root
49           Use "root" as the filesystem root. If not specified, use the value
50           of the environment variable "AUGEAS_ROOT". If that doesn't exist
51           either, use ""/"".
52
53       save => backup | newfile | noop
54           Specify how to save the configuration file. Either create a newfile
55           (with extension ".augnew", and do not overwrite the original file)
56           or move the original file into a backup file (".augsave"
57           extension).  "noop" make saves a no-op process, just record what
58           would have changed
59
60       type_check => 1
61           Typecheck lenses; since it can be very expensive it is not done by
62           default.
63
64       no_std_inc
65           Do not use the builtin load path for modules
66
67       no_load
68           Do not load the tree from AUG_INIT
69

Methods

71   defvar( name, [ expr ])
72       Define a variable "name" whose value is the result of evaluating
73       "expr". If a variable "name" already exists, its name will be replaced
74       with the result of evaluating "expr".
75
76       If "expr" is omitted, the variable "name" will be removed if it is
77       defined.
78
79       Path variables can be used in path expressions later on by prefixing
80       them with '$'.
81
82       Returns -1 on error; on success, returns 0 if "expr" evaluates to
83       anything other than a nodeset, and the number of nodes if "expr"
84       evaluates to a nodeset
85
86   defnode ( name, expr, value )
87       Define a variable "name" whose value is the result of evaluating
88       "expr", which must evaluate to a nodeset. If a variable "name" already
89       exists, its name will be replaced with the result of evaluating "expr".
90
91       If "expr" evaluates to an empty nodeset, a node is created, equivalent
92       to calling "set( expr, value)" and "name" will be the nodeset
93       containing that single node.
94
95       Returns undef on error
96
97       Returns an array containing:
98
99       •   the number of nodes in the nodeset
100
101       •   1 if a node was created, and 0 if it already existed.
102
103   get( path )
104       Lookup the value associated with "path". Returns the value associated
105       with "path" if "path" matches exactly one node. If PATH matches no
106       nodes or more than one node, returns undef.
107
108   set ( path, value )
109       Set the value associated with "path" to "value". "value" is copied into
110       Augeas internal data structure. Intermediate entries are created if
111       they don't exist. Return 1 on success, 0 on error. It is an error if
112       more than one node matches "path".
113
114   text_store ( lens, node, path )
115       Use the value of node "node" as a string and transform it into a tree
116       using the lens "lens" and store it in the tree at "path", which will be
117       overwritten. "path" and "node" are path expressions.
118
119   text_retrieve ( lens, node_in, path, node_out )
120       Transform the tree at "path" into a string using lens "lens" and store
121       it in the node "node_out", assuming the tree was initially generated
122       using the value of node "node_in". "path", "node_in", and "node_out"
123       are path expressions.
124
125   insert ( label, before | after , path )
126       Create a new sibling "label" for "path" by inserting into the tree just
127       before or just after "path".
128
129       "path" must match exactly one existing node in the tree, and "label"
130       must be a label, i.e. not contain a '/', '*' or end with a bracketed
131       index '[N]'.
132
133       Return 1 on success, and 0 if the insertion fails.
134
135   remove ( path )
136       Remove path and all its children. Returns the number of entries
137       removed.  All nodes that match "path", and their descendants, are
138       removed. ("remove" can also be called with "rm")
139
140   move ( src, dest )
141       Move the node SRC to DST. SRC must match exactly one node in the tree.
142       DST must either match exactly one node in the tree, or may not exist
143       yet. If DST exists already, it and all its descendants are deleted. If
144       DST does not exist yet, it and all its missing ancestors are created.
145
146       Note that the node SRC always becomes the node DST: when you move
147       "/a/b" to "/x", the node "/a/b" is now called "/x", no matter whether
148       "/x" existed initially or not. ("move" can also be called with "mv")
149
150       Returns 1 in case of success, 0 otherwise.
151
152   rename ( src, dest )
153       Rename the label of all nodes matching "src" to "lbl".
154
155       Returns the number of nodes renamed on success and -1 on failure.
156
157   span ( path )
158       Returns a hash containing the "filename", "label_start", "label_end",
159       "value_start", "value_end", "span_start" and "span_end" of the given
160       "path".
161
162       Example:
163
164         my $span = $aug->span('/files/etc/passwd/root') ;
165         # If filename is undefined, there are no valid span information for this node
166         if ($span->{filename}) {
167            print "Found root in passwd at character $span->{span_start}\n" ;
168         }
169
170       WARNING: You must check that $span->{filename} is defined. If it isn't,
171       the node has no span information and all other values in the hash are
172       wrong.
173
174   match ( pattern )
175       Returns an array of the elements that match of the path expression
176       "pattern". The returned paths are sufficiently qualified to make sure
177       that they match exactly one node in the current tree.
178
179   count_match ( pattern )
180       Same as match but return the number of matching element in manner more
181       efficient than using "scalar match( pattern )"
182
183   save
184       Write all pending changes to disk. Return 0 if an error is encountered,
185       1 on success. Only files that had any changes made to them are written.
186       "save" will follow backup files as specified with Config::Augeas::new
187       "backup" parameter.
188
189   load
190       Load files into the tree. Which files to load and what lenses to use on
191       them is specified under "/augeas/load" in the tree; each entry
192       "/augeas/load/NAME" specifies a 'transform', by having itself exactly
193       one child 'lens' and any number of children labelled 'incl' and 'excl'.
194       The value of NAME has no meaning.
195
196       The 'lens' grandchild of "/augeas/load" specifies which lens to use,
197       and can either be the fully qualified name of a lens 'Module.lens' or
198       '@Module'. The latter form means that the lens from the transform
199       marked for autoloading in "MODULE" should be used.
200
201       The 'incl' and 'excl' grandchildren of "/augeas/load" indicate which
202       files to transform. Their value are used as glob patterns. Any file
203       that matches at least one 'incl' pattern and no 'excl' pattern is
204       transformed. The order of 'incl' and 'excl' entries is irrelevant.
205
206       When init is first called, it populates "/augeas/load" with the
207       transforms marked for autoloading in all the modules it finds.
208
209       Before loading any files, "load" will remove everything underneath
210       "/augeas/files" and "/files", regardless of whether any entries have
211       been modified or not.
212
213       Returns 0 on error, 1 on success. Note that success includes the case
214       where some files could not be loaded. Details of such files can be
215       found as '"/augeas//error"'.
216
217   print ( [ path  , [ file ] ] )
218       Print each node matching "path" and its descendants on STDOUT or in a
219       file
220
221       The second parameter can be :
222
223       •   A file name.
224
225       •   Omitted. In this case, print to STDOUT
226
227       If path is omitted, all Augeas nodes will be printed.
228
229       Example:
230
231         $aug->print ; # print all nodes to STDOUT
232         $aug->print('/files') ; # print all file nodes to STDOUT
233         $aug->print('/augeas/','bar.txt'); # print Augeas meta data in bar.txt
234
235       WARNING: The parameter order is reversed compared to Augeas C API.
236
237   srun ( [ text  , [ file ] ] )
238       Run one or more newline-separated commands listed in "text".  Running
239       just "help" will print what commands are available.  Commands accepted
240       by this are identical to what augtool accepts.
241
242       The second parameter can be :
243
244       •   A file name.
245
246       •   Omitted. In this case, print to STDOUT
247
248       The function returns the number of executed commands on success, and 0
249       otherwise.
250

Error reporting

252   error
253       Returns the error code from the last API call as a short string:
254       noerror, nomem, internal, pathx, nomatch, manymatch, syntax, nolens,
255       multiple_transforms
256
257   error_message
258       Return a human-readable message for the error code.
259
260   error_minor_message
261       Return a human-readable message elaborating the error code; might be
262       undef. For example, when the error code is "pathx", this will explain
263       how the path expression is invalid.
264
265   error_details
266       Return details about the error, which might be undef. For example, for
267       "pathx", indicates where in the path expression the error occurred. The
268       returned value can only be used until the next API call
269

CAVEATS

271       Object oriented design would suggest to use a new class to represent
272       Augeas errors, but this would stray too far from current Augeas design
273       and API.
274

SEE ALSO

276http://augeas.net/ : Augeas project page
277
278       •   Config::Model : Another kind of configuration editor (with optional
279           GUI and advanced validation).
280
281       •   Config::Augeas::Validator : A unit test framework for configuration
282           files.
283
284       •   Config::Augeas::Exporter : A module to export the Augeas tree to
285           various formats.
286
287       •   Augeas mailing list: http://augeas.net/developers.html
288
289       •   Source repository: https://github.com/raphink/config-augeas
290

AUTHORS

292       •   Dominique Dumont, <ddumont at cpan dot org@<gt>
293
294       •   Raphael Pinson, <raphink at cpan dot org@<gt>
295
297       •   Copyright (C) 2008-2010 by Dominique Dumont
298
299       •   Copyright (C) 2011-2012 by Raphael Pinson
300
301       This library is free software; you can redistribute it and/or modify it
302       under the LGPL terms.
303
304
305
306perl v5.36.0                      2022-07-22                 Config::Augeas(3)
Impressum