view release on metacpan or  search on metacpan

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

To retrieve a node, address it using its I<full path>, i.e. list of statement
names that lead to this node. For example, in this simple configuration file:

   [core]
       filemode = true

the path of the C<filemode> statement is C<qw(core filemode)>. 

=head1 CONSTRUCTOR
    
    $cfg = new Config::AST(%opts);

Creates new configuration parser object.  Valid options are:

=over 4

=item B<debug> => I<NUM>

Sets debug verbosity level.    

=item B<ci> => B<0> | B<1>

If B<1>, enables case-insensitive keyword matching.  Default is B<0>,
i.e. the keywords are case-sensitive.    

=item B<lexicon> => \%hash

Defines the I<keyword lexicon>.
    
=back    

=head3 Keyword lexicon

The hash reference passed via the B<lexicon> keyword defines the keywords
and sections allowed within a configuration file.  In a simplest case, a
keyword is described as

    name => 1

This means that B<name> is a valid keyword, but does not imply anything
about its properties.  A more complex declaration is possible, in
which the value is a hash reference, containing one or more of the following
keywords:

=over 4

=item mandatory => 0 | 1

Whether or not this setting is mandatory.

=item default => I<VALUE>

Default value for the setting. This value will be assigned if that particular
statement is not explicitly used in the configuration file. If I<VALUE>
is a CODE reference, it will be invoked as a method each time the value is
accessed.

Default values must be pure Perl values (not the values that should appear
in the configuration file). They are not processed using the B<check>
callbacks (see below).    
    
=item array => 0 | 1

If B<1>, the value of the setting is an array.  Each subsequent occurrence
of the statement appends its value to the end of the array.

=item re => I<regexp>

Defines a regular expression which the value must match. If it does not,
a syntax error will be reported.

=item select => I<coderef>

Reference to a method which will be called in order to decide whether to
apply this hash to a particular configuration setting.  The method is
called as 

    $self->$coderef($node, @path)

where $node is the B<Config::AST::Node::Value> object (use
B<$vref-E<gt>value>, to obtain the actual value), and B<@path> is its pathname.
    
=item check => I<coderef>

Defines a method which will be called after parsing the statement in order to
verify its value.  The I<coderef> is called as

    $self->$coderef($valref, $prev_value, $locus)

where B<$valref> is a reference to its value, and B<$prev_value> is the
value of the previous instance of this setting.  The function must return
B<true>, if the value is OK for that setting.  In that case, it is allowed
to modify the value referenced by B<$valref>.  If the value is erroneous,
the function must issue an appropriate error message using B<$cfg-E<gt>error>,
and return 0.
    
=back    

In taint mode, any value that matched B<re> expression or passed the B<check>
function will be automatically untainted.
        
To define a section, use the B<section> keyword, e.g.:

    core => {
        section => {
            pidfile => {
               mandatory => 1
            },
            verbose => {
               re => qr/^(?:on|off)/i
            }
        }
    }

This says that the section named B<core> can have two variables: B<pidfile>,
which is mandatory, and B<verbose>, whose value must be B<on>, or B<off>
(case-insensitive). E.g.:

    [core]
        pidfile = /run/ast.pid