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



SSYYNNOOPPSSIISS
        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');

DDEESSCCRRIIPPTTIIOONN
       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 mmaakkeeppoodd methode you can generate
       documentation of the configuration file format.

       The mmaakkeettmmppll 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.

       GGrraammmmaarr DDeeffiinniittiioonn

       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.

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

                   __tteexxtt is a hash reference which can contain a
                   __rree and a __rree__eerrrroorr 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

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

       _doc        Describtion of the variable.

       _example    A one line example for the content of this
                   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

       CCoonnffiigguurraattiioonn SSyynnttaaxx

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

       EExxaammppllee

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

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

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

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

HHIISSTTOORRYY
        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)
