-
-
06 Mar 2013 21:58:52 UTC
- Distribution: Config-Augeas
- Module version: 1.000
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Issues (1)
- Testers (602 / 1 / 1)
- Kwalitee
Bus factor: 1- % Coverage
- License: lgpl_2_1
- Activity
24 month- Tools
- Download (63.8KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 1 contributors- Raphaël Pinson (raphink at cpan dot org)
- Dependencies
- unknown
- Reverse dependencies
- CPAN Testers List
- Dependency graph
- NAME
- SYNOPSIS
- DESCRIPTION
- Constructor
- new ( ... )
- Methods
- defvar( name, [ expr ])
- defnode ( name, expr, value )
- get( path )
- set ( path, value )
- text_store ( lens, node, path )
- text_retrieve ( lens, node_in, path, node_out )
- insert ( label, before | after , path )
- remove ( path )
- move ( src, dest )
- rename ( src, dest )
- span ( path )
- match ( pattern )
- count_match ( pattern )
- save
- load
- print ( [ path , [ file ] ] )
- srun ( [ text , [ file ] ] )
- Error reporting
- CAVEATS
- SEE ALSO
- AUTHORS
- COPYRIGHT AND LICENSE
NAME
Config::Augeas - Edit configuration files through Augeas C library
SYNOPSIS
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 ;
DESCRIPTION
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.
Constructor
new ( ... )
Creates a new Config::Augeas object. Optional parameters are:
- loadpath
-
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. - root
-
Use
root
as the filesystem root. If not specified, use the value of the environment variableAUGEAS_ROOT
. If that doesn't exist either, use "/
". - save => backup | newfile | noop
-
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 - type_check => 1
-
Typecheck lenses; since it can be very expensive it is not done by default.
- no_std_inc
-
Do not use the builtin load path for modules
- no_load
-
Do not load the tree from AUG_INIT
Methods
defvar( name, [ expr ])
Define a variable
name
whose value is the result of evaluatingexpr
. If a variablename
already exists, its name will be replaced with the result of evaluatingexpr
.If
expr
is omitted, the variablename
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 ifexpr
evaluates to a nodesetdefnode ( name, expr, value )
Define a variable
name
whose value is the result of evaluatingexpr
, which must evaluate to a nodeset. If a variablename
already exists, its name will be replaced with the result of evaluatingexpr
.If
expr
evaluates to an empty nodeset, a node is created, equivalent to callingset( expr, value)
andname
will be the nodeset containing that single node.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.
get( path )
Lookup the value associated with
path
. Returns the value associated withpath
ifpath
matches exactly one node. If PATH matches no nodes or more than one node, returns undef.set ( path, value )
Set the value associated with
path
tovalue
.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 matchespath
.text_store ( lens, node, path )
Use the value of node
node
as a string and transform it into a tree using the lenslens
and store it in the tree atpath
, which will be overwritten.path
andnode
are path expressions.text_retrieve ( lens, node_in, path, node_out )
Transform the tree at
path
into a string using lenslens
and store it in the nodenode_out
, assuming the tree was initially generated using the value of nodenode_in
.path
,node_in
, andnode_out
are path expressions.insert ( label, before | after , path )
Create a new sibling
label
forpath
by inserting into the tree just before or just afterpath
.path
must match exactly one existing node in the tree, andlabel
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 )
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 withrm
)move ( src, dest )
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 withmv
)Returns 1 in case of success, 0 otherwise.
rename ( src, dest )
Rename the label of all nodes matching
src
tolbl
.Returns the number of nodes renamed on success and -1 on failure.
span ( path )
Returns a hash containing the
filename
,label_start
,label_end
,value_start
,value_end
,span_start
andspan_end
of the givenpath
.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.
match ( pattern )
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.count_match ( pattern )
Same as match but return the number of matching element in manner more efficient than using
scalar match( pattern )
save
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::newbackup
parameter.load
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.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 inMODULE
should be used.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.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
'.print ( [ path , [ file ] ] )
Print each node matching
path
and its descendants on STDOUT or in a fileThe second parameter can be :
A file name.
Omitted. In this case, print to STDOUT
If path is omitted, all Augeas nodes will be printed.
Example:
$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.
srun ( [ text , [ file ] ] )
Run one or more newline-separated commands listed in
text
. Running justhelp
will print what commands are available. Commands accepted by this are identical to what augtool accepts.The second parameter can be :
A file name.
Omitted. In this case, print to STDOUT
The function returns the number of executed commands on success, and 0 otherwise.
Error reporting
error
Returns the error code from the last API call as a short string: noerror, nomem, internal, pathx, nomatch, manymatch, syntax, nolens, multiple_transforms
error_message
Return a human-readable message for the error code.
error_minor_message
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.error_details
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 callCAVEATS
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.
SEE ALSO
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
AUTHORS
Dominique Dumont, <ddumont at cpan dot org@<gt>
Raphael Pinson, <raphink at cpan dot org@<gt>
COPYRIGHT AND LICENSE
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.
Module Install Instructions
To install Config::Augeas, copy and paste the appropriate command in to your terminal.
cpanm Config::Augeas
perl -MCPAN -e shell install Config::Augeas
For more information on module installation, please visit the detailed CPAN module installation guide.