|
Parse::PerlConfig - parse a configuration file written in Perl |
Parse::PerlConfig - parse a configuration file written in Perl
use Parse::PerlConfig;
my $parsed = Parse::PerlConfig::parse(
File => "/etc/perlapp/conf",
Handlers => [\%config, \&config],
);
This module is useful for parsing a configuration file written in Perl and
obtaining the values defined therein. This is achieved through the parse()
function, which creates a namespace, reads in Perl code, evals it, and then
examines the namespace's symbol table. Symbols are then processed into a
hash and returned.
The parse() function is exportable upon request.
Parsing is not a simple do(``filename''). Instead the filenames specified are opened, read, eval'd, and closed. The justification for this being twofold:
do(``file'') searches @INC.
Parsing (in this manner) requires a namespace. By default, the namespace is constructed by appending Namespace_Base to a unique identifier (currently, an encoded version of the filename, but don't rely on this). You can override this behaviour by specifying an explicit Namespace argument.
Prior to eval'ing the contents of a configuration file the lexical hash %parse_perl_config is initialized with several keys (documented below); if a Lexicals argument was given each of the lexicals specified are initialized.
There are a few caveats; lexicals specified in the Lexicals argument cannot override %parse_perl_config; keys specified in Lexicals cannot be code references, because code references cannot currently be reliably reconstructed; modifications to %parse_perl_config keys (other than Error, documented below) are discouraged, as the results are not defined.
The %parse_perl_config hash contains the following keys:
Once the namespace has been setup, and the code eval'd, it is then parse()'s job to go through the namespace's symbol table and look for ``things''. What it looks for depends on the Thing_Order and Symbols arguments.
After that, handlers are updated, and a hash reference of what was parsed out is returned.
parse() takes a list of key-value pairs as its arguments and adds them to an
argument hash. If the first argument to parse() is a hash or array
reference, it is dereferenced and used as if it were specified as a list.
All elements following this argument are added to the arguments hash, and
they override any settings specified by the reference.
This means the call:
parse(
{ Files => "/home/me/config.conf", Error_default => 'fwarn' },
Files => "/home/you/config.conf"
);
causes parse()'s argument hash to consist of the following (ignoring default settings):
Files => "/home/you/config.conf",
Error_default => "fwarn",
Simply replace the braces, {}, with brackets, [], and you get the same
result. This makes it convenient to store commonly-used arguments to
parse() in a hash or array, and efficiently pass these arguments to parse(),
while still allowing a seperate Files argument for each call.
The below itemization of parse()'s arguments describes key-value pairs. Each item consists of a key name and a description of the expected value for that key.
The value description requires some explanation.
A single pipe, ``|'', indicates alternative values; only one of the values must be specified.
Values bracketed with ``<'' and ``>'' indicate that value is not literal, but figurative. So, in the case of <coderef>, you must specify a code reference (a closure or reference to a named subroutine), not the literal string ``<coderef>''. Values without such bracketing are literal.
Braces, {}, indicate a hash reference is required; brackets, [], indicate an array reference is required.
Below each key-value description is a description of the default setting, followed by a description of what the argument means.
default: none, this argument is required
This is the file or files you wish to parse. If a file cannot be parsed for any reason the entire parse is not abandoned, the file is simply skipped (after calling an appropriate error handling function).
default: none
By default, parse() simply returns a hash reference of symbol names and
their values. Given a Handlers argument, parse() will add key-value pairs
to each hash reference specified, and call each code reference specified
with a single argument, the hash reference it returns.
default: none
The key-value pairs in the specified hashref are made into lexical variables in the configuration eval. See the section on Parsing for further information.
default: '$@%&i*'
Specifies the default thing order for symbols parsed from each configuration file. See the section Things for further information.
default: false
If set to any true value the filehandle opened on the configuration file is
untainted before evaling the code contained therein. Because this involves
loading IO::Handle, which involves quite a bit of code, the option is turned
off by default. You will get taint exceptions if you don't specify this
option while running in -T mode.
Also, as the namespace is currently constructed, having a tainted filename will cause the namespace name to be tainted, so it is also untainted. In the case of an explicitly specified Namespace value, it will also be untainted.
No other values are untainted. This includes any key-value pairs specified
by the Lexicals argument; you must untaint those yourself, since there is no
reasonable way for parse() to determine how best to untaint them.
default: empty hashref
This is an override for the Thing_Order argument above. The keys in the specified hashref are symbols you want parsed specially, the values the thing order (either a string or array reference). See the section Things for further information regarding thing order.
default: generated from Namespace_Base and a unique identifier
This option explicitly specifies the namespace the files are parsed in. See the section Parsing for further information.
default: Parse::PerlConfig::ConfigFile
Unless the Namespace argument is specified, the namespace a file is parsed in is generated by appending a cleaned up version of the filename to this setting. See the section Parsing for further information.
``Things'' (as taken from the Perl documentation, regarding the *foo{THING} syntax) are the Perl datatypes. These include scalars, arrays, hashes, subroutines, IO handles, and globs.
Anywhere a ``things'' argument is required you can specify one of two things;
a string containing the special ``thing'' characters, or an array reference of
each thing's actual name. The thing characters are as follows: $ for
scalar, % for a hash, @ for an array, & for a subroutine, i for
an IO handle, and * for a glob. The full name for each coincides with
the full name for each datatype in their respective glob slots: SCALAR for a
scalar, HASH for a hash, ARRAY for an array, CODE for a subroutine, IO for
an IO handle, and GLOB for a glob.
parse() takes various Error_* and Warn_* arguments that determine how it
handles any problems it encounters. Each argument can take one of several
values.
$^W is set to a true value.
$^W's value.
die() or warn()).
There are various handler arguments. Unless otherwise specified, the default handler is used (Error_default's or Warn_default's value).
default: noop
The default warning handler.
default: warn
The default error handler.
Due to the fact that the scalar slot in a glob is always filled it is not
possible to distinguish from a scalar that was never defined (e.g. @foo
was, but $foo was never mentioned) from one that is simply undef.
Because of this, for example, if you have a thing order of $@ and code
along the lines of $foo = undef; @foo = (); the 'foo' key of the hash
will be an array reference, despite there being a scalar and $ coming
first in the thing order.
t/parse/symbols.t, t/parse/multi-file.t, t/parse/namespace.t
Michael Fowler <michael@shoebox.net>
|
Parse::PerlConfig - parse a configuration file written in Perl |