1
ISG::ParseConfig(3) SmokePing ISG::ParseConfig(3)
8
my $parser = ISG::ParseConfig->new(\%grammar);
9
my $cfg = $parser->parse('app.cfg') or die "ERROR: $parser->{err}\n";
10
my $pod = $parser->makepod();
11
my $ex = $parser->maketmpl('TOP','SubNode');
13
DDEESSCCRRIIPPTTIIOONN
14
ISG::ParseConfig is a module to parse configuration files.
15
The configuration may consist of multiple-level sections
16
with assignments and tabular data. The parsed data will be
17
returned as a hash containing the whole configuration.
18
ISG::ParseConfig uses a grammar that is supplied upon cre-
19
ation of a ISG::ParseConfig object to parse the configura-
20
tion file and return helpful error messages in case of
21
syntax errors. Using the mmaakkeeppoodd methode you can generate
22
documentation of the configuration file format.
24
The mmaakkeettmmppll method can generate a template configuration
25
file. If your grammar contains regexp matches, the tem-
26
plate will not be all that helpful as ParseConfig is not
27
smart enough to give you sensible template data based in
30
GGrraammmmaarr DDeeffiinniittiioonn
32
The grammar is a multiple-level hash of hashes, which fol-
33
lows the structure of the configuration. Each section or
34
variable is represented by a hash with the same structure.
35
Each hash contains special keys starting with an under-
36
score such as '_sections', '_vars', '_sub' or '_re' to
37
denote meta data with information about that section or
38
variable. Other keys are used to structure the hash
39
according to the same nesting structure of the configura-
40
tion itself. The starting hash given as parameter to 'new'
41
contains the "root section".
43
_S_p_e_c_i_a_l _S_e_c_t_i_o_n _K_e_y_s
45
_sections Array containing the list of sub-sections of
46
this section. Each sub-section must then be
47
represented by a sub-hash in this hash with
48
the same name of the sub-section.
50
The sub-section can also be a regular expres-
51
sion denoted by the syntax '/re/', where re is
52
the regular-expression. In case a regular
53
expression is used, a sub-hash named with the
54
same '/re/' must be included in this hash.
56
_recursive Array containing the list of those sub-sec-
57
tions that are _r_e_c_u_r_s_i_v_e, ie. that can con-
58
tain a new sub-section with the same syntax as
61
The same effect can be accomplished with cir-
62
cular references in the grammar tree or a
63
suitable __ddyynn section subroutine (see below},
64
so this facility is included just for conve-
67
_vars Array containing the list of variables
68
(assignments) in this section. Analogous to
69
sections, regular expressions can be used.
71
_mandatory Array containing the list of mandatory sec-
74
_inherited Array containing the list of the variables
75
that should be assigned the same value as in
76
the parent section if nothing is specified
79
_table Hash containing the table grammar (see Special
80
Table Keys). If not specified, no table is
81
allowed in this section. The grammar of the
82
columns if specified by sub-hashes named with
85
_text Section contains free-form text. Only sections
86
and @includes statements will be interpreted,
87
the rest will be added in the returned hash
88
under '_text' as string.
90
__tteexxtt is a hash reference which can contain a
91
__rree and a __rree__eerrrroorr key which will be used to
92
scrutanize the text ... if the hash is empty,
93
all text will be accepted.
95
_order If defined, a '_order' element will be put in
96
every hash containing the sections with a num-
97
ber that determines the order in which the
98
sections were defined.
100
_doc Describes what this section is about
102
_dyn A subroutine reference (function pointer) that
103
will be called when a new section of this syn-
104
tax is encountered. The subroutine will get
105
three arguments: the syntax of the section
106
name (string or regexp), the actual name
107
encountered (this will be the same as the
108
first argument for non-regexp sections) and a
109
reference to the grammar tree of the section.
110
This subroutine can then modify the grammar
113
_S_p_e_c_i_a_l _V_a_r_i_a_b_l_e _K_e_y_s
115
_re Regular expression upon which the value will
118
_re_error String containing the returned error in case
119
the regular expression doesn't match (if not
120
specified, a generic 'syntax error' message
123
_sub A function pointer. It called for every value,
124
with the value passed as its first argument.
125
If the function returns a defined value it is
126
assumed that the test was not successful and
127
an error is generated with the returned string
130
_default A default value that will be assigned to the
131
variable if none is specified or inherited.
133
_doc Describtion of the variable.
135
_example A one line example for the content of this
138
_dyn A subroutine reference (function pointer) that
139
will be called when the variable is assigned
140
some value in the config file. The subroutine
141
will get three arguments: the name of the
142
variable, the value assigned and a reference
143
to the grammar tree of this section. This
144
subroutine can then modify the grammar tree
147
Note that no ___d_y_n_(_) call is made for default
148
and inherited values of the variable.
150
_S_p_e_c_i_a_l _T_a_b_l_e _K_e_y_s
152
_columns Number of columns. If not specified, it will
155
_key If defined, the specified column number will
156
be used as key in a hash in the returned hash.
157
If not defined, the returned hash will contain
158
a '_table' element with the contents of the
159
table as array. The rows of the tables are
162
_sub they work analog to the description in the
165
_doc describes the content of the column.
167
_example example for the content of this column
169
_S_p_e_c_i_a_l _T_e_x_t _K_e_y_s
171
_re Regular expression upon which the text will be
172
checked (everything as a single line).
174
_re_error String containing the returned error in case
175
the regular expression doesn't match (if not
176
specified, a generic 'syntax error' message
179
_sub they work analog to the description in the
184
_example Potential multi line example for the content
187
CCoonnffiigguurraattiioonn SSyynnttaaxx
189
_G_e_n_e_r_a_l _S_y_n_t_a_x
191
'#' denotes a comment up to the end-of-line, empty lines
192
are allowed and space at the beginning and end of lines is
195
'\' at the end of the line marks a continued line on the
196
next line. A single space will be inserted between the
199
'@include filename' is used to include another file.
201
'@define a some value' will replace all occurences of 'a'
202
in the following text with 'some value'.
204
Fields in tables that contain white space can be enclosed
205
in either "'" or """. Whitespace can also be escaped with
206
"\". Quotes inside quotes are allowed but must be escaped
207
with a backslash as well.
211
ISG::ParseConfig supports hierarchical configurations
212
through sections, whose syntax is as follows:
214
Level 1 *** section name ***
216
Level 2 + section name
218
Level 3 ++ section name
220
Level n, n>1 +..+ section name (number of '+' determines
223
_A_s_s_i_g_n_m_e_n_t_s
225
Assignements take the form: 'variable = value', where
226
value can be any string (can contain whitespaces and spe-
227
cial characters). The spaces before and after the equal
230
_T_a_b_u_l_a_r _D_a_t_a
232
The data is interpreted as one or more columns separated
265
my $parser = ISG::ParseConfig->new({
266
_sections => [ 'network', 'hosts' ],
269
_sections => [ "/$RE_IP/" ],
271
_doc => "address of the dns server",
272
_example => "ns1.oetiker.xs",
275
'dns must be an host name or ip address',
279
_example => '10.2.3.2',
280
_vars => [ 'netmask', 'gateway' ],
283
_example => "255.255.255.0",
286
'netmask must be a dotted ip address'
289
_doc => "Default Gateway address in IP notation",
290
_example => "10.22.12.1",
293
'gateway must be a dotted ip address' },
297
_doc => "Details about the hosts",
299
_doc => "Description of all the Hosts",
303
_doc => "Ethernet Address",
304
_example => "0:3:3:d:a:3:dd:a:cd",
307
'first column must be an ethernet mac address',
310
_doc => "IP Address",
311
_example => "10.11.23.1",
314
'second column must be a dotted ip address',
318
_example => "tardis",
324
my $cfg = $parser->parse('test.cfg') or
325
die "ERROR: $parser->{err}\n";
327
print $praser->makepod;
329
_C_o_n_f_i_g_u_r_a_t_i_o_n
337
netmask = 255.255.255.192
338
gateway = 129.132.7.65
342
00:50:fe:bc:65:11 129.132.7.97 plain.hades
343
00:50:fe:bc:65:12 129.132.7.98 isg.ee.hades
344
00:50:fe:bc:65:14 129.132.7.99 isg.ee.hades
350
'00:50:fe:bc:65:11' => [
355
'00:50:fe:bc:65:12' => [
360
'00:50:fe:bc:65:14' => [
368
'netmask' => '255.255.255.192',
369
'gateway' => '129.132.7.65'
371
'dns' => '129.132.7.87'
376
Copyright (c) 2000, 2001 by ETH Zurich. All rights
380
This program is free software; you can redistribute it
381
and/or modify it under the terms of the GNU General Public
382
License as published by the Free Software Foundation;
383
either version 2 of the License, or (at your option) any
386
This program is distributed in the hope that it will be
387
useful, but WITHOUT ANY WARRANTY; without even the implied
388
warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
389
PURPOSE. See the GNU General Public License for more
392
You should have received a copy of the GNU General Public
393
License along with this program; if not, write to the Free
394
Software Foundation, Inc., 675 Mass Ave, Cambridge, MA
398
David Schweikert <dws@ee.ethz.ch>
399
Tobias Oetiker <oetiker@ee.ethz.ch>
402
2001-05-11 ds 1.2 Initial Version for policy 0.3
403
2001-09-04 ds 1.3 Remove space before comments, more strict variable definition
404
2001-09-19 to 1.4 Added _sub error parsing and _doc self documentation
405
2001-10-20 to Improved Rendering of _doc information
406
2002-01-09 to Added Documentation to the _text section documentation
407
2002-01-28 to Fixed quote parsing in tables
408
2002-03-12 ds 1.5 Implemented @define, make makepod return a string and not an array
409
2002-08-28 to Added maketmpl methode
410
2002-10-10 ds 1.6 More verbatim _text sections
411
2004-02-09 to 1.7 Added _example propperty for pod and template generation
412
2004-08-17 to 1.8 Allow special input files like "program|"
413
2005-01-10 ds 1.9 Implemented _dyn, _default, _recursive, and _inherited (Niko Tyni)
417
1.38 2005-01-10 ISG::ParseConfig(3)
added
removed
doc/ParseConfig.pm.txt
