Config::Augeas man page on Pidora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Pidora logo
[printable version]

Config::Augeas(3)     User Contributed Perl Documentation    Config::Augeas(3)

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 variable "AUGEAS_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 evaluating
       "expr". If a variable "name" already exists, its name will be replaced
       with the result of evaluating "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

   defnode ( name, expr, value )
       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.

       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
       with "path" if "path" 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" 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".

   insert ( label, before | after , path )
       Create a new sibling "label" for "path" by inserting into the tree just
       before or just after "path".

       "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 )
       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")

   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 with "mv")

       Returns 1 in case of success, 0 otherwise.

   span ( path )
       Returns a hash containing the "filename", "label_start", "label_end",
       "value_start", "value_end", "span_start" and "span_end" of the given
       "path".

       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::new
       "backup" 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 in "MODULE" 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
       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.

       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
       just "help" 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 call

CAVEATS
       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.

perl v5.14.2			  2012-03-19		     Config::Augeas(3)
[top]

List of man pages available for Pidora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net