/ 
Config-Nested-2.0.1
River stage zero No dependents
/ Config::Nested

NAME

Config::Nested - parse a configuration file consiging of nested blocks and sections.

SYNOPSIS

use Config::Nested; use Data::Dumper;

my $c = new Config::Nested( section => [qw( location animal)], boolean => [qw( happy hungry alive)], variable => [qw( sex name colour ) ], array => 'breed exercise owner', hash => 'path', );

$c->parseFile($ARGV[0]) || die "failed to parse!\n";

my @list = $c->section('animal'); print Dumper(\@list;

DESCRIPTION

Config::Nested is a configuration file parser based on brace delimited blocks and named sections. Section, variable and boolean names are predefined.

The result are configuration section hash objects corresponding to the declared sections in the configuration string/file. Each hash contains all the configuration information that is in scope at the end of its block. The hash objects also contain an element '+' that is an array of (section-name, value) pairs tracking which sections contain the current configuration.

Array and hash variables accumumlate values as they proceed into deeper and deeper blocks. When the block ends, arrays and hashes revert back to their original value in the outer block.

The format is similar (but not idenical) to the ISC named or ISC dhcpd configuration files. It is also similar to the configuration supported by the perl module Config::Scoped except that sections can be nested and arrays do not have to be enclosed by []. Consequently the syntax is simpler and the data structures are less complicated.

CONFIG FILE FORMAT

config: <statements>
statements: section, block, assignemnts, lists
section: <section> <value> [{ statements }]?
block: { statements }
hash: <hash-name> <value> <value>
array: <array-name> <values>
assignments: <variable> [=|+=|.=]? <value>
boolean: [*!]?<boolean-variable>

The section, array, variable and booleans names are all specified prior to parsing the configuration file.

Comments start with a # and continue to the end of the line.

The scope of each object is the enclosing block, section or file.

Each variable name must be unique when declared for the configuration. However unique abbreviations are allowed within the configuration.

EXAMPLE CONFIG FILE

Suppose 'location' and 'animal' are decalred as sections; 'owner', 'name' and 'sex' as scalars; and 'path' as an array. Consider the following configuration:

    owner George
    path step1
    location home {
        animal fish 
        {
            name Fred
            sex male
        }

        animal dog
        {
            name Fido
	    sex  female
    	    path step2
        }
    }

This data would create 1 location configuration hash and 2 animal configuration hashes; each contains all the configuration information that is in scope at the end of it's block.

In particular, the last animal configuration hash looks like:

{
  '+'        => [ [ 'location', 'home' ], [ 'animal', 'dog' ] ],
  'age'      => '',
  'animal'   => 'dog',
  'location' => 'home',
  'name'     => 'Fido',
  'owner'    => 'George',
  'path'     => ['step1', 'step2' ],
  'sex'      => 'female'
 }

EXPORTS

Nothing.

FUNCTIONS

$parser = Config::Nested->new( options )

$parser->configure( options )

Construct a new Config::Nested object; arguments can be listed as key => value pairs. The keys are

section

The allowed section names. In the configuration file, each section name is followed by a value.

array

The allowed array names. In the configuration file, each array name is followed by a space separated list of values. The default is the empty array.

hash

The allowed hash names. In the configuration file, each hash name is followed by a space separated pair of values. The first value is the key and the seconds its valuse in the hash. The default is the empty array.

boolean

The allowed boolean names. In the configuration file, each boolean appears as just the work (set to 1), preceded by ! (set to 0) or * (set to 1). The default is 0 (false).

==item variable

The allowed variable names. In the configuration file, each variable can be followed by a single value or by the operations = (assign), += (increment) or .= (append) and a single value. The default is the empty string ''.

The data in a configuration hash can be accessed via the declared name (i.e. $obj->{name}). Booleans take the value 0 or 1, declared arrays are Perl arrays, sections and variables are just scalers. Every name is present in the hash even if it has not been defined.

$parser->initialise()

Clear all the keywords from the parser.

$conf = $parser->autoConfigure($conf)

Configure the parser from the configuration string, $conf. Lines that start with an @ are special and are removed before returning the resulting string.

Lines of the form

  • @section <sections>

  • @array <array names>

  • @boolean <booleans>

  • @variable <variables>

all cause the corresponding configuration action for the parser.

Lines of the form

  • @defaults <variables>

are fed to the parser as configuration strings and act to set defaults.

$parser->reset()

Clear all the parsed data from the parser.

$parser->sections()

Return the allowed section names.

$parser->section("section")

Return the current array of parsed sections.

$parser->parse( string )

$parser->parseFile( file )

These parse the configuration string and files respectively.

SEE ALSO

Parse::RecDescent, Config::Scoped.