Help-Site Computer Manuals
  Algorithms & Data Structures   Programming Languages   Revision Control
  Cameras   Computers   Displays   Keyboards & Mice   Motherboards   Networking   Printers & Scanners   Storage
  Windows   Linux & Unix   Mac

use extended apache format config files

Config::ApacheExtended - use extended apache format config files


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

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.


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 the IO::File manpage), 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" .


  my $conf = Config::ApacheExtended->new();



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

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




 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.

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.


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