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



SSSSYYYYNNNNOOOOPPPPSSSSIIIISSS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;


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNN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mmmaaaakkkkeeeeppppoooodddd methode you can generate
       documentation of the configuration file format.

       GGGGrrrraaaammmmmmmmaaaarrrr DDDDeeeeffffiiiinnnniiiittttiiiioooonnn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.

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

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

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

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

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




       CCCCoooonnnnffffiiiigggguuuurrrraaaattttiiiioooonnnn SSSSyyyynnnnttttaaaaxxx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EEExxxxaaaammmmpppplllleee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",
                _re => $RE_HOST,
                _re_error =>
                   'dns must be an host name or ip address',
                },
             "/$RE_IP/" => {
                _doc    => "Ip Adress",
                _vars   => [ 'dns', 'netmask', 'gateway' ],
                dns     => {
                   _doc => "address of the dns server",
                   _re => $RE_HOST,
                   _re_error =>
                      'dns must be an host name or ip address'
                   },
                netmask => {
                   _doc => "Netmask",
                   _re => $RE_IP,
                   _re_error =>
                      'netmask must be a dotted ip address'
                   },
                gateway => {
                   _doc => "Default Gateway address in IP notation",
                   _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",
                   _re => $RE_MAC,
                   _re_error =>
                      'first column must be an ethernet mac address',
                   },
                1 => {
                   _doc => "IP Address",
                   _re => $RE_IP,
                   _re_error =>
                      'second column must be a dotted ip address',
                   },
                },
             },
          });

        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CCCOOOOPPPPYYYYRRRRIIIIGGGGHHHHTTTT
       Copyright (c) 2000, 2001 by ETH Zurich. All rights
       reserved.

LLLLIIIICCCCEEEENNNNSSSSEEE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AAAUUUUTTTTHHHHOOOORRRR
       David Schweikert <dws@ee.ethz.ch>
       Tobias Oetiker <oetiker@ee.ethz.ch>

HHHHIIIISSSSTTTTOOOORRRRYYY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-03-27                     1.12           ISG::ParseConfig(3)
