view release on metacpan or  search on metacpan

lib/Config/Nested.pm  view on Meta::CPAN

#! /usr/bin/env perl

=head1 NAME

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

=head1 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;

=head1 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.

=head1 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.

=head1 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: