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