|
NAMEParse::PerlConfig - parse a configuration file written in PerlSYNOPSISuse Parse::PerlConfig; my $parsed = Parse::PerlConfig::parse( File => "/etc/perlapp/conf", Handlers => [\%config, \&config], ); DESCRIPTIONThis 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.ExportThe parse() function is exportable upon request.ParsingParsing is not a simple do("filename"). Instead the filenames specified are opened, read, eval'd, and closed. The justification for this being twofold:
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. The parse subroutineArgumentsparse() 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.
Things"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. Exception Handlingparse() takes various Error_* and Warn_* arguments that determine how it handles any problems it encounters. Each argument can take one of several values.
There are various handler arguments. Unless otherwise specified, the default handler is used (Error_default's or Warn_default's value).
BUGSDue 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.TODOt/parse/symbols.t, t/parse/multi-file.t, t/parse/namespace.tAUTHORMichael Fowler <michael@shoebox.net>
Visit the GSP FreeBSD Man Page Interface. |