Config::Grammar(3)          SmokePing          Config::Grammar(3)



NAME
       Config::Grammar - A grammar-based, user-friendly config
       parser

SYNOPSIS
        use Config::Grammar;

        my $parser = Config::Grammar->new(\%grammar);
        my $cfg = $parser->parse('app.cfg') or die "ERROR: $parser->{err}\n";
        my $pod = $parser->makepod();
        my $ex = $parser->maketmpl('TOP','SubNode');

DESCRIPTION
       Config::Grammar is a module to parse configuration files.
       The configuration may consist of multiple-level sections
       with assignments and tabular data. The parsed data will be
       returned as a hash containing the whole configuration.
       Config::Grammar uses a grammar that is supplied upon cre-
       ation of a Config::Grammar object to parse the configura-
       tion file and return helpful error messages in case of
       syntax errors. Using the makepod method you can generate
       documentation of the configuration file format.

       The maketmpl method can generate a template configuration
       file.  If your grammar contains regexp matches, the tem-
       plate will not be all that helpful as Config::Grammar is
       not smart enough to give you sensible template data based
       in regular expressions.

       Grammar Definition

       The grammar is a multiple-level hash of hashes, which fol-
       lows the structure of the configuration. Each section or
       variable is represented by a hash with the same structure.
       Each hash contains special keys starting with an under-
       score such as '_sections', '_vars', '_sub' or '_re' to
       denote meta data with information about that section or
       variable. Other keys are used to structure the hash
       according to the same nesting structure of the configura-
       tion itself. The starting hash given as parameter to 'new'
       contains the "root section".

       Special Section Keys

       _sections   Array containing the list of sub-sections of
                   this section. Each sub-section must then be
                   represented by a sub-hash in this hash with
                   the same name of the sub-section.

                   The sub-section can also be a regular expres-
                   sion denoted by the syntax '/re/', where re is
                   the regular-expression. In case a regular
                   expression is used, a sub-hash named with the
                   same '/re/' must be included in this hash.

       _recursive  Array containing the list of those sub-sec-
                   tions that are recursive, ie.  that can con-
                   tain a new sub-section with the same syntax as
                   themselves.

                   The same effect can be accomplished with cir-
                   cular references in the grammar tree or a
                   suitable _dyn section subroutine (see below},
                   so this facility is included just for conve-
                   nience.

       _vars       Array containing the list of variables
                   (assignments) in this section.  Analogous to
                   sections, regular expressions can be used.

       _mandatory  Array containing the list of mandatory sec-
                   tions and variables.

       _inherited  Array containing the list of the variables
                   that should be assigned the same value as in
                   the parent section if nothing is specified
                   here.

       _table      Hash containing the table grammar (see Special
                   Table Keys). If not specified, no table is
                   allowed in this section. The grammar of the
                   columns if specified by sub-hashes named with
                   the column number.

       _text       Section contains free-form text. Only sections
                   and @includes statements will be interpreted,
                   the rest will be added in the returned hash
                   under '_text' as string.

                   _text is a hash reference which can contain a
                   _re and a _re_error key which will be used to
                   scrutanize the text ... if the hash is empty,
                   all text will be accepted.

       _order      If defined, a '_order' element will be put in
                   every hash containing the sections with a num-
                   ber that determines the order in which the
                   sections were defined.

       _varlist    If defined, a '_varlist' element will be put
                   in the config hash of this section with a list
                   of the variables defined in the section. This
                   can be used to find out the order of the vari-
                   able assignments.

                   The '_sub' function (see below) of any vari-
                   ables defined in this section will also
                   receive a list of those variables already
                   defined in the same section. This can be used
                   to enforce the order of the variables during
                   parsing.

       _doc        Describes what this section is about

       _sub        A function pointer. It is called for every
                   instance of this section, with the real name
                   of the section passed as its first argument.
                   This is probably only useful for the regexp
                   sections. If the function returns a defined
                   value it is assumed that the test was not suc-
                   cessful and an error is generated with the
                   returned string as content.

       _dyn        A subroutine reference (function pointer) that
                   will be called when a new section of this syn-
                   tax is encountered. The subroutine will get
                   three arguments: the syntax of the section
                   name (string or regexp), the actual name
                   encountered (this will be the same as the
                   first argument for non-regexp sections) and a
                   reference to the grammar tree of the section.
                   This subroutine can then modify the grammar
                   tree dynamically.

       _dyndoc     A hash reference that lists interesting names
                   for the section that should be documented. The
                   keys of the hash are the names and the values
                   in the hash are strings that can contain an
                   explanation for the name. The _dyn() subrou-
                   tine is then called for each of these names
                   and the differences of the resulting grammar
                   and the original one are documented. This mod-
                   ule can currently document differences in the
                   _vars list, listing new variables and removed
                   ones, and differences in the _sections list,
                   listing the new and removed sections.

       Special Variable Keys

       _re         Regular expression upon which the value will
                   be checked.

       _re_error   String containing the returned error in case
                   the regular expression doesn't match (if not
                   specified, a generic 'syntax error' message
                   will be returned).

       _sub        A function pointer. It called for every value,
                   with the value passed as its first argument.
                   If the function returns a defined value it is
                   assumed that the test was not successful and
                   an error is generated with the returned string
                   as content.

                   If the '_varlist' key (see above) is defined
                   in this section, the '_sub' function will also
                   receive an array reference as the second argu-
                   ment. The array contains a list of those vari-
                   ables already defined in the same section.
                   This can be used to enforce the order of the
                   variables.

       _default    A default value that will be assigned to the
                   variable if none is specified or inherited.

       _doc        Description of the variable.

       _example    A one line example for the content of this
                   variable.

       _dyn        A subroutine reference (function pointer) that
                   will be called when the variable is assigned
                   some value in the config file. The subroutine
                   will get three arguments: the name of the
                   variable, the value assigned and a reference
                   to the grammar tree of this section.  This
                   subroutine can then modify the grammar tree
                   dynamically.

                   Note that no _dyn() call is made for default
                   and inherited values of the variable.

       _dyndoc     A hash reference that lists interesting values
                   for the variable that should be documented.
                   The keys of the hash are the values and the
                   values in the hash are strings that can con-
                   tain an explanation for the value. The _dyn()
                   subroutine is then called for each of these
                   values and the differences of the resulting
                   grammar and the original one are documented.
                   This module can currently document differences
                   in the _vars list, listing new variables and
                   removed ones, and differences in the _sections
                   list, listing the new and removed sections.

       Special Table Keys

       _columns    Number of columns. If not specified, it will
                   not be enforced.

       _key        If defined, the specified column number will
                   be used as key in a hash in the returned hash.
                   If not defined, the returned hash will contain
                   a '_table' element with the contents of the
                   table as array. The rows of the tables are
                   stored as arrays.

       _sub        they work analog to the description in the
                   previous section.

       _doc        describes the content of the column.

       _example    example for the content of this column

       Special Text Keys

       _re         Regular expression upon which the text will be
                   checked (everything as a single line).

       _re_error   String containing the returned error in case
                   the regular expression doesn't match (if not
                   specified, a generic 'syntax error' message
                   will be returned).

       _sub        they work analog to the description in the
                   previous section.

       _doc        Ditto.

       _example    Potential multi line example for the content
                   of this text section

       Configuration Syntax

       General Syntax

       '#' denotes a comment up to the end-of-line, empty lines
       are allowed and space at the beginning and end of lines is
       trimmed.

       '\' at the end of the line marks a continued line on the
       next line. A single space will be inserted between the
       concatenated lines.

       '@include filename' is used to include another file.

       '@define a some value' will replace all occurences of 'a'
       in the following text with 'some value'.

       Fields in tables that contain white space can be enclosed
       in either "'" or """.  Whitespace can also be escaped with
       "\". Quotes inside quotes are allowed but must be escaped
       with a backslash as well.

       Sections

       Config::Grammar supports hierarchical configurations
       through sections, whose syntax is as follows:

       Level 1        *** section name ***

       Level 2        + section name

       Level 3        ++ section name

       Level n, n>1   +..+ section name (number of '+' determines
                      level)

       Assignments

       Assignements take the form: 'variable = value', where
       value can be any string (can contain whitespaces and spe-
       cial characters). The spaces before and after the equal
       sign are optional.

       Tabular Data

       The data is interpreted as one or more columns separated
       by spaces.

       Example

       Code

































        my $parser = Config::Grammar->new({
          _sections => [ 'network', 'hosts' ],
          network => {
             _vars     => [ 'dns' ],
             _sections => [ "/$RE_IP/" ],
             dns       => {
                _doc => "address of the dns server",
                _example => "ns1.oetiker.xs",
                _re => $RE_HOST,
                _re_error =>
                   'dns must be an host name or ip address',
                },
             "/$RE_IP/" => {
                _doc    => "Ip Adress",
                _example => '10.2.3.2',
                _vars   => [ 'netmask', 'gateway' ],
                netmask => {
                   _doc => "Netmask",
                   _example => "255.255.255.0",
                   _re => $RE_IP,
                   _re_error =>
                      'netmask must be a dotted ip address'
                   },
                gateway => {
                   _doc => "Default Gateway address in IP notation",
                   _example => "10.22.12.1",
                   _re => $RE_IP,
                   _re_error =>
                      'gateway must be a dotted ip address' },
                },
             },
          hosts => {
             _doc => "Details about the hosts",
             _table  => {
                 _doc => "Description of all the Hosts",
                _key => 0,
                _columns => 3,
                0 => {
                   _doc => "Ethernet Address",
                   _example => "0:3:3:d:a:3:dd:a:cd",
                   _re => $RE_MAC,
                   _re_error =>
                      'first column must be an ethernet mac address',
                   },
                1 => {
                   _doc => "IP Address",
                   _example => "10.11.23.1",
                   _re => $RE_IP,
                   _re_error =>
                      'second column must be a dotted ip address',
                   },
                2 => {
                   _doc => "Host Name",
                   _example => "tardis",
                    },
                },
             },
          });

        my $cfg = $parser->parse('test.cfg') or
          die "ERROR: $parser->{err}\n";
        print Dumper($cfg);
        print $praser->makepod;

       Configuration

        *** network ***

          dns      = 192.168.7.87

        + 192.168.7.64

          netmask  = 255.255.255.192
          gateway  = 192.168.7.65

        *** hosts ***

          00:50:fe:bc:65:11     192.168.7.97    plain.hades
          00:50:fe:bc:65:12     192.168.7.98    isg.ee.hades
          00:50:fe:bc:65:14     192.168.7.99    isg.ee.hades

       Result

        {
          'hosts' => {
                       '00:50:fe:bc:65:11' => [
                                                '00:50:fe:bc:65:11',
                                                '192.168.7.97',
                                                'plain.hades'
                                              ],
                       '00:50:fe:bc:65:12' => [
                                                '00:50:fe:bc:65:12',
                                                '192.168.7.98',
                                                'isg.ee.hades'
                                              ],
                       '00:50:fe:bc:65:14' => [
                                                '00:50:fe:bc:65:14',
                                                '192.168.7.99',
                                                'isg.ee.hades'
                                              ]
                     },
          'network' => {
                         '192.168.7.64' => {
                                             'netmask' => '255.255.255.192',
                                             'gateway' => '192.168.7.65'
                                           },
                         'dns' => '192.168.7.87'
                       }
        };

COPYRIGHT
       Copyright (c) 2000-2005 by ETH Zurich. All rights
       reserved.

LICENSE
       This program is free software; you can redistribute it
       and/or modify it under the same terms as Perl itself.

AUTHOR
       David Schweikert <dws_at_ee.ethz.ch>, Tobias Oetiker
       <oetiker_at_ee.ethz.ch>, Niko Tyni  <ntyni_at_iki.fi>

HISTORY
        2001-05-11 ds      Initial Version of ISG::ParseConfig
        2005-03-08 ds 1.00 Renamed from ISG::ParseConfig to Config::Grammar



2.0.9                       2005-12-18         Config::Grammar(3)
