1ApacheFormat(3)       User Contributed Perl Documentation      ApacheFormat(3)
2
3
4

NAME

6       Config::ApacheFormat - use Apache format config files
7

SYNOPSIS

9       Config files used with this module are in Apache's format:
10
11         # comment here
12         RootDir /path/foo
13         LogDir  /path/foo/log
14         Colors red green orange blue \
15                black teal
16
17         <Directory /path/foo>
18            # override Colors inside block
19            Colors red blue black
20         </Directory>
21
22       Code to use this config file might look like:
23
24         use Config::ApacheFormat;
25
26         # load a conf file
27         my $config = Config::ApacheFormat->new();
28         $config->read("my.conf");
29
30         # access some parameters
31         $root_dir = $config->get("RootDir");
32         $log_dir  = $config->get("LogDir");
33         @colors   = $config->get("colors");
34
35         # using the autoloaded methods
36         $config->autoload_support(1);
37         $root_dir = $config->RootDir;
38         $log_dir  = $config->logdir;
39
40         # access parameters inside a block
41         my $block = $config->block(Directory => "/path/foo");
42         @colors = $block->get("colors");
43         $root_dir = $block->get("root_dir");
44

DESCRIPTION

46       This module is designed to parse a configuration file in the same
47       syntax used by the Apache web server (see http://httpd.apache.org for
48       details).  This allows you to build applications which can be easily
49       managed by experienced Apache admins.  Also, by using this module,
50       you'll benefit from the support for nested blocks with built-in
51       parameter inheritance.  This can greatly reduce the amount or repeated
52       information in your configuration files.
53
54       A good reference to the Apache configuration file format can be found
55       here:
56
57         http://httpd.apache.org/docs-2.0/configuring.html
58
59       To quote from that document, concerning directive syntax:
60
61        Apache configuration files contain one directive per line. The
62        back-slash "\" may be used as the last character on a line to
63        indicate that the directive continues onto the next line. There must
64        be no other characters or white space between the back-slash and the
65        end of the line.
66
67        Directives in the configuration files are case-insensitive, but
68        arguments to directives are often case sensitive. Lines that begin
69        with the hash character "#" are considered comments, and are
70        ignored. Comments may not be included on a line after a configuration
71        directive. Blank lines and white space occurring before a directive
72        are ignored, so you may indent directives for clarity.
73
74       And block notation:
75
76        Directives placed in the main configuration files apply to the entire
77        server. If you wish to change the configuration for only a part of the
78        server, you can scope your directives by placing them in <Directory>,
79        <DirectoryMatch>, <Files>, <FilesMatch>, <Location>, and
80        <LocationMatch> sections. These sections limit the application of the
81        directives which they enclose to particular filesystem locations or
82        URLs. They can also be nested, allowing for very fine grained
83        configuration.
84
85       This module will parse actual Apache configuration files, but you will
86       need to set some options to non-default values.  See "Parsing a Real
87       Apache Config File".
88

METHODS

90       $config = Config::ApacheFormat->new(opt => "value")
91           This method creates an object that can then be used to read
92           configuration files. It does not actually read any files; for that,
93           use the "read()" method below. The object supports the following
94           attributes, all of which may be set through "new()":
95
96           inheritance_support
97               Set this to 0 to turn off the inheritance feature. Block
98               inheritance means that variables declared outside a block are
99               available from inside the block unless overriden.  Defaults to
100               1.
101
102           include_support
103               When this is set to 1, the directive "Include" will be treated
104               specially by the parser.  It will cause the value to be treated
105               as a filename and that filename will be read in.  If you use
106               "Include" with a directory, every file in that directory will
107               be included.  This matches Apache's behavior and allows users
108               to break up configuration files into multiple, possibly shared,
109               pieces.  Defaults to 1.
110
111           autoload_support
112               Set this to 1 and all your directives will be available as
113               object methods.  So instead of:
114
115                 $config->get("foo");
116
117               You can write:
118
119                 $config->foo;
120
121               Defaults to 0.
122
123           case_sensitive
124               Set this to 1 to preserve the case of directive names.
125               Otherwise, all names will be "lc()"ed and matched case-
126               insensitively.  Defaults to 0.
127
128           fix_booleans
129               If set to 1, then during parsing, the strings "Yes", "On", and
130               "True" will be converted to 1, and the strings "No", "Off", and
131               "False" will be converted to 0. This allows you to more easily
132               use "get()" in conditional statements.
133
134               For example:
135
136                 # httpd.conf
137                 UseCanonicalName  On
138
139               Then in Perl:
140
141                 $config = Config::ApacheFormat->new(fix_booleans => 1);
142                 $config->read("httpd.conf");
143
144                 if ($config->get("UseCanonicalName")) {
145                     # this will get executed if set to Yes/On/True
146                 }
147
148               This option defaults to 0.
149
150           expand_vars
151               If set, then you can use variable expansion in your config file
152               by prefixing directives with a "$". Hopefully this seems
153               logical to you:
154
155                 Website     http://my.own.dom
156                 JScript     $Website/js
157                 Images      $Website/images
158
159               Undefined variables in your config file will result in an
160               error. To use a literal "$", simply prefix it with a "\"
161               (backslash). Like in Perl, you can use brackets to delimit the
162               variables more precisely:
163
164                 Nickname    Rob
165                 Fullname    ${Nickname}ert
166
167               Since only scalars are supported, if you use a multi-value, you
168               will only get back the first one:
169
170                 Options     Plus Minus "About the Same"
171                 Values      $Options
172
173               In this examples, "Values" will become "Plus". This is seldom a
174               limitation since in most cases, variable subsitution is used
175               like the first example shows. This option defaults to 0.
176
177           setenv_vars
178               If this is set to 1, then the special "SetEnv" directive will
179               be set values in the environment via %ENV.  Also, the special
180               "UnSetEnv" directive will delete environment variables.
181
182               For example:
183
184                 # $ENV{PATH} = "/usr/sbin:/usr/bin"
185                 SetEnv PATH "/usr/sbin:/usr/bin"
186
187                 # $ENV{MY_SPECIAL_VAR} = 10
188                 SetEnv MY_SPECIAL_VAR 10
189
190                 # delete $ENV{THIS}
191                 UnsetEnv THIS
192
193               This option defaults to 0.
194
195           valid_directives
196               If you provide an array of directive names then syntax errors
197               will be generated during parsing for invalid directives.
198               Otherwise, any directive name will be accepted.  For exmaple,
199               to only allow directives called "Bar" and "Bif":
200
201                 $config = Config::ApacheFormat->new(
202                                     valid_directives => [qw(Bar Bif)],
203                                                    );
204
205           valid_blocks
206               If you provide an array of block names then syntax errors will
207               be generated during parsing for invalid blocks.  Otherwise, any
208               block name will be accepted.  For exmaple, to only allow
209               "Directory" and "Location" blocks in your config file:
210
211                 $config = Config::ApacheFormat->new(
212                                     valid_blocks => [qw(Directory Location)],
213                                                    );
214
215           include_directives
216               This directive controls the name of the include directive.  By
217               default it is "['Include']", but you can set it to any list of
218               directive names.
219
220           root_directive
221               This controls what the root directive is, if any.  If you set
222               this to the name of a directive it will be used as a base
223               directory for "Include" processing.  This mimics the behavior
224               of "ServerRoot" in real Apache config files, and as such you'll
225               want to set it to 'ServerRoot' when parsing an Apache config.
226               The default is "undef".
227
228           hash_directives
229               This determines which directives (if any) should be parsed so
230               that the first value is actually a key into the remaining
231               values. For example, "AddHandler" is such a directive.
232
233                 AddHandler cgi-script .cgi .sh
234                 AddHandler server-parsed .shtml
235
236               To parse this correctly, use:
237
238                 $config = Config::ApacheFormat->new(
239                                     hash_directives => [qw(AddHandler PerlSetVar)]
240                                                    );
241
242               Then, use the two-argument form of "get()":
243
244                 @values = $config->get(AddHandler => 'cgi-script');
245
246               This allows you to access each directive individually, which is
247               needed to correctly handle certain special-case Apache
248               settings.
249
250           duplicate_directives
251               This option controls how duplicate directives are handled. By
252               default, if multiple directives of the same name are
253               encountered, the last one wins:
254
255                 Port 8080
256                 # ...
257                 Port 5053
258
259               In this case, the directive "Port" would be set to the last
260               value, 5053.  This is useful because it allows you to include
261               other config files, which you can then override:
262
263                 # default setup
264                 Include /my/app/defaults.conf
265
266                 # override port
267                 Port 5053
268
269               In addition to this default behavior, "Config::ApacheFormat"
270               also supports the following modes:
271
272                 last     -  the value from the last one is kept (default)
273                 error    -  duplicate directives result in an error
274                 combine  -  combine values of duplicate directives together
275
276               These should be self-explanatory. If set to "error", any
277               duplicates will result in an error.  If set to "last" (the
278               default), the last value wins. If set to "combine", then
279               duplicate directives are combined together, just like they had
280               been specified on the same line.
281
282           All of the above attributes are also available as accessor methods.
283           Thus, this:
284
285             $config = Config::ApacheFormat->new(inheritance_support => 0,
286                                                 include_support => 1);
287
288           Is equivalent to:
289
290             $config = Config::ApacheFormat->new();
291             $config->inheritance_support(0);
292             $config->include_support(1);
293
294           $config->read("my.conf");
295           $config->read(\*FILE);
296               Reads a configuration file into the config object.  You must
297               pass either the path of the file to be read or a reference to
298               an open filehandle.  If an error is encountered while reading
299               the file, this method will die().
300
301               Calling read() more than once will add the new configuration
302               values from another source, overwriting any conflicting values.
303               Call clear() first if you want to read a new set from scratch.
304
305           "$value = $config->get("var_name")"
306           "@vals = $config->get("list_name")"
307           "$value = $config->get("hash_var_name", "key")"
308               Returns values from the configuration file.  If the directive
309               contains a single value, it will be returned.  If the directive
310               contains a list of values then they will be returned as a list.
311               If the directive does not exist in the configuration file then
312               nothing will be returned (undef in scalar context, empty list
313               in list context).
314
315               For example, given this confiuration file:
316
317                 Foo 1
318                 Bar bif baz bop
319
320               The following code would work as expected:
321
322                 my $foo = $config->get("Foo");   # $foo = 1
323                 my @bar = $config->get("Bar");   # @bar = ("bif", "baz", "bop")
324
325               If the name is the name of a block tag in the configuration
326               file then a list of available block specifiers will be
327               returned.  For example, given this configuration file:
328
329                 <Site big>
330                    Size 10
331                 </Site>
332
333                 <Site small>
334                    Size 1
335                 </Site>
336
337               This call:
338
339                 @sites = $config->get("Site");
340
341               Will return "([ Site =" "big"], [ Site => "small" ])>.  These
342               arrays can then be used with the block() method described
343               below.
344
345               If the directive was included in the file but did not have a
346               value, 1 is returned by get().
347
348               Calling get() with no arguments will return the names of all
349               available directives.
350
351               Directives declared in "hash_directives" require a key value:
352
353                 $handler = $config->get("AddHandler", "cgi-script");
354
355               "directive()" is available as an alias for "get()".
356
357           $block = $config->block("BlockName")
358           $block = $config->block(Directory => "/foo/bar")
359           $block = $config->block(Directory => "~" => "^.*/bar")
360               This method returns a Config::ApacheFormat object used to
361               access the values inside a block.  Parameters specified within
362               the block will be available.  Also, if inheritance is turned on
363               (the default), values set outside the block that are not
364               overwritten inside the block will also be available.  For
365               example, given this file:
366
367                 MaxSize 100
368
369                 <Site "big">
370                    Size 10
371                 </Site>
372
373                 <Site "small">
374                    Size 1
375                 </Site>
376
377               this code:
378
379                 print "Max: ", $config->get("MaxSize"), "\n";
380
381                 $block = $config->block(Site => "big");
382                 print "Big: ", $block->get("Size"), " / ",
383                                $block->get("MaxSize"), "\n";
384
385                 $block = $config->block(Site => "small");
386                 print "Small: ", $block->get("Size"), " / ",
387                                  $block->get("MaxSize"), "\n";
388
389               will print:
390
391                 Max: 100
392                 Big: 10 / 100
393                 Small: 1 / 100
394
395               Note that "block()" does not require any particular number of
396               parameters.  Any number will work, as long as they uniquely
397               identify a block in the configuration file.  To get a list of
398               available blocks, use get() with the name of the block tag.
399
400               This method will die() if no block can be found matching the
401               specifier passed in.
402
403           $config->clear()
404               Clears out all data in $config.  Call before re-calling
405               $config->read() for a fresh read.
406
407           $config->dump()
408               This returns a dumped copy of the current configuration. It can
409               be used on a block object as well. Since it returns a string,
410               you should say:
411
412                   print $config->dump;
413
414               Or:
415
416                   for ($config->block(VirtualHost => '10.1.65.1')) {
417                       print $_->dump;
418                   }
419
420               If you want to see any output.
421

Parsing a Real Apache Config File

423       To parse a real Apache config file (ex. "httpd.conf") you'll need to
424       use some non-default options.  Here's a reasonable starting point:
425
426         $config = Config::ApacheFormat->new(
427                     root_directive     => 'ServerRoot',
428                     hash_directives    => [ 'AddHandler' ],
429                     include_directives => [ 'Include',
430                                             'AccessConfig',
431                                             'ResourceConfig' ],
432                     setenv_vars        => 1,
433                     fix_booleans       => 1);
434

TODO

436       Some possible ideas for future development:
437
438       ·   Add a set() method.  (useless?)
439
440       ·   Add a write() method to create a new configuration file.
441           (useless?)
442

BUGS

444       I know of no bugs in this software.  If you find one, please create a
445       bug report at:
446
447         http://rt.cpan.org/
448
449       Include the version of the module you're using and a small piece of
450       code that I can run which demonstrates the problem.
451
453       Copyright (C) 2002-2003 Sam Tregar
454
455       This program is free software; you can redistribute it and/or modify it
456       under the same terms as Perl 5 itself.
457

AUTHORS

459       Sam Tregar <sam@tregar.com>
460           Original author and maintainer
461
462       Nathan Wiger <nate@wiger.org>
463           Porting of features from Apache::ConfigFile
464

SEE ALSO

466       Apache::ConfigFile
467
468       Apache::ConfigParser
469

POD ERRORS

471       Hey! The above document had some coding errors, which are explained
472       below:
473
474       Around line 94:
475           '=item' outside of any '=over'
476
477       Around line 1019:
478           You forgot a '=back' before '=head1'
479
480       Around line 1070:
481           '=item' outside of any '=over'
482
483       Around line 1078:
484           You forgot a '=back' before '=head1'
485
486
487
488perl v5.32.0                      2020-07-28                   ApacheFormat(3)
Impressum