/ 
Config-ApacheExtended-1.16
River stage zero No dependents
/ Config::ApacheExtended

NAME

Config::ApacheExtended - use extended apache format config files

SYNOPSIS

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";
            }
        }
    }
}

DESCRIPTION

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.

METHODS

new

Usage : Config::AapcheExtended->new( %options )

Purpose : Construct a new Config::ApacheExtended object

Returns : A new Config::ApacheExtended object, or undef on error.

Arguments :

source - path string

The relative or absolute path to the configuration file. If a relative path is given, it is resolved using File::Spec::rel2abs

expand_vars - boolean

Turn on variable expansion support. (See "VARIABLE SUBSTITUTION")

Defaults to OFF.

conf_root - path string

The directory to use as the base for relative path resolutions (i.e. for include statements)

root_directive - string

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".

honor_include - boolean

Set this option to false to turn off include support.

Defaults to ON.

inherit_vals - boolean

If this option is set value inheritance will be enabled.

Defaults to OFF.

ignore_case - boolean

If this option is turned off then directives and block names are case sensitive.

Defaults to ON.

die_on_nokey - boolean

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.

Defaults to OFF.

die_on_noblock - boolean

Same as die_on_noblock, except for the block() method. These two options are here to help emulate behaviour in Config::ApacheFormat.

Defaults to OFF.

valid_directives - Array Ref

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.

valid_blocks - Array Ref

This option is the same as valid_directives except it applies to block specifiers.

parse

    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);

get

    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);

block

    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()

    For Example:

      # 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());
	  }
  }

as_hash

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.

VARIABLE SUBSTITUTION

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.

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.

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.

BUGS

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])

SUPPORT

You can email me, I can't promise response times. If I start getting a lot of mail I'll start a list.

AUTHOR

Michael Grubb
mgrubb@cpan.org
http://www.fifthvision.net  -- This is junk right now.

COPYRIGHT

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.

SEE ALSO

perl(1).