1Config::Grammar(3)    User Contributed Perl Documentation   Config::Grammar(3)
2
3
4

NAME

6       Config::Grammar - A grammar-based, user-friendly config parser
7

SYNOPSIS

9        use Config::Grammar;
10
11        my $args = { encoding => 'utf8' }; # the second parameter to parse() is optional
12        my $parser = Config::Grammar->new(\%grammar);
13        my $cfg = $parser->parse('app.cfg', $args) or die "ERROR: $parser->{err}\n";
14        my $pod = $parser->makepod();
15        my $ex = $parser->maketmpl('TOP','SubNode');
16        my $minex = $parser->maketmplmin('TOP','SubNode');
17

DESCRIPTION

19       Config::Grammar is a module to parse configuration files. The optional
20       second parameter to the parse() method can be used to specify the file
21       encoding to use for opening the file (see documentation for Perl's use
22       open pragma).
23
24       The configuration may consist of multiple-level sections with
25       assignments and tabular data. The parsed data will be returned as a
26       hash containing the whole configuration. Config::Grammar uses a grammar
27       that is supplied upon creation of a Config::Grammar object to parse the
28       configuration file and return helpful error messages in case of syntax
29       errors. Using the makepod method you can generate documentation of the
30       configuration file format.
31
32       The maketmpl method can generate a template configuration file.  If
33       your grammar contains regexp matches, the template will not be all that
34       helpful as Config::Grammar is not smart enough to give you sensible
35       template data based in regular expressions. The related function
36       maketmplmin generates a minimal configuration template without
37       examples, regexps or comments and thus allows an experienced user to
38       fill in the configuration data more efficiently.
39
40   Grammar Definition
41       The grammar is a multiple-level hash of hashes, which follows the
42       structure of the configuration. Each section or variable is represented
43       by a hash with the same structure.  Each hash contains special keys
44       starting with an underscore such as '_sections', '_vars', '_sub' or
45       '_re' to denote meta data with information about that section or
46       variable. Other keys are used to structure the hash according to the
47       same nesting structure of the configuration itself. The starting hash
48       given as parameter to 'new' contains the "root section".
49
50       Special Section Keys
51
52       _sections   Array containing the list of sub-sections of this section.
53                   Each sub-section must then be represented by a sub-hash in
54                   this hash with the same name of the sub-section.
55
56                   The sub-section can also be a regular expression denoted by
57                   the syntax '/re/', where re is the regular-expression. In
58                   case a regular expression is used, a sub-hash named with
59                   the same '/re/' must be included in this hash.
60
61       _vars       Array containing the list of variables (assignments) in
62                   this section.  Analogous to sections, regular expressions
63                   can be used.
64
65       _mandatory  Array containing the list of mandatory sections and
66                   variables.
67
68       _inherited  Array containing the list of the variables that should be
69                   assigned the same value as in the parent section if nothing
70                   is specified here.
71
72       _table      Hash containing the table grammar (see Special Table Keys).
73                   If not specified, no table is allowed in this section. The
74                   grammar of the columns if specified by sub-hashes named
75                   with the column number.
76
77       _text       Section contains free-form text. Only sections and
78                   @includes statements will be interpreted, the rest will be
79                   added in the returned hash under '_text' as string.
80
81                   _text is a hash reference which can contain a _re and a
82                   _re_error key which will be used to scrutanize the text ...
83                   if the hash is empty, all text will be accepted.
84
85       _order      If defined, a '_order' element will be put in every hash
86                   containing the sections with a number that determines the
87                   order in which the sections were defined.
88
89       _doc        Describes what this section is about
90
91       _sub        A function pointer. It is called for every instance of this
92                   section, with the real name of the section passed as its
93                   first argument. This is probably only useful for the regexp
94                   sections. If the function returns a defined value it is
95                   assumed that the test was not successful and an error is
96                   generated with the returned string as content.
97
98       Special Variable Keys
99
100       _re         Regular expression upon which the value will be checked.
101
102       _re_error   String containing the returned error in case the regular
103                   expression doesn't match (if not specified, a generic
104                   'syntax error' message will be returned).
105
106       _sub        A function pointer. It called for every value, with the
107                   value passed as its first argument. If the function returns
108                   a defined value it is assumed that the test was not
109                   successful and an error is generated with the returned
110                   string as content.
111
112                   If the '_varlist' key (see above) is defined in this
113                   section, the '_sub' function will also receive an array
114                   reference as the second argument. The array contains a list
115                   of those variables already defined in the same section.
116                   This can be used to enforce the order of the variables.
117
118       _default    A default value that will be assigned to the variable if
119                   none is specified or inherited.
120
121       _doc        Description of the variable.
122
123       _example    A one line example for the content of this variable.
124
125       Special Table Keys
126
127       _columns    Number of columns. If not specified, it will not be
128                   enforced.
129
130       _key        If defined, the specified column number will be used as key
131                   in a hash in the returned hash. If not defined, the
132                   returned hash will contain a '_table' element with the
133                   contents of the table as array. The rows of the tables are
134                   stored as arrays.
135
136       _sub        they work analog to the description in the previous
137                   section.
138
139       _doc        describes the content of the column.
140
141       _example    example for the content of this column
142
143       Special Text Keys
144
145       _re         Regular expression upon which the text will be checked
146                   (everything as a single line).
147
148       _re_error   String containing the returned error in case the regular
149                   expression doesn't match (if not specified, a generic
150                   'syntax error' message will be returned).
151
152       _sub        they work analog to the description in the previous
153                   section.
154
155       _doc        Ditto.
156
157       _example    Potential multi line example for the content of this text
158                   section
159
160   Configuration Syntax
161       General Syntax
162
163       '#' denotes a comment up to the end-of-line, empty lines are allowed
164       and space at the beginning and end of lines is trimmed.
165
166       '\' at the end of the line marks a continued line on the next line. A
167       single space will be inserted between the concatenated lines.
168
169       '@include filename' is used to include another file. Include works
170       relative to the directory where the parent file is in.
171
172       '@define a some value' will replace all occurrences of 'a' in the
173       following text with 'some value'.
174
175       Fields in tables that contain white space can be enclosed in either "'"
176       or """.  Whitespace can also be escaped with "\". Quotes inside quotes
177       are allowed but must be escaped with a backslash as well.
178
179       Sections
180
181       Config::Grammar supports hierarchical configurations through sections,
182       whose syntax is as follows:
183
184       Level 1        *** section name ***
185
186       Level 2        + section name
187
188       Level 3        ++ section name
189
190       Level n, n>1   +..+ section name (number of '+' determines level)
191
192       Assignments
193
194       Assignments take the form: 'variable = value', where value can be any
195       string (can contain whitespaces and special characters). The spaces
196       before and after the equal sign are optional.
197
198       Tabular Data
199
200       The data is interpreted as one or more columns separated by spaces.
201
202   Example
203       Code
204
205        use Data::Dumper;
206        use Config::Grammar;
207
208        my $RE_IP       = '\d+\.\d+\.\d+\.\d+';
209        my $RE_MAC      = '[0-9a-f]{2}(?::[0-9a-f]{2}){5}';
210        my $RE_HOST     = '\S+';
211
212        my $parser = Config::Grammar->new({
213          _sections => [ 'network', 'hosts' ],
214          network => {
215             _vars     => [ 'dns' ],
216             _sections => [ "/$RE_IP/" ],
217             dns       => {
218                _doc => "address of the dns server",
219                _example => "ns1.oetiker.xs",
220                _re => $RE_HOST,
221                _re_error =>
222                   'dns must be an host name or ip address',
223                },
224             "/$RE_IP/" => {
225                _doc    => "Ip Adress",
226                _example => '10.2.3.2',
227                _vars   => [ 'netmask', 'gateway' ],
228                netmask => {
229                   _doc => "Netmask",
230                   _example => "255.255.255.0",
231                   _re => $RE_IP,
232                   _re_error =>
233                      'netmask must be a dotted ip address'
234                   },
235                gateway => {
236                   _doc => "Default Gateway address in IP notation",
237                   _example => "10.22.12.1",
238                   _re => $RE_IP,
239                   _re_error =>
240                      'gateway must be a dotted ip address' },
241                },
242             },
243          hosts => {
244             _doc => "Details about the hosts",
245             _table  => {
246                 _doc => "Description of all the Hosts",
247                _key => 0,
248                _columns => 3,
249                0 => {
250                   _doc => "Ethernet Address",
251                   _example => "0:3:3:d:a:3:dd:a:cd",
252                   _re => $RE_MAC,
253                   _re_error =>
254                      'first column must be an ethernet mac address',
255                   },
256                1 => {
257                   _doc => "IP Address",
258                   _example => "10.11.23.1",
259                   _re => $RE_IP,
260                   _re_error =>
261                      'second column must be a dotted ip address',
262                   },
263                2 => {
264                   _doc => "Host Name",
265                   _example => "tardis",
266                    },
267                },
268             },
269          });
270
271        my $args = { encoding => 'utf8' }; # the second parameter to parse() is optional
272        my $cfg = $parser->parse('test.cfg', $args) or
273          die "ERROR: $parser->{err}\n";
274        print Dumper($cfg);
275        print $parser->makepod;
276
277       Configuration
278
279        *** network ***
280
281          dns      = 192.168.7.87
282
283        + 192.168.7.64
284
285          netmask  = 255.255.255.192
286          gateway  = 192.168.7.65
287
288        *** hosts ***
289
290          00:50:fe:bc:65:11     192.168.7.97    plain.hades
291          00:50:fe:bc:65:12     192.168.7.98    isg.ee.hades
292          00:50:fe:bc:65:14     192.168.7.99    isg.ee.hades
293
294       Result
295
296        {
297          'hosts' => {
298                       '00:50:fe:bc:65:11' => [
299                                                '00:50:fe:bc:65:11',
300                                                '192.168.7.97',
301                                                'plain.hades'
302                                              ],
303                       '00:50:fe:bc:65:12' => [
304                                                '00:50:fe:bc:65:12',
305                                                '192.168.7.98',
306                                                'isg.ee.hades'
307                                              ],
308                       '00:50:fe:bc:65:14' => [
309                                                '00:50:fe:bc:65:14',
310                                                '192.168.7.99',
311                                                'isg.ee.hades'
312                                              ]
313                     },
314          'network' => {
315                         '192.168.7.64' => {
316                                             'netmask' => '255.255.255.192',
317                                             'gateway' => '192.168.7.65'
318                                           },
319                         'dns' => '192.168.7.87'
320                       }
321        };
322

SEE ALSO

324       Config::Grammar::Dynamic
325
327       Copyright (c) 2000-2005 by ETH Zurich. All rights reserved.  Copyright
328       (c) 2007 by David Schweikert. All rights reserved.
329

LICENSE

331       This program is free software; you can redistribute it and/or modify it
332       under the same terms as Perl itself.
333

AUTHORS

335       David Schweikert, Tobias Oetiker, Niko Tyni
336
337
338
339perl v5.34.0                      2022-01-21                Config::Grammar(3)
Impressum