Config::Augeas - Edit configuration files through Augeas C library
use Config::Augeas; my $aug = Config::Augeas->new( root => $aug_root ) ; my $ret = $aug->get("/files/etc/hosts/1/ipaddr") ; $aug->set("/files/etc/hosts/2/ipaddr","192.168.0.1") ; my @a = $aug->match("/files/etc/hosts/") ; my $nb = $aug->count_match("/files/etc/hosts/") ; $aug->save ;
Augeas is a library and command line tool that focuses on the most basic problem in handling Linux configurations programmatically: editing actual configuration files in a controlled manner.
To that end, Augeas exposes a tree of all configuration settings (well, all the ones it knows about) and a simple local API for manipulating the tree. Augeas then modifies underlying configuration files according to the changes that have been made to the tree; it does as little modeling of configurations as possible, and focuses exclusively on transforming the tree-oriented syntax of its public API to the myriad syntaxes of individual configuration files.
This module provides an object oriented Perl interface for Augeas configuration edition library with a more "perlish" API than Augeas C counterpart.
Creates a new Config::Augeas object. Optional parameters are:
a colon-spearated list of directories that lenses should be searched in. This is in addition to the standard load path and the directories in specified AUGEAS_LENS_LIB environment variable.
AUGEAS_LENS_LIB
Use root as the filesystem root. If not specified, use the value of the environment variable AUGEAS_ROOT. If that doesn't exist either, use "/".
root
AUGEAS_ROOT
/
Specify how to save the configuration file. Either create a newfile (with extension .augnew, and do not overwrite the original file) or move the original file into a backup file (.augsave extension). noop make saves a no-op process, just record what would have changed
.augnew
.augsave
noop
Typecheck lenses; since it can be very expensive it is not done by default.
Do not use the builtin load path for modules
Do not load the tree from AUG_INIT
Define a variable name whose value is the result of evaluating expr. If a variable name already exists, its name will be replaced with the result of evaluating expr.
name
expr
If expr is omitted, the variable name will be removed if it is defined.
Path variables can be used in path expressions later on by prefixing them with '$'.
Returns -1 on error; on success, returns 0 if expr evaluates to anything other than a nodeset, and the number of nodes if expr evaluates to a nodeset
Define a variable name whose value is the result of evaluating expr, which must evaluate to a nodeset. If a variable name already exists, its name will be replaced with the result of evaluating expr.
If expr evaluates to an empty nodeset, a node is created, equivalent to calling set( expr, value) and name will be the nodeset containing that single node.
set( expr, value)
Returns undef on error
Returns an array containing:
the number of nodes in the nodeset
1 if a node was created, and 0 if it already existed.
Lookup the value associated with path. Returns the value associated with path if path matches exactly one node. If PATH matches no nodes or more than one node, returns undef.
path
Set the value associated with path to value. value is copied into Augeas internal data structure. Intermediate entries are created if they don't exist. Return 1 on success, 0 on error. It is an error if more than one node matches path.
value
Use the value of node node as a string and transform it into a tree using the lens lens and store it in the tree at path, which will be overwritten. path and node are path expressions.
node
lens
Transform the tree at path into a string using lens lens and store it in the node node_out, assuming the tree was initially generated using the value of node node_in. path, node_in, and node_out are path expressions.
node_out
node_in
Create a new sibling label for path by inserting into the tree just before or just after path.
label
path must match exactly one existing node in the tree, and label must be a label, i.e. not contain a '/', '*' or end with a bracketed index '[N]'.
Return 1 on success, and 0 if the insertion fails.
Remove path and all its children. Returns the number of entries removed. All nodes that match path, and their descendants, are removed. (remove can also be called with rm)
remove
rm
Move the node SRC to DST. SRC must match exactly one node in the tree. DST must either match exactly one node in the tree, or may not exist yet. If DST exists already, it and all its descendants are deleted. If DST does not exist yet, it and all its missing ancestors are created.
Note that the node SRC always becomes the node DST: when you move /a/b to /x, the node /a/b is now called /x, no matter whether /x existed initially or not. (move can also be called with mv)
/a/b
/x
move
mv
Returns 1 in case of success, 0 otherwise.
Rename the label of all nodes matching src to lbl.
src
lbl
Returns the number of nodes renamed on success and -1 on failure.
Returns a hash containing the filename, label_start, label_end, value_start, value_end, span_start and span_end of the given path.
filename
label_start
label_end
value_start
value_end
span_start
span_end
Example:
my $span = $aug->span('/files/etc/passwd/root') ; # If filename is undefined, there are no valid span information for this node if ($span->{filename}) { print "Found root in passwd at character $span->{span_start}\n" ; }
WARNING: You must check that $span->{filename} is defined. If it isn't, the node has no span information and all other values in the hash are wrong.
Returns an array of the elements that match of the path expression pattern. The returned paths are sufficiently qualified to make sure that they match exactly one node in the current tree.
pattern
Same as match but return the number of matching element in manner more efficient than using scalar match( pattern )
scalar match( pattern )
Write all pending changes to disk. Return 0 if an error is encountered, 1 on success. Only files that had any changes made to them are written. save will follow backup files as specified with Config::Augeas::new backup parameter.
save
backup
Load files into the tree. Which files to load and what lenses to use on them is specified under /augeas/load in the tree; each entry /augeas/load/NAME specifies a 'transform', by having itself exactly one child 'lens' and any number of children labelled 'incl' and 'excl'. The value of NAME has no meaning.
/augeas/load
/augeas/load/NAME
The 'lens' grandchild of /augeas/load specifies which lens to use, and can either be the fully qualified name of a lens 'Module.lens' or '@Module'. The latter form means that the lens from the transform marked for autoloading in MODULE should be used.
@Module
MODULE
The 'incl' and 'excl' grandchildren of /augeas/load indicate which files to transform. Their value are used as glob patterns. Any file that matches at least one 'incl' pattern and no 'excl' pattern is transformed. The order of 'incl' and 'excl' entries is irrelevant.
When init is first called, it populates /augeas/load with the transforms marked for autoloading in all the modules it finds.
Before loading any files, load will remove everything underneath /augeas/files and /files, regardless of whether any entries have been modified or not.
load
/augeas/files
/files
Returns 0 on error, 1 on success. Note that success includes the case where some files could not be loaded. Details of such files can be found as '/augeas//error'.
/augeas//error
Print each node matching path and its descendants on STDOUT or in a file
The second parameter can be :
A file name.
Omitted. In this case, print to STDOUT
If path is omitted, all Augeas nodes will be printed.
$aug->print ; # print all nodes to STDOUT $aug->print('/files') ; # print all file nodes to STDOUT $aug->print('/augeas/','bar.txt'); # print Augeas meta data in bar.txt
WARNING: The parameter order is reversed compared to Augeas C API.
Run one or more newline-separated commands listed in text. Running just help will print what commands are available. Commands accepted by this are identical to what augtool accepts.
text
help
The function returns the number of executed commands on success, and 0 otherwise.
Returns the error code from the last API call as a short string: noerror, nomem, internal, pathx, nomatch, manymatch, syntax, nolens, multiple_transforms
Return a human-readable message for the error code.
Return a human-readable message elaborating the error code; might be undef. For example, when the error code is pathx, this will explain how the path expression is invalid.
pathx
Return details about the error, which might be undef. For example, for pathx, indicates where in the path expression the error occurred. The returned value can only be used until the next API call
Object oriented design would suggest to use a new class to represent Augeas errors, but this would stray too far from current Augeas design and API.
http://augeas.net/ : Augeas project page
Config::Model : Another kind of configuration editor (with optional GUI and advanced validation).
Config::Augeas::Validator : A unit test framework for configuration files.
Config::Augeas::Exporter : A module to export the Augeas tree to various formats.
Augeas mailing list: http://augeas.net/developers.html
Source repository: https://github.com/raphink/config-augeas
Dominique Dumont, <ddumont at cpan dot org@<gt>
Raphael Pinson, <raphink at cpan dot org@<gt>
Copyright (C) 2008-2010 by Dominique Dumont
Copyright (C) 2011-2012 by Raphael Pinson
This library is free software; you can redistribute it and/or modify it under the LGPL terms.
To install Config::Augeas, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Config::Augeas
CPAN shell
perl -MCPAN -e shell install Config::Augeas
For more information on module installation, please visit the detailed CPAN module installation guide.