1ApacheFormat(3) User Contributed Perl Documentation ApacheFormat(3)
2
6 Config::ApacheFormat - use Apache format config files
7
9 Config files used with this module are in Apache's format:
10 # comment here
12 RootDir /path/foo
13 LogDir /path/foo/log
14 Colors red green orange blue \
15 black teal
16 <Directory /path/foo>
18 # override Colors inside block
19 Colors red blue black
20 </Directory>
21 Code to use this config file might look like:
23 use Config::ApacheFormat;
25 # load a conf file
27 my $config = Config::ApacheFormat->new();
28 $config->read("my.conf");
29 # access some parameters
31 $root_dir = $config->get("RootDir");
32 $log_dir = $config->get("LogDir");
33 @colors = $config->get("colors");
34 # using the autoloaded methods
36 $config->autoload_support(1);
37 $root_dir = $config->RootDir;
38 $log_dir = $config->logdir;
39 # 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
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 A good reference to the Apache configuration file format can be found
55 here:
56 http://httpd.apache.org/docs-2.0/configuring.html
58 To quote from that document, concerning directive syntax:
60 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 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 And block notation:
75 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 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
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 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 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 autoload_support
112 Set this to 1 and all your directives will be available as
113 object methods. So instead of:
114 $config->get("foo");
116 You can write:
118 $config->foo;
120 Defaults to 0.
122 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 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 For example:
135 # httpd.conf
137 UseCanonicalName On
138 Then in Perl:
140 $config = Config::ApacheFormat->new(fix_booleans => 1);
142 $config->read("httpd.conf");
143 if ($config->get("UseCanonicalName")) {
145 # this will get executed if set to Yes/On/True
146 }
147 This option defaults to 0.
149 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 Website http://my.own.dom
156 JScript $Website/js
157 Images $Website/images
158 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 Nickname Rob
165 Fullname ${Nickname}ert
166 Since only scalars are supported, if you use a multi-value, you
168 will only get back the first one:
169 Options Plus Minus "About the Same"
171 Values $Options
172 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 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 For example:
183 # $ENV{PATH} = "/usr/sbin:/usr/bin"
185 SetEnv PATH "/usr/sbin:/usr/bin"
186 # $ENV{MY_SPECIAL_VAR} = 10
188 SetEnv MY_SPECIAL_VAR 10
189 # delete $ENV{THIS}
191 UnsetEnv THIS
192 This option defaults to 0.
194 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 $config = Config::ApacheFormat->new(
202 valid_directives => [qw(Bar Bif)],
203 );
204 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 $config = Config::ApacheFormat->new(
212 valid_blocks => [qw(Directory Location)],
213 );
214 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 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 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 AddHandler cgi-script .cgi .sh
234 AddHandler server-parsed .shtml
235 To parse this correctly, use:
237 $config = Config::ApacheFormat->new(
239 hash_directives => [qw(AddHandler PerlSetVar)]
240 );
241 Then, use the two-argument form of "get()":
243 @values = $config->get(AddHandler => 'cgi-script');
245 This allows you to access each directive individually, which is
247 needed to correctly handle certain special-case Apache
248 settings.
249 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 Port 8080
256 # ...
257 Port 5053
258 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 # default setup
264 Include /my/app/defaults.conf
265 # override port
267 Port 5053
268 In addition to this default behavior, "Config::ApacheFormat"
270 also supports the following modes:
271 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 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 All of the above attributes are also available as accessor methods.
283 Thus, this:
284 $config = Config::ApacheFormat->new(inheritance_support => 0,
286 include_support => 1);
287 Is equivalent to:
289 $config = Config::ApacheFormat->new();
291 $config->inheritance_support(0);
292 $config->include_support(1);
293 $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 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 "$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 For example, given this confiuration file:
316 Foo 1
318 Bar bif baz bop
319 The following code would work as expected:
321 my $foo = $config->get("Foo"); # $foo = 1
323 my @bar = $config->get("Bar"); # @bar = ("bif", "baz", "bop")
324 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 <Site big>
330 Size 10
331 </Site>
332 <Site small>
334 Size 1
335 </Site>
336 This call:
338 @sites = $config->get("Site");
340 Will return "([ Site =" "big"], [ Site => "small" ])>. These
342 arrays can then be used with the block() method described
343 below.
344 If the directive was included in the file but did not have a
346 value, 1 is returned by get().
347 Calling get() with no arguments will return the names of all
349 available directives.
350 Directives declared in "hash_directives" require a key value:
352 $handler = $config->get("AddHandler", "cgi-script");
354 "directive()" is available as an alias for "get()".
356 $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 MaxSize 100
368 <Site "big">
370 Size 10
371 </Site>
372 <Site "small">
374 Size 1
375 </Site>
376 this code:
378 print "Max: ", $config->get("MaxSize"), "\n";
380 $block = $config->block(Site => "big");
382 print "Big: ", $block->get("Size"), " / ",
383 $block->get("MaxSize"), "\n";
384 $block = $config->block(Site => "small");
386 print "Small: ", $block->get("Size"), " / ",
387 $block->get("MaxSize"), "\n";
388 will print:
390 Max: 100
392 Big: 10 / 100
393 Small: 1 / 100
394 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 This method will die() if no block can be found matching the
401 specifier passed in.
402 $config->clear()
404 Clears out all data in $config. Call before re-calling
405 $config->read() for a fresh read.
406 $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 print $config->dump;
413 Or:
415 for ($config->block(VirtualHost => '10.1.65.1')) {
417 print $_->dump;
418 }
419 If you want to see any output.
421
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 $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
436 Some possible ideas for future development:
437 • Add a set() method. (useless?)
439 • Add a write() method to create a new configuration file.
441 (useless?)
442
444 I know of no bugs in this software. If you find one, please create a
445 bug report at:
446 http://rt.cpan.org/
448 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 This program is free software; you can redistribute it and/or modify it
456 under the same terms as Perl 5 itself.
457
459 Sam Tregar <sam@tregar.com>
460 Original author and maintainer
461 Nathan Wiger <nate@wiger.org>
463 Porting of features from Apache::ConfigFile
464
466 Apache::ConfigFile
467 Apache::ConfigParser
469
471 Hey! The above document had some coding errors, which are explained
472 below:
473 Around line 94:
475 '=item' outside of any '=over'
476 Around line 1019:
478 You forgot a '=back' before '=head1'
479 Around line 1070:
481 '=item' outside of any '=over'
482 Around line 1078:
484 You forgot a '=back' before '=head1'
485perl v5.32.1 2021-01-27 ApacheFormat(3)