1Config::Augeas(3) User Contributed Perl Documentation Config::Augeas(3)
2
6 Config::Augeas - Edit configuration files through Augeas C library
7
9 use Config::Augeas;
10 my $aug = Config::Augeas->new( root => $aug_root ) ;
12 my $ret = $aug->get("/files/etc/hosts/1/ipaddr") ;
14 $aug->set("/files/etc/hosts/2/ipaddr","192.168.0.1") ;
15 my @a = $aug->match("/files/etc/hosts/") ;
17 my $nb = $aug->count_match("/files/etc/hosts/") ;
19 $aug->save ;
21
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 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 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
41 Creates a new Config::Augeas object. Optional parameters are:
42 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 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 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 type_check => 1
61 Typecheck lenses; since it can be very expensive it is not done by
62 default.
63 no_std_inc
65 Do not use the builtin load path for modules
66 no_load
68 Do not load the tree from AUG_INIT
69
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 If "expr" is omitted, the variable "name" will be removed if it is
77 defined.
78 Path variables can be used in path expressions later on by prefixing
80 them with '$'.
81 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 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 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 Returns undef on error
96 Returns an array containing:
98 • the number of nodes in the nodeset
100 • 1 if a node was created, and 0 if it already existed.
102 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 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 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 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 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 "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 Return 1 on success, and 0 if the insertion fails.
134 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 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 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 Returns 1 in case of success, 0 otherwise.
151 rename ( src, dest )
153 Rename the label of all nodes matching "src" to "lbl".
154 Returns the number of nodes renamed on success and -1 on failure.
156 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 Example:
163 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 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 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 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 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 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 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 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 When init is first called, it populates "/augeas/load" with the
207 transforms marked for autoloading in all the modules it finds.
208 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 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 print ( [ path , [ file ] ] )
218 Print each node matching "path" and its descendants on STDOUT or in a
219 file
220 The second parameter can be :
222 • A file name.
224 • Omitted. In this case, print to STDOUT
226 If path is omitted, all Augeas nodes will be printed.
228 Example:
230 $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 WARNING: The parameter order is reversed compared to Augeas C API.
236 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 The second parameter can be :
243 • A file name.
245 • Omitted. In this case, print to STDOUT
247 The function returns the number of executed commands on success, and 0
249 otherwise.
250
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 error_message
258 Return a human-readable message for the error code.
259 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 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
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
276 • http://augeas.net/ : Augeas project page
277 • Config::Model : Another kind of configuration editor (with optional
279 GUI and advanced validation).
280 • Config::Augeas::Validator : A unit test framework for configuration
282 files.
283 • Config::Augeas::Exporter : A module to export the Augeas tree to
285 various formats.
286 • Augeas mailing list: http://augeas.net/developers.html
288 • Source repository: https://github.com/raphink/config-augeas
290
292 • Dominique Dumont, <ddumont at cpan dot org@<gt>
293 • Raphael Pinson, <raphink at cpan dot org@<gt>
295
297 • Copyright (C) 2008-2010 by Dominique Dumont
298 • Copyright (C) 2011-2012 by Raphael Pinson
300 This library is free software; you can redistribute it and/or modify it
302 under the LGPL terms.
303perl v5.34.0 2022-01-21 Config::Augeas(3)