Config::ApacheExtended - use extended apache format config files
use Config::ApacheExtended my $conf = Config::ApacheExtended->new(source => "t/parse.conf"); $conf->parse() or die "Unsuccessful Parsing of config file"; # Print out all the Directives foreach ($conf->get()) { print "$_ => " . $conf->get($_) . "\n"; } # Show all the blocks at the root foreach ($conf->block()) { foreach ($conf->block($_)) { print $_->[0] . " => " . $_->[1] . "\n"; foreach ($conf->block(@$_)) { my $block = $_; foreach ($block->get()) { print "$_ => " . $block->get($_) . "\n"; } } } }
This module is used to parse a configuration file similar to that of the Apache webserver (see http://httpd.apache.org for more details). This module provides several extensions to that syntax, namely variable substitution and Hereto documents. Other features include, value inheritance, directive and block validation, and include support. This module also handles quoted strings and split lines properly.
Usage : Config::AapcheExtended->new( %options )
Purpose : Construct a new Config::ApacheExtended object
Returns : A new Config::ApacheExtended object, or undef on error.
The relative or absolute path to the configuration file. If a relative path is given, it is resolved using File::Spec::rel2abs
Turn on variable expansion support. (See "VARIABLE SUBSTITUTION")
Defaults to OFF.
The directory to use as the base for relative path resolutions (i.e. for include statements)
If this option is set then it will be used as conf_root. This is handy if parsing an apache config file set it to "ServerRoot".
Set this option to false to turn off include support.
Defaults to ON.
If this option is set value inheritance will be enabled.
If this option is turned off then directives and block names are case sensitive.
If this option is turned on then get() will die if the given key is not found, when this option is off get() will return undef when the key is not found.
Same as die_on_noblock, except for the block() method. These two options are here to help emulate behaviour in Config::ApacheFormat.
This option allows you to specify a list of valid directives. If the parser comes across any directive not in this list, it will fail.
This option is the same as valid_directives except it applies to block specifiers.
Usage : $conf->parse( source );
Purpose : Causes the Config::ApacheExtended object to parse the given source.
Returns : undef on error, number of top level directives found if successful.
Argument : Optional. The source to parse. This argument gives some more options than what the source argument to new() allows. This can be a filehandle (GLOB or IO::File), a relative or absolute path string, or a reference to a scalar holding the contents to parse.
Throws : Croaks on unresolvable path string.
For example:
my $contents = "DirectiveA valueA\n" . "DirectiveB valueB\n" . "<BlockC valuec>\n" . "DirectiveD valueD\n" . "</BlockC>\n"; my $conf = Config::ApacheExtended->new(); $conf->parse(\$contents);
Usage : get( DirectiveName )
Purpose : Retrieve a value, or a list of directives in current block.
Returns : If a directive has a single value associated with it get() returns that value as a scalar regardless of context, if a directive has more than one value and get() is called in a list context then a list is returned, if get() is called in a scalar context, then an anonymous array is returned. If no directive can be found an empty list or undef is returned respective of the context in which get() was called. If no directive is given then a list of keys in the current block is returned.
Argument : Optional. Directive name
Throws : Only if die_on_nokey is turned ON.
See Also : block()
For Example:
# Print out a list of all this block's directives my @directives = $conf->get(); map { print "$_\n" } @directives; my @vals = $conf->get('Bar') or die "Could not find 'Bar'"; print join(", ", @vals); my $vals = $conf->get('Bar'); print join(", ", @$vals);
Usage : block( BlockType => BlockName )
Purpose : Retrieve a list of all blocks in the current block, a list of a given block type in the current block, or a specific block.
Returns : If no BlockType is given, then a list of available BlockTypes is returned. If given a BlockType then block() returns a list of anonymous arrays, which contain the block type followed by the block name of all the blocks of the given type in the current block. This is so that retrieving a block from the list is more convenient. If a specific block is requested, then a new Config::ApacheExtended object is returned. This object only contains the values and blocks associated with the requested block.
Argument : Optional. BlockType <Optional.> BlockName
Throws : Only if die_on_noblock is turned ON.
See Also : get()
# Print out a list of all the BlockTypes in this block my @blocktypes = $conf->block(); map { print "$_\n" } @blocktypes; # Print out all the block names of each BlockType foreach my $blocktype (@blocktypes) { my @blocks = $conf->block($blocktype); # Print the block name and list of keys for each block print "$blocktype:\n"; foreach my $blockspec (@blocks) { print "\t" . $blockspec->[1] . "\n"; my $block = $conf->block(@$blockspec); map { print "\t\t$_\n" } ($block->get()); } }
Usage : as_hash() Purpose : Returns the current block's data as a hash Returns : a copy of the current block's data as a hash ref. Comments : Don't use this. It is Dangerous.
It just occured to me that this section has been omitted for some time. Sorry. Variable substitution is supported in one of three ways. Given the configuration:
ValList1 myval1 myval2 ValList2 myval3 myval4 MyVal @ValList1 @ValList2 OddVal thatval1 @ValList1 thatval2 Stringification "The (@ValList1) is a list of two values" AnotherVal $ValList1 YetAnotherVal $ValList2[1]
Retrieving MyVal will yield a list with 4 values namely: myval1, myval2, myval3, myval4. Retrieving OddVal will also yield a list with 4 values: thatval1, myval1, myval2, thatval2. Retrieving AnotherVal will yeild myval1. Retrieving YetAnotherVal will yield: myval4. Retrieving Stringification will yield the string: The (myval1 myval2) is a list of two values.
MyVal
OddVal
AnotherVal
YetAnotherVal
Stringification
So this leads to the conclusion that:
The "$" prefix substitutes the first/only value of another directive.
The "$" prefix used with the index N after the directive name will substitute the Nth value of the other directive. Indexes are zero indexed just as Perl array indexes are.
The "@" prefix substitutes the entire value list of the other directive in place.
The "@" prefix will substitute the entire value list joined on the $LIST_SEPARATOR if it occurs within a quoted string. NOTE: That "@SomeVal" will not cause stringification of the list. I'm working on this.
$LIST_SEPARATOR
"@SomeVal"
This behaviour has only slightly changed from 1.15 to 1.16. The difference is that the "@" prefix now causes the entire list to be substituted rather than having the values joined with the $LIST_SEPARATOR character. Also note that substitution WILL occur inside single quotes. This is a limitation of the current implementation, as I do not have enough hints at substitution time to know whether the values where inside single or double quotes. I welcome patches/suggestions to fix this.
This not really a bug, more of a Todo, however This module does not currently provide access to multiple block "names" (i.e. <BlockType blockval1 blockval2>...</BlockType>) However, it will parse these blocks properly. The only thing that needs to be done is to provide space in the data structure for these values, they were not important to me, so I didn't see the need. However, I am willing to accept patches.
Other than that, I have found no bugs, but I'm sure there are some lurking about. (Example code is for the most part untested, [I'm working on this, I just wanted to get the documentation done])
You can email me, I can't promise response times. If I start getting a lot of mail I'll start a list.
Michael Grubb mgrubb@cpan.org http://www.fifthvision.net -- This is junk right now.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
perl(1).
To install Config::ApacheExtended, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Config::ApacheExtended
CPAN shell
perl -MCPAN -e shell install Config::ApacheExtended
For more information on module installation, please visit the detailed CPAN module installation guide.