Config::Scoped.3pm

Langue: en

Autres versions - même langue

Version: 2008-04-09 (ubuntu - 07/07/09)

Section: 3 (Bibliothèques de fonctions)

NAME

Config::Scoped - feature rich configuration file parser

SYNOPSIS

   use Config::Scoped;
   $parser = Config::Scoped->new( file => 'foo.cfg' );
   $config = $parser->parse;
 
   $parser->store_cache( cache => 'foo.cfg.dump' );
 
 

just a string to parse in one rush

   $config =
     Config::Scoped->new->parse(
       text => "foo bar { baz = 1 }" );
 
 

retrieve a previously parsed cfg cache:

   $cfg =
     Config::Scoped->new->retrieve_cache(
       cache => 'foo.cfg.dump' );
 
   $cfg = Config::Scoped->new(
       file     => 'foo.cfg',
       warnings => 'off'
   )->retrieve_cache;
 
 

ABSTRACT

Config::Scoped is a configuration file parser for complex configuration files based on Parse::RecDescent. Files similar to the ISC named or ISC dhcpd configurations are possible. In order to be fast a precompiled grammar and optionally a config cache is used.

REQUIRES

Parse::RecDescent, Error

DESCRIPTION

Config::Scoped has the following highlights as a configuration file parser:
Complex recursive datastructures to any extent with scalars, lists and hashes as elements,
As a subset parses any complex Perl datastructures (no references and globs) without do or require,
Include files with recursion checks,
Controlled macro expansion in double quoted tokens,
Lexically scoped parameter assignments and pragma directives,
Perl quote like constructs to any extent, '', "", and here docs <<,
Perl code evaluation in Safe compartments,
Caching and restore with MD5 checks to determine alterations in the original config files,
Standard macro, parameter, declaration redefinition validation, may be overridden to validate on semantic knowledge,
Standard file permission and ownership safety validation, may be overridden,
Fine control for redefiniton warnings with pragma's and other safety checks,
Easy inheritable, may be subclassed to build parsers with specialized validation features,
Condoning syntax checker, semicolons and or commas are not always necessary to finish a statement or a list item if the end can be guessed by other means like newlines, closing brackets, braces etc.,
Well spotted messages for syntax errors even within include files with correct line numbers and file names,
Exception based error handling,
etc.,

CONFIG FILE FORMAT

The configuration file consists of different statements formed by tokens and literals. The file is a free-form ASCII text file and may contain extra tabs and newlines for formatting purposes.

TOKENS

A token consists of anything other than white space, curly braces ``{}'', brackets ``[]'', less and greater ``<>'', a semicolon ``;'', a comma ``,'', an equal '=', a pound '%' or a hash sign ``#'' or single and double quotes. If a token contains one of these characters it has to be quoted.

Definition from the corresponding grammar file:

     token : /[^ \s >< }{ )( [\] ; , ' " = # % ]+/x
 
 

QUOTING

Tokens delimited by single or double quotes work much like quoted literals in regular perl. Double quoted tokens are subject to macro expansion and backslash interpolation. Text in here-docs is treated as double quoted unless the delimiter is ''. Example:

     foo     = 'bar baz';
     bar     = "\tA\tB\tC\n";
     baz     = "\Uconvert to uppercase till \\E\E";
     goof    = "_MACRO_ expansion in double quoted tokens!";
 
 

The interpolation of double quoted strings is done by an "reval()" in the Safe compartment since it's possible to smuggle subroutine calls in a double quoted string:

     trojan = "localtime is: ${\(scalar localtime)}";
 
 

See below for full featured code evalaution.

PERL CODE EVALUATION

A perl code evaluation consists of the keyword "perl_code" or for short "eval" followed by a block in curly braces "{}". The value returned is the value of the last expression evaluated; a return statement may be also used, just as with subroutines. The expression providing the return value is evaluated in scalar context:

     start = eval { localtime };
     list  = eval { [ 1 .. 42 ] };
     hash  = perl_code { \%SIG };
     stop  = eval { localtime };
 
     foo   = eval {  warn 'foo,' if $debug; return 'bar'};
 
 

Perl code eval may be placed anywhere within the file where a token is expected, not only as a RHS of a parameter assigment:

     eval { 'foo' } eval { 'bar' }{
         is = baz;
     };
 
     lists = [ eval{ [ 1 .. 5 ] }, eval{ [ 10 .. 50 ] } ];
 
 

The code is evaluated in a Safe compartment. The compartment may be supplied to the new() method or a default compartment is created via "Safe->new()".

Macro expansion is done just before the code is evaluated. The whole expression string between the curly braces is subject to macro expansion, even without double quotes! Example:

     %macro INT_IF 'eth1,eth2,eth3';
 
     filter {
         internal_ifaces = eval { [INT_IF] };
         rule = "-o  INT_IF -j REJECT";
     }
 
 

is expanded to:

     $config = {
         'filter' => {
             'rule'            => '-o  eth1,eth2,eth3 -j REJECT',
             'internal_ifaces' => [ 'eth1', 'eth2', 'eth3' ]
         }
     };
 
 

COMMENTS

Comments may be placed anywhere within the file where a statement is allowed. Comments begin with the # character and end at the end of the line.

STATEMENTS

The file essentially consists of a list of statements. Statements fall into three broad categories - pragmas, parameters and declarations.

PARAMETERS

Parameters consist of the parameter name and value, separated by '='. In order to be able to parse perl datastructures '=>' is also allowed as a separator. A parameter is terminated by a semicolon ``;'' or newline.

The name consist of a token whereas the value consist of a token or a list of values or a hash which can contain other parameters. Lists and hashes are recursive in any combination and to any depth:

     scalar = bar;
     list = [ bar, baz ];
     hash = { bar = baz, goofed = spoofed };
 
     lol = [ [ foo, bar, baz ], [ 1, 2 ], [ red, green, blue ] ];
     hol = { color = [ red, green, blue ], goof = [ foo, bar, baz ] };
     loh = [ { bar = baz }, { goof = spoof } ];
 
 

DECLARATIONS

Declarations consist of declaration name(s) followed by a "block", a list of parameters and pragmas in curly braces "{}":
     devices rtr001 {
         variables = [ ifInOctets, ifOutOctets ];
         oids      = {
             ifInOctets  = 1.3.6.1.2.1.2.2.1.10;
             ifOutOctets = 1.3.6.1.2.1.2.2.1.16;
         };
         ports = [ 1, 2, 8, 9 ];
       }
 
 

Declarations inherit all parameters, macro definitions and warning settings from the current scope. Parameter and macro assigments and warning directives are lexically scoped within these declaration block. The declaration names are used as a key chain in the global config hash to store the parameter hash:

   $config->{decl_name_1}{decl_...}{decl_name_n} = {parameter hash}
 
 

Parameters and macros may be redefined within the declaration block, but see the %warnings directive below.

BLOCKS

blocks can be used to group some statements together and to give defaults for some parameters for following declarations enclosed by this block. Blocks consist of a list of "statements" in curly braces "{}". Blocks can be nested to any depth.
         {
             # defaults, lexically scoped
             community = public;
             variables = [ ifInOctets, ifOutOctets ];
             oids = {
                 ifInOctets  = 1.3.6.1.2.1.2.2.1.10;
                 ifOutOctets = 1.3.6.1.2.1.2.2.1.16;
             };
 
             %warnings parameter off;    ### allow parameter redefinition
 
             devices rtr001 {
                 ports = [ 1, 2, 8, 9 ];
             }
 
             devices rtr007 {
                 community = 'really top secret!';
                 ports = [ 1, 2, 3, 4 ];
             }
         }
 
 

Scopes

Blocks, declarations and hashes start new scopes. Parameter and macro assigments and warning directives are lexically scoped within these blocks. The blocks and declarations inherit all parameter assignments in outer scopes whereas a hash starts with an empty parameter hash since hashes are itself parameters. Parameters and macros may be redefined within each block, but see the %warnings directive below.

Global scope

Parameters outside a block or declaration are global. Only if there is no declaration in the config file they are accessible via the _GLOBAL auto declaration in the config hash:

         param1 = foo;
         param2 = [ 1, 2, 3, ];
         param3 = { a => hash };
 
 

results in the following perl datastructure:

         '_GLOBAL' => {
             'param1' => 'foo',
             'param2' => [ '1', '2', '3' ],
             'param3' => { 'a' => 'hash' },
           }
 
 

This allows very simple config files just with parameters and without declarations.

PRAGMAS

Pragmas consist of macro definitions, include and warnings directives:

"%macro macro_name macro_value;"

A macro consists of the keyword %macro followed by a name and a value separated by whitespace. Macros may be placed anywhere within the file where a statement is allowed. Macro's are lexically scoped within the blocks, declarations and hashes. They are expanded within ANY double quoted token and in perl_eval blocks with or without any quotes:

     %macro _FOO_ 'expand me';
 
     param1 = _FOO_;                                 # not expanded
     param2 = '_FOO_ not expanded, single quoted';
     param3 = "_FOO_ expanded, double quoted";
 
     "_FOO_ in name" = 'macro\'s within ANY "" are expanded!';
 
     param4 = <<HERE_DOC
     _FOO_: expanded, here docs without quotes are double quote like
     HERE_DOC
 
     param5 = <<'HERE_DOC'
     _FOO_: single quoted, not expanded
     HERE_DOC
 
     param6 = <<"HERE_DOC"
     _FOO_: double quoted, expanded
     HERE_DOC
         
     %macro "_FOO_ again" 'believe me: in ANY double quoted token!';
 
     # in eval blocks quotes doesn't matter for expansion!
     unquot = eval { _FOO_  . ' in eval just before evaluation!' };
     anyway = eval {
         _FOO_ . ' _FOO_ ' . "_FOO_ " . 'with or without quotes!'
     };
 
 

"%include path;"

The include directive starts with the keyword %include followed by a path. This directive may only be placed on file scope or within blocks, but not within other statements like declarations.

Parameters and macros in the included files are imported to the current scope. If this is not intended the %include pragma must be put inside a block {}. Warnings are always scoped within the include files and don't leak to the parent file.

Pathnames are absolute or relative to the dirname of the current configuration file. Example:

     ####
     # in configuration file /etc/myapp/global.cfg
     #
     %include shared.cfg
 
 

includes the file /etc/myapp/shared.cfg.

When parsing a string the path is relative to the current working directory.

Include files are handled by a cloned parser.

"%warnings [name] off|on;"

The warnings directive starts with the keyword %warnings followed by an optional name and the switch on or off. Warning directives may be placed anywhere within the file where a statement is allowed. They are lexically scoped to the current block. The following warning names are predefined (expandable):

     declaration
     digests
     macro
     parameter
     permissions
 
 

Warning directives allow fine control of the validation process within the configuration file. Example:

     param1 = default
     foo { param2 = something };
     bar { param1 = special; param2 = "doesn't matter" }
 
 

stop's with a Config::Scoped::Error::Validate::Parameter exception:

     "parameter redefinition for 'param1' at ... "
 
 

and with a proper %warnings directive a redefinition is possible:

     param1 = default
     foo { param2 = something };
     bar {
         %warnings parameter off;
         param1 = special;
         param2 = "doesn't matter";
       }
 
 

See also the methods new() and set_warnings() for object wide settings. Different warning names are possible just by naming them and may be used by subclassed validation methods.

EXPORTS

Nothing.

CONSTRUCTOR

Config::Scoped->new()

May take a set of named parameters as key => value pairs. Returns a Config::Scoped parser object or throws Config::Scoped::Error::... exceptions on error.
     my $parser = Config::Scoped->new(
         file      => '/etc/appl/foo.cfg',
         lc        => 1,
         safe      => $your_compartment,
         your_item => $your_value,
 
         # global warnings control
         warnings => {
             permissions => 'on',
             digest      => 'on',
             declaration => 'on',
             macro       => 'off',
             parameter   => 'off',
             your_name   => 'on',
         },
       )
 
 
file => $cfg_file
Optional, without a configuration file the parse() method needs a string to parse.
lc => true|false
Optional, if true converts all declaration and parameter names to lowercase. Default is false.
safe => $compartment
Safe compartment, optional. Defaults to a Safe compartment with no extra shares and the :default operator tag.
warnings => $warnings
Redefiniton and other safety warnings, defaults to all 'on'. The value is either just a literal 'on' or 'off' or a hashref with finer control.
   warnings => 'off'  # all warnings 'off'
 
   # all 'on', except for macro and an appl. defined your_name
   warnings => { macro => 'off', your_name => 'off' }
 
 

May be overridden by warnings pragmas in the config file. Warnings are relativ to the scopes of definition.

your_item => $your_value
Any unknown key => value pair is also stored unaltered in the object. Please use a special prefix for subclass object data (subclass_prefix_key => $value) not to override the existing one. With this scheme perhaps you don't need to override the new() constructor.

OBJECT METHODS

$parser->parse()

Parses the config file or string and returns the config hash. Throws Config::Scoped::Error::... exceptions on error.
     # cfg file
     $config = $parser->parse;
 
     # cfg string
     $config = $parser->parse( text => $cfg_text );
 
 

Should be called only once per parser object since some per parser state hashes are filled during a parse.

May take one named parameter if the object was constructed without the file argument.

text => $string_to_parse
The config file to parse in one string.

$parser->warnings_on()

Returns true if warnings are enabled for $item (macro, parameter, declaration, permissions, ...). May be used in the different (possibly overridden) validation methods.
     $parser->warnings_on(
         name     => $item,
     );
 
 

May take a set of named parameters as key => value pairs:

name => $item>
Mandatory, the name of the questionable warnings switch. The following names are predefined (expandable):
     declaration
     digests
     macro
     parameter
     permissions
 
 

Different warning names are possible just by naming them and may be used by subclassed validation methods.

$parser->set_warnings()

Set the warnings switch in the global scope for $item (macro, parameter, declaration, permissions, ...).
     $parser->set_warnings(
         name     => $item,
         switch   => 'on',       # or 'off'
     );
 
 

May take a set of named parameters as key => value pairs:

name => $item>
The name of the questionable warnings switch. Optional, defaults to 'all'. The following names are predefined (expandable):
     declaration
     digests
     macro
     parameter
     permissions
 
 

Different warning names are possible just by naming them and may be used by subclassed validation methods.

switch => 'on|off'>
Enable 'on' or disable 'off' the warning.

$parser->store_cache()

Store the cfg hash and the digests of the cfg files on disk for later fast retrieval.
     $parser->store_cache( cache => $cache_file, );
 
 

May take one named parameter:

cache => $filename>
Cache file, optional. Defaults to ``${cfg_file}.dump''.

$parser->retrieve_cache()

Retrieve the cfg hash. Checks if the file is safe via $parser->permissions_validate() and if the digests of the original config file (and possible included files) have changed since last storage. The warnings flags 'digests' and/or 'permissions' may be switched off to retrieve the cache without any checks.
     $config = $parser->retrieve_cache( cache => $cache_file, );
 
 

May take one named parameter:

cache => $filename>
Cache file, optional. Defaults to ``${cfg_file}.dump''.

INHERITANCE

Config::Scoped is a general configuration file parser with some rudimentary validation checks. When special validation hooks are needed, the following methods should be overridden through subclassing or just redefined in the Config::Scoped package. The original methods must be studied before redefining them:

$parser->macro_validate()

Validates a macro, returns the value unaltered or throws a Config::Scoped::Error::Validate::Macro exception. Checks for macro redefinition unless warnings for macros are off in the current scope. This method may be overridden to perform different validations. The method has the following interface:
     $parser->macro_validate(
         name     => $macro_name,
         value    => $macro_value,
     );
 
 

Example:

     %macro FOO "expand me"
 
 

yields to the following validation parameters:

     $parser->macro_validate(
         name     => 'FOO'
         value    => 'expand me',
     );
 
 

$parser->parameter_validate()

Validates a parameter, returns the value unaltered or throws a Config::Scoped::Error::Validate::Parameter exception. Checks for redefinition unless warnings for parameters are off in the current scope. This method may be overridden to perform different validations. The method has the following interface:
     $parser->parameter_validate(
         name     => $param_name,
         value    => $param_value,
     );
 
 

Example:

     passphrase = "This is very insecure"
 
 

yields to the following validation parameters:

     $parser->parameter_validate(
         name     => 'passphrase',
         value    => 'This is very insecure',
     );
 
 

$parser->declaration_validate()

Validates a declaration, returns the value unaltered or throws a Config::Scoped::Error::Validate::Declaration exception. Checks for declaration redefinition unless warnings for declarations are off in the current scope. This method may be overridden to perform different validations. The method has the following interface:
     $parser->declaration_validate(
         name     => $names_arrayref,
         value    => $params_ref,
         tail     => $config_tail,
     );
 
 

Example:

     foo bar baz { a = 1; b = 2; }
 
 

yields to the following validation parameters:

     $parser->declaration_validate(
         name     => [ 'foo', 'bar', 'baz' ],
         value    => { 'a' => '1'; 'b' => '2' },
         tail     => $thisparser->{local}{config}{foo}{bar}{baz},
       )
 
 

$parser->permissions_validate()

Checks for owner and permission safety unless warnings for permissions are off in the current scope. The owner of the cfg_file (and any included file) must be either the real uid or superuser and no one but owner may write to it. Must throw a Config::Scoped::Error::Validate::Permissions exception otherwise. This method may be overridden to perform different safety checks if necessary. The method has the following interface:
     $parser->permissions_validate( handle => $fh );
 
 

or

     $parser->permissions_validate( file => $file_name );
 
 

SEE ALSO

Parse::RecDescent, Safe, Error, Config::Scoped::Error, ``Quote-Like Operators'' in perlop

TODO

Parse::RecDescent Patch
Convince Damian Conway to apply the P::RD patch in the next release. The patch is used in this package to enable inheritance for precompiled grammar packages. P::RD works fine with inheritance but not the precompiled packages. In the precompiled packages the one-argument form of bless() is used, this is the main problem. I patched P::RD to create inheritable precompiled packages from the grammar files. This does NOT mean you have to patch YOUR P::RD installation! The patch is only necessary to create the Config::Scoped::Precomp package from the grammar file. If someone likes to play with the grammar, use the patched R::RD in this distribution. I sent the patch to Damian but didn't get a reply. This geek is just to busy.
TESTS
Still More tests needed.
Documentation
This documentation must be rewritten by a native speaker, volunteers welcome.

BUGS

If you find parser bugs, please send the stripped down config file and additional version information to the author.

CREDITS

Inspired by the application specific configuration file parser of the ToGather project, written by Rainer Bawidamann. Danke Rainer.

AUTHOR

Karl Gaissmaier <karl.gaissmaier at uni-ulm.de> Copyright (c) 2004-2008 by Karl Gaissmaier

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.