NAME

SYNOPSIS

    my $cfg = new Config::AST(%opts);
    $cfg->parse() or die;
    $cfg->commit() or die;

    if ($cfg->is_set('core', 'variable')) {
       ...
    }

    my $x = $cfg->get('file', 'locking');

    $cfg->set('file', 'locking', 'true');

    $cfg->unset('file', 'locking');

DESCRIPTION

See Config::Parser module for an implementation of a parser based on this module.

A configuration file in general is supposed to consist of statements of two kinds: simple statements and sections. A simple statement declares or sets a configuration parameter. Examples of simple statements are:

    # Bind configuration file:
    file "cache/named.root";

    # Apache configuration file:
    ServerName example.com

    # Git configuration file:
    logallrefupdates = true

A section statement groups together a number of another statements. These can be simple statements, as well as another sections. Examples of sections are (with subordinate statements replaced with ellipsis):

    # Bind configuration file:
    zone "." {
       ...
    };

    # Apache configuration file:
    <VirtualHost *:80>
       ...
    </VirtualHost>

    # Git configuration file:
    [core]
       ...

The syntax of Git configuration file being one of the simplest, we will use it in the discussion below to illustrate various concepts.

The abstract syntax tree (AST) for a configuration file consists of nodes. Each node represents a single statement and carries detailed information about that statement, in particular:

locus

Location of the statement in the configuration. It is represented by an object of class Text::Locus.

order

0-based number reflecting position of this node in the parent section node.

value

For simple statements - the value of this statement.

subtree

For sections - the subtree below this section.

The type of each node can be determined using the following node attributes:

is_section

True if node is a section node.

is_value

True if node is a simple statement.

To retrieve a node, address it using its 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 "filemode" statement is "qw(core filemode)".

CONSTRUCTOR

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

Creates new configuration parser object. Valid options are:

debug => NUM

Sets debug verbosity level.

ci => 0 | 1

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

lexicon => \%hash

Defines the keyword lexicon.

Keyword lexicon

The hash reference passed via the 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 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:

mandatory => 0 | 1

Whether or not this setting is mandatory.

default => VALUE

Default value for the setting. This value will be assigned if that particular statement is not explicitly used in the configuration file. If 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 check callbacks (see below).

array => 0 | 1

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

re => regexp

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

select => 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 Config::AST::Node::Value object (use $vref->value, to obtain the actual value), and @path is its pathname.

check => coderef

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

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

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

In taint mode, any value that matched re expression or passed the check function will be automatically untainted.

To define a section, use the section keyword, e.g.:

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

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

    [core]
        pidfile = /run/ast.pid
        verbose = off

To accept arbitrary keywords, use *. For example, the following declares code section, which must have the pidfile setting and is allowed to have any other settings as well.

    code => {
       section => {
           pidfile => { mandatory => 1 },
           '*' => 1
       }
    }

Everything said above applies to the '*' as well. E.g. the following example declares the code section, which must have the pidfile setting and is allowed to have subsections with arbitrary settings.

    code => {
       section => {
           pidfile = { mandatory => 1 },
           '*' => {
               section => {
                   '*' => 1
               }
           }
       }
    }

The special entry

    '*' => '*'

means "any settings and any subsections are allowed".

PARSING

The caller must then perform the following operations

1. Create an instance of the derived class $cfg.

2. Call the $cfg->parse method.

3. On success, call the $cfg->commit method.

METHODS

NODE RETRIEVAL

    pidfile = /var/run/x.pid

has the path

    ( 'pidfile' )

The path of the pidfile statement in section core, e.g.:

    [core]
        pidfile = /var/run/x.pid

is

    ( 'core', 'pidfile' )

Similarly, the path of the file setting in the following configuration file:

    [item foo]
        file = bar

is ( 'item', 'foo', 'bar' )

    Returns the parse tree.

DIRECT ADDRESSING

    qw(foo bar baz)

one can write:

    $node = $cfg->foo->bar->baz

This statement is equivalent to

    $node = $cfg->getnode(qw(foo bar baz))

except that if the node in question does not exist, direct access returns a null node, and getnode returns "undef". Null node is a special node representing a missing node. Its is_null method returns true and it can be used in conditional context as a boolean value, e.g.:

    if (my $node = $cfg->foo->bar->baz) {
        $val = $node->value;
    }

Direct addressing is enabled only if lexicon is provided (either during creation of the object, or later, via the lexicon method).

Obviously, statements that have names coinciding with one of the methods of the Config::AST class (or any of its subclasses) can't be used in direct addressing. In other words, you can't have a top-level statement called "tree" and access it as

    $cfg->tree

This statement will always refer to the method tree of the Config::AST class.

Another possible problem when using direct access are keywords with dashes. Currently a kludge is implemented to make it possible to access such keywords: when looking for a matching keyword, double underscores compare equal to a single dash. For example, to retrieve the "qw(files temp-dir)" node, use

    $cfg->files->temp__dir;

CONSTRUCTING THE SYNTAX TREE

    $cfg->add_node(qw(core pidfile), $node)
    
    $cfg->add_node('core.pidfile', $node)

AUXILIARY METHODS

    [item foo]
       x = 1
    [item bar]
       x = 1
    [item baz]
       y = 2

    $cfg->names_of('item')

    ( 'foo', 'bar', 'baz' )

    use Config::AST qw(:sort);
    @array = $cfg->flatten(sort => SORT_PATH);

    ($newkey, $newvalue) = &{$map}($what, $key, $value)

    sub map {
        my ($what, $name, $val) = @_;
        if ($name eq 'section') {
            $val->{section} = {};
            $val = $val->{section};
        }
        ($name, $val);
    }

SEE ALSO

Config::Parser.