ISG::ParseConfig(3)         SmokePing         ISG::ParseConfig(3)



SYNOPSIS
        use ISG::ParseConfig;

        my $parser = ISG::ParseConfig->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
       ISG::ParseConfig 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.
       ISG::ParseConfig uses a grammar that is supplied upon cre-
       ation of a ISG::ParseConfig object to parse the configura-
       tion file and return helpful error messages in case of
       syntax errors. Using the makepod methode 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 ParseConfig 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.

       _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.

       _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.

       _doc        Describes what this section is about

       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.

       _doc        Describtion of the variable.

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

       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

       ISG::ParseConfig 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 = ISG::ParseConfig->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      = 129.132.7.87

        + 129.132.7.64

          netmask  = 255.255.255.192
          gateway  = 129.132.7.65

        *** hosts ***

          00:50:fe:bc:65:11     129.132.7.97    plain.hades
          00:50:fe:bc:65:12     129.132.7.98    isg.ee.hades
          00:50:fe:bc:65:14     129.132.7.99    isg.ee.hades

       Result

        {
          'hosts' => {
                       '00:50:fe:bc:65:11' => [
                                                '00:50:fe:bc:65:11',
                                                '129.132.7.97',
                                                'plain.hades'
                                              ],
                       '00:50:fe:bc:65:12' => [
                                                '00:50:fe:bc:65:12',
                                                '129.132.7.98',
                                                'isg.ee.hades'
                                              ],
                       '00:50:fe:bc:65:14' => [
                                                '00:50:fe:bc:65:14',
                                                '129.132.7.99',
                                                'isg.ee.hades'
                                              ]
                     },
          'network' => {
                         '129.132.7.64' => {
                                             'netmask' => '255.255.255.192',
                                             'gateway' => '129.132.7.65'
                                           },
                         'dns' => '129.132.7.87'
                       }
        };

COPYRIGHT
       Copyright (c) 2000, 2001 by ETH Zurich. All rights
       reserved.

LICENSE
       This program is free software; you can redistribute it
       and/or modify it under the terms of the GNU General Public
       License as published by the Free Software Foundation;
       either version 2 of the License, or (at your option) any
       later version.

       This program is distributed in the hope that it will be
       useful, but WITHOUT ANY WARRANTY; without even the implied
       warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
       PURPOSE.  See the GNU General Public License for more
       details.

       You should have received a copy of the GNU General Public
       License along with this program; if not, write to the Free
       Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
       02139, USA.

AUTHOR
       David Schweikert <dws@ee.ethz.ch>
       Tobias Oetiker <oetiker@ee.ethz.ch>

HISTORY
        2001-05-11 ds 1.2 Initial Version for policy 0.3
        2001-09-04 ds 1.3 Remove space before comments, more strict variable definition
        2001-09-19 to 1.4 Added _sub error parsing and _doc self documentation
        2001-10-20 to     Improved Rendering of _doc information
        2002-01-09 to     Added Documentation to the _text section documentation
        2002-01-28 to     Fixed quote parsing in tables
        2002-03-12 ds 1.5 Implemented @define, make makepod return a string and not an array
        2002-08-28 to     Added maketmpl methode
        2002-10-10 ds 1.6 More verbatim _text sections
        2004-02-09 to 1.7 Added _example propperty for pod and template generation



1.30                        2004-02-09        ISG::ParseConfig(3)
