Config::Scoped - feature rich configuration file parser
use Config::Scoped;
$compartment = new Safe 'YOUR_SHARE';
$warnings = 'off'; # or 'on'
$warnings = { declaration => 'off', # or 'on'
digests => 'off',
macro => 'off',
parameter => 'off',
permissions => 'off',
your_warning => 'off' };
$parser = new Config::Scoped file => $config_file,
lc => $lc,
safe => $compartment,
warnings => $warnings,
your_key => $your_value;
$config = $parser->parse;
$config = $parser->parse(text => $config_string);
$parser->set_warnings(name => $name,
switch => 'on'); # or 'off'
$parser->warnings_on(name => $name) and ...
$parser->store_cache;
$parser->store_cache (cache => $file);
$parser->retrieve_cache;
$parser->retrieve_cache(cache => $file);
Config::Scoped is a configuration file parser.
eval, do or require
''), double quotes(""), and here docs (<<EOF)
Safe compartments
Parse::RecDescent-based parser; precompiled grammar for speed
Parse::RecDescent
Error
Nothing.
new Config::Scoped
file => $config_file,
lc => $lc,
safe => $compartment,
warnings => $warnings,
your_key => $your_value [, ...]
Creates and returns a new Config::Scoped object.
All parameters are optional.
$config_file is the configuration file to parse.
If $config_file is omitted,
then a $config_string must be provided to the parse method (see below).
If $lc is true, all declaration and parameter names will be converted to lower case.
$compartment is a Safe compartment for evaluating Perl code blocks in the configuration file.
Defaults to a Safe compartment with no extra shares and the :default operator tag.
$warnings may be
'on' or 'off'
All warnings are on by default.
Arbitrary key/value pairs may be passed to the constructor, and will be stored in the $parser object. This is useful primarily to subclasses.
parse
parse(text => $config_string)
Parses the configuration and returns a reference to the config hash.
The first form parses the $config_file that was provided to the constructor.
If $config_file was not provided to the constructor, this form dies.
The second form parses the $config_string.
This method should only be called once.
set_warnings(name => $name, switch => 'on')
set_warnings(name => $name, switch => 'off')
warnings_on(name => $name)
store_cache(cache => $cache_file)
store_cache
Stores the config hash on disk for rapid retrieval. If $config_file was provided to the constructor, then the stored form includes checksums of $config_file and any included files.
The first form writes to $cache_file.
The second form writes to $config_file.dump.
If $config_file was not provided to the constructor, the second form dies.
retrieve_cache(cache => $cache_file)
retrieve_cache
Retrieves the $config hash from a file that was created by store_cache.
The first form reads $cache_file.
The second form reads $config_file.dump.
If $config_file was not provided to the constructor, the second form dies.
The stored file is subject to digests and permissions checks.
All methods die on error.
Config::Scoped::Error defines a hierarchy of classes that represent
Config::Scoped errors. When a method detects an error, it creates
an instance of the corresponding class and throws it. The error
classes are all subclasses of Config::Scoped::Error. See
Config::Scoped::Error for the complete list.
If the exception is not caught, the program terminates, and
Config::Scoped prints the config file name and line number where
the error was detected to STDERR.
Config::Scoped reads configuration files.
If we have a config file
% cat host.cfg
host
{
name = cpan.org
port = 22
}
%
we can read it into Perl with code like
$parser = new Config::Scoped file => host.cfg; $config = $parser->parse;
The resulting $config is always a hash ref.
We'll call this the config hash, and write
$config = {
host => { name => 'cpan.org',
port => 22 }
}
to show its contents.
Fundamentally, Config::Scoped is a way to specify the contents of the config hash.
As shown in the /SYNOPSIS, Config::Scoped can obtain a
configuration from a $config_file, passed to the constructor, or
from a $config_string, passed to the parse method. For
simplicity, we'll talk about parsing configuration files,
distinguishing configuration strings only when necessary.
Config files are free-form ascii text.
Comments begin with #, and extend to the end of the line.
The top-level elements of a config file are called declarations. A declaration consists of a name, followed by a block
foo
{
}
bar
{
}
The declaration names become keys in the config hash. The value of each key is another hash ref. The config shown above parses to
$config = {
foo => { },
bar => { }
}
You can create additional levels in the config hash simply by listing successive declaration names before the block. This config
dog hound
{
}
dog beagle
{
}
cat
{
}
parses to
$config = {
dog => { hound => { },
beagle => { } },
cat => { }
}
Declarations may not be nested.
The ultimate purpose of a configuration file is to provide data values for a program. These values are specified by parameters. Parameters have the form
name = value
and go inside declaration blocks. The
name = value
parameters in a spec file become
$name => $value
pairs inside the declaration hashes in Perl code. For example, this configuration
dog
{
legs = 4
wings = 0
}
bird
{
legs = 2
wings = 2
}
parses to
$config = {
dog => { legs => 4,
wings => 0 },
bird => { legs => 2,
wings => 2 }
}
Parameter values can be scalars, lists or hashes. Scalar values may be numbers or strings
shape = square sides = 4
Lists values are enclosed in square brackets
colors = [ red green blue ] primes = [ 2 3 5 7 11 13 ]
Hash values are enclosed in curly brackets
capitals = { England => London
France => Paris }
A hash value is also called a hash block.
Lists and hashes can be nested to arbitrary depth
Europe
{
currency = euro
cities = { England => [ London Birmingham Liverpool ]
France => [ Paris Canne Calais ] }
}
parses to
$config = {
Europe => {
currency => 'euro',
cities => { England => [ 'London', 'Birmingham', 'Liverpool' ],
France => [ 'Paris', 'Canne', 'Calais' ] }
}
}
The Config::Scoped data syntax is similar to the Perl data syntax,
and Config::Scoped will parse many Perl data structures. In
general, Config::Scoped requires less punctuation that Perl. Note
that Config::Scoped allows arrow (=>) or equals (=)
between hash keys and values, but not comma (,)
capitals = { England => London # OK
France = Paris # OK
Germany , Berlin # error
}
If a config file contains no declarations at all
name = cpan.org port = 22
then any parameters will be placed in a _GLOBAL declaration in the
config hash
$config = {
_GLOBAL => { name = cpan.org
port = 22 }
}
This allows very simple config files with just parameters and no declarations.
Each declaration block in a config file creates a lexical scope. Parameters inside a declaration are scoped to that block.
Parameters are inherited by all following declarations within their scope. If all your animals have four legs, you can save some typing by writing
legs = 4
cat {}
dog {}
which parses to
$config = {
cat => { legs => 4 }
dog => { legs => 4 }
}
If some of your animals have two legs, you can create additional scopes with anonymous blocks to control inheritance
{
legs = 4
cat {}
dog {}
}
{
legs = 2
bird {}
}
parses to
$config = {
cat => { legs => 4 }
dog => { legs => 4 }
bird => { legs => 2 }
}
Anonymous blocks may be nested.
Each hash block also creates a scope. The hash does not inherit parameters from outside its own scope.
If you can't express what you need within the Config::Scoped
syntax, your escape hatch is
eval { ... }
This does a Perl eval on the block,
and replaces the construct with the results of the eval.
start = eval { localtime }
foo = eval { warn 'foo,' if $debug; return 'bar' }
The block is evaluated in scalar context. However, it may return a list or hash reference, and the underlying list or hash can become a parameter value. For example
a
{
list = eval { [ 1 .. 3 ] }
hash = eval { { a => 1, b => 2, c => 3 } }
}
parses to
$config = {
a => { list => [ 1, 2, 3 ],
hash => { a => 1, b => 2, c => 3 }
}
The block is evaluated inside the parser's Safe compartment.
Variables can be made available to the eval by sharing them with
the compartment. To set the $debug variable in the example above, do
$compartment = new Safe 'MY_SHARE'; $MY_SHARE::debug = 1; $parser = new Config::Scoped file => 'config.txt', safe => $compartment; $config = $parser->parse;
Only global variables can be shared with a compartment; lexical variables cannot.
perl_code is a synonym for eval.
A token is a
Any token may be quoted. Tokens that contain special characters must be quoted. The special characters are
\s {} [] <> () ; , ' " = # %
Config::Scoped uses the Perl quoting syntax.
Tokens may be quoted with either single or double quotes
a = 'New York' b = "New Jersey\n"
Here-docs are supported
a = <<EOT New York New Jersey EOT
but generalized quotes (q(), qq(), etc.) are not. Text in
here-docs is regarded as single-quoted if the delimiter is enclosed in
single quotes, and double-quoted if the delimiter is enclosed in
double quotes or unquoted.
Double-quoted tokens are evaluated as Perl strings inside the parser's
Safe compartment. They are subject to the usual Perl backslash and
variable interpolation, as well as macro expansion. Variables to be
interpolated are passed via the Safe compartment, as shown above in
/Perl code evaluation. If you need a literal $ or @ in a
double-quoted string, be sure to escape it with a backslash (\) to
suppress interpolation.
An
eval { ... }
may appear anywhere that a token is expected. For example
a
{
eval { 'b' . 'c' } = 1
}
parses to
$config = { a => { bc => 1 } }
Config::Scoped has three directives: %macro, %warning, and
%include.
Config::Scoped supports macros.
A macro is defined with
%macro name value
Macros may be defined
Macros defined within blocks are lexically scoped to those blocks.
Macro substitution occurs
eval blocks
Config::Scoped supports include files.
To include one config file within another, write
%include path/to/file
%include directives may appear
In particular, %include directives may not appear within
declaration blocks or hash blocks.
Parameters and macros in include files are imported to the current scope. You can control this scope with an anonymous block
{
%include dog.cfg
dog { } # sees imports from dog.cfg
}
bird { } # does not see imports from dog.cfg
Warnings are scoped to the included file and do not leak to the parent file.
Pathnames are either
For example, this config
# in configuration file /etc/myapp/global.cfg
%include shared.cfg
includes the file /etc/myapp/shared.cfg. When parsing a configuration string, the path is relative to the current working directory.
Include files are not actually included as text.
Rather, they are processed by a recursive call to Config::Scoped.
Subclass implementers may need to be aware of this.
Config::Scoped can check for five problems with config files
The API refers to these as "warnings", but they are actually errors, and if they occur, the parse fails and throws an exception. For consistency with the API, we'll use the term "warning" in the POD.
The five warnings are identified by five predefined warning names
declaration
parameter
macro
permissions
digests
The permissions check requires that the config file
These restrictions help prevent an attacker from subverting a program by altering its config files.
The store_cache method computes MD5 checksums for the config file and all included files.
These checksums are stored with the cached configuration.
The retrieve_cache method recomputes the checksums of the files and compares them to the stored values.
The digests check requires that the checksums agree.
This helps prevent programs from relying on stale configuration caches.
All warnings are enabled by default.
Warnings can be disabled by passing the warning key to the constructor,
as shown in the /SYNOPSIS,
or with the set_warnings method.
Warnings can also be controlled with the %warnings directive, which has the form
%warnings [name] off|on
A %warnings directive applies to the named warning,
or to all warnings, if name is omitted.
%warnings directives allow warnings to be turned on and off as
necessary throughout the config file. A %warnings directive may
appear
Each %warnings directive is lexically scoped to its enclosing file or block.
Example
legs = 4
cat {}
dog {}
bird
{
legs = 2
}
fails with a duplicate parameter warning, but
legs = 4
cat {}
dog {}
bird
{
%warnings parameter off;
legs = 2
}
successfully parses to
$config = {
cat => { legs => 4 }
dog => { legs => 4 }
bird => { legs => 2 }
}
As with all things Perl, there's more than one way to write configuration files. Here are some suggestions for writing config files that are concise, readable, and maintainable.
Config::Scoped accepts most Perl data syntax.
This allows Perl data to pulled into config files largely unaltered
foo
{
a = 1;
b = [ 'red', 'green', 'blue' ];
c = { x => 5,
y => 6 };
}
However, Config::Scoped doesn't require as much punctuation as Perl,
and config files written from scratch will be cleaner without it
foo
{
a = 1
b = [ red green blue ]
c = { x => 5
y => 6 }
}
Don't use anonymous blocks unless you need to restrict the scope of something. In particular, there is no need for a top-level anonymous block around the whole config file
{ # unnecessary
foo { }
}
Parameters that are outside of a declaration are inherited by all following declarations in their scope. Don't do this unless you mean it
wheels = 4
car
{
# OK
}
cat
{
# I can haz weelz?
}
Config::Scoped has four different kinds of blocks
eval
They all look the same, but they aren't, and they have different rules and restrictions. See /CONFIG FILE FORMAT for descriptions of each.
Macros are evil, and Config::Scoped macros are specially evil,
because
Caveat scriptor.
Config::Scoped has no formally defined subclass interface. Here are
some guidelines for writing subclasses. Implementers who override (or
redefine) base class methods may need to read the Config::Scoped
sources for more information.
Arbitrary
$key => $value
pairs may be passed to the Config::Scoped constructor. They will be
stored in the $parser object, and methods may access them with code
like
$parser->{local}{$key}
To avoid conflict with existing keys in the local hash,
consider distinguishing your keys with a unique prefix.
Arbitrary warning names may be defined, set with new and
set_warnings, used in %warnings directives, and tested with
warnings_on. Methods can call warnings_on to find out whether a
warning is currently enabled.
All methods throw exceptions (die) on error. The exception object
should be a subclass of Config::Scoped::Error. You can use one of
the classes defined in Config::Scoped::Error, or you can derive
your own. This code
throw Config::Scoped::Error -file => $parser->_get_file(%args),
-line => $parser->_get_line(%args),
-text => $message;
will generate an error message that reports the location in the config file where the error was detected, rather than a location in Perl code.
Config::Scoped performs validation checks on the elements of
configuration files (declarations, parameters, macros, etc). Here are
the interfaces to the validation methods. Subclasses can override
these methods to modify or extend the validation checks.
macro_validate(name => $name, value => $value)
Called for each %macro directive.
Receives the $name and $value from the directive. The returned $macro_value becomes the actual value of the macro.
If the macro is invalid,
throws a Config::Scoped::Error::Validate::Macro exception.
parameter_validate(name => $name, value => $value)
Called for each parameter definition.
Receives the $name and $value from the definition. The returned $param_value becomes the actual value of the parameter.
If the parameter is invalid,
throws a Config::Scoped::Error::Validate::Parameter exception.
declaration_validate(name => $name, value => $value, tail => $tail)
Called for each declaration.
$name is an array ref giving the chain of names for the declaration block. $value is a hash ref containing all the parameters in the declaration block. $tail is a hash ref containing all the parameters in any previously defined declaration with the same name(s).
For example, the declaration
foo bar baz { a=1 b=2 }
leads to the call
$parser->declaration_validate(name => [ qw(foo bar baz) ],
value => { a => '1', b => '2' },
tail => $parser->{local}{config}{foo}{bar}{baz});
The method can test %$tail to discover if there is an existing, non-empty declaration with the same name(s).
The method has no return value. However, the method can alter the contents of %$value. Upon return, the parameters in %$value become the actual contents of the declaration block.
If the declaration is invalid,
throws a Config::Scoped::Error::Validate::Declaration exception.
permissions_validate(file => $file, handle => $handle)
Called for the config file, each included file, and each retrieved cache file. One of $file or $handle will be non-null.
Throws a Config::Scoped::Error::Validate::Permissions exception if
the file is not safe to read.
Error
Safe
Config::Scoped::Error
Parse::RecDescent
Parse::RecDescent patch
Test if the P::RD patch is still needed for P::RD newer than 1.94.
The P::RD 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
wants to play with the grammar, use the patched R::RD in this
distribution.
If you find parser bugs, please send the stripped down config file and additional version information to the author.
Inspired by the application specific configuration file parser of the ToGather project, written by Rainer Bawidamann. Danke Rainer.
POD by Steven W. McDougall <swmcd@theworld.com>
Karl Gaissmaier <karl.gaissmaier at uni-ulm.de>
Copyright (c) 2004-2009 by Karl Gaissmaier
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.