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



SSYYNNOOPPSSIISS
        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');

DDEESSCCRRIIPPTTIIOONN
       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 mmaakkeeppoodd methode you can generate
       documentation of the configuration file format.

       The mmaakkeettmmppll 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.

       GGrraammmmaarr DDeeffiinniittiioonn

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

       _S_p_e_c_i_a_l _S_e_c_t_i_o_n _K_e_y_s

       _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 _r_e_c_u_r_s_i_v_e, 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 __ddyynn 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.

                   __tteexxtt is a hash reference which can contain a
                   __rree and a __rree__eerrrroorr 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

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

       _S_p_e_c_i_a_l _V_a_r_i_a_b_l_e _K_e_y_s

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

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

       _doc        Describtion 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 ___d_y_n_(_) call is made for default
                   and inherited values of the variable.

       _S_p_e_c_i_a_l _T_a_b_l_e _K_e_y_s

       _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

       _S_p_e_c_i_a_l _T_e_x_t _K_e_y_s

       _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

       CCoonnffiigguurraattiioonn SSyynnttaaxx

       _G_e_n_e_r_a_l _S_y_n_t_a_x

       '#' 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.

       _S_e_c_t_i_o_n_s

       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)

       _A_s_s_i_g_n_m_e_n_t_s

       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.

       _T_a_b_u_l_a_r _D_a_t_a

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

       EExxaammppllee

       _C_o_d_e



























        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;

       _C_o_n_f_i_g_u_r_a_t_i_o_n

        *** 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

       _R_e_s_u_l_t

        {
          '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'
                       }
        };

CCOOPPYYRRIIGGHHTT
       Copyright (c) 2000, 2001 by ETH Zurich. All rights
       reserved.

LLIICCEENNSSEE
       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.

AAUUTTHHOORR
       David Schweikert <dws@ee.ethz.ch>
       Tobias Oetiker <oetiker@ee.ethz.ch>

HHIISSTTOORRYY
        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
        2004-08-17 to 1.8 Allow special input files like "program|"
        2005-01-10 ds 1.9 Implemented _dyn, _default, _recursive, and _inherited (Niko Tyni)



1.38                        2005-01-10        ISG::ParseConfig(3)
