Config::Augeas(3pm)

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   insert ( label, before | after , path )
115       Create a new sibling "label" for "path" by inserting into the tree just
116       before or just after "path".
117
118       "path" must match exactly one existing node in the tree, and "label"
119       must be a label, i.e. not contain a '/', '*' or end with a bracketed
120       index '[N]'.
121
122       Return 1 on success, and 0 if the insertion fails.
123
124   remove ( path )
125       Remove path and all its children. Returns the number of entries
126       removed.  All nodes that match "path", and their descendants, are
127       removed. ("remove" can also be called with "rm")
128
129   move ( src, dest )
130       Move the node SRC to DST. SRC must match exactly one node in the tree.
131       DST must either match exactly one node in the tree, or may not exist
132       yet. If DST exists already, it and all its descendants are deleted. If
133       DST does not exist yet, it and all its missing ancestors are created.
134
135       Note that the node SRC always becomes the node DST: when you move
136       "/a/b" to "/x", the node "/a/b" is now called "/x", no matter whether
137       "/x" existed initially or not. ("move" can also be called with "mv")
138
139       Returns 1 in case of success, 0 otherwise.
140
141   match ( pattern )
142       Returns an array of the elements that match of the path expression
143       "pattern". The returned paths are sufficiently qualified to make sure
144       that they match exactly one node in the current tree.
145
146   count_match ( pattern )
147       Same as match but return the number of matching element in manner more
148       efficient than using "scalar match( pattern )"
149
150   save
151       Write all pending changes to disk. Return 0 if an error is encountered,
152       1 on success. Only files that had any changes made to them are written.
153       "save" will follow backup files as specified with Config::Augeas::new
154       "backup" parameter.
155
156   load
157       Load files into the tree. Which files to load and what lenses to use on
158       them is specified under "/augeas/load" in the tree; each entry
159       "/augeas/load/NAME" specifies a 'transform', by having itself exactly
160       one child 'lens' and any number of children labelled 'incl' and 'excl'.
161       The value of NAME has no meaning.
162
163       The 'lens' grandchild of "/augeas/load" specifies which lens to use,
164       and can either be the fully qualified name of a lens 'Module.lens' or
165       '@Module'. The latter form means that the lens from the transform
166       marked for autoloading in "MODULE" should be used.
167
168       The 'incl' and 'excl' grandchildren of "/augeas/load" indicate which
169       files to transform. Their value are used as glob patterns. Any file
170       that matches at least one 'incl' pattern and no 'excl' pattern is
171       transformed. The order of 'incl' and 'excl' entries is irrelevant.
172
173       When init is first called, it populates "/augeas/load" with the
174       transforms marked for autoloading in all the modules it finds.
175
176       Before loading any files, "load" will remove everything underneath
177       "/augeas/files" and "/files", regardless of whether any entries have
178       been modified or not.
179
180       Returns 0 on error, 1 on success. Note that success includes the case
181       where some files could not be loaded. Details of such files can be
182       found as '"/augeas//error"'.
183
184   print ( [ path  , [ file ] ] )
185       Print each node matching "path" and its descendants on STDOUT or in a
186       file
187
188       The second parameter can be :
189
190       ·   A file name.
191
192       ·   Omitted. In this case, print to STDOUT
193
194       If path is omitted, all Augeas nodes will be printed.
195
196       Example:
197
198         $aug->print ; # print all nodes to STDOUT
199         $aug->print('/files') ; # print all file nodes to STDOUT
200         $aug->print('/augeas/','bar.txt'); # print Augeas meta data in bar.txt
201
202       WARNING: The parameter order is reversed compared to Augeas C API.
203

Error reporting

205   error
206       Returns the error code from the last API call as a short string:
207       noerror, nomem, internal, pathx, nomatch, manymatch, syntax, nolens,
208       multiple_transforms
209
210   error_message
211       Return a human-readable message for the error code.
212
213   error_minor_message
214       Return a human-readable message elaborating the error code; might be
215       undef. For example, when the error code is "pathx", this will explain
216       how the path expression is invalid.
217
218   error_details
219       Return details about the error, which might be undef. For example, for
220       "pathx", indicates where in the path expression the error occurred. The
221       returned value can only be used until the next API call
222

CAVEATS

224       Object oriented design would suggest to use a new class to represent
225       Augeas errors, but this would stray too far from current Augeas design
226       and API.
227

AUTHOR

237       Dominique Dumont, <ddumont at cpan dot org@<gt>
238

COPYRIGHT AND LICENSE

240       Copyright (C) 2008-2010 by Dominique Dumont
241
242       This library is free software; you can redistribute it and/or modify it
243       under the LGPL terms.
244
245
246
247perl v5.12.0                      2010-04-30                 Config::Augeas(3)