NAME

Config::ApacheFormat - use Apache format config files

SYNOPSIS

Config files used with this module are in Apache's format:

  # comment here
  RootDir /path/foo
  LogDir  /path/foo/log
  Colors red green orange blue \
         black teal

  <Directory /path/foo>
     # override Colors inside block
     Colors red blue black
  </Directory>
  

Code to use this config file might look like:

  use Config::ApacheFormat;

  # load a conf file
  my $config = Config::ApacheFormat->new();
  $config->read("my.conf");

  # access some parameters
  $root_dir = $config->get("RootDir");
  $log_dir  = $config->get("LogDir");
  @colors   = $config->get("colors");

  # using the autoloaded methods
  $config->autoload_support(1);
  $root_dir = $config->RootDir;
  $log_dir  = $config->logdir;

  # access parameters inside a block
  my $block = $config->block(Directory => "/path/foo");
  @colors = $block->get("colors");
  $root_dir = $block->get("root_dir");

DESCRIPTION

This module is designed to parse a configuration file in the same syntax used by the Apache web server (see http://httpd.apache.org for details). This allows you to build applications which can be easily managed by experienced Apache admins. Also, by using this module, you'll benefit from the support for nested blocks with built-in parameter inheritence. This can greatly reduce the amount or repeated information in your configuration files.

A good reference to the Apache configuration file format can be found here:

  http://httpd.apache.org/docs-2.0/configuring.html

To quote from that document, concerning directive syntax:

 Apache configuration files contain one directive per line. The
 back-slash "\" may be used as the last character on a line to
 indicate that the directive continues onto the next line. There must
 be no other characters or white space between the back-slash and the
 end of the line.

 Directives in the configuration files are case-insensitive, but
 arguments to directives are often case sensitive. Lines that begin
 with the hash character "#" are considered comments, and are
 ignored. Comments may not be included on a line after a configuration
 directive. Blank lines and white space occurring before a directive
 are ignored, so you may indent directives for clarity.

And block notation:

 Directives placed in the main configuration files apply to the entire
 server. If you wish to change the configuration for only a part of the
 server, you can scope your directives by placing them in <Directory>,
 <DirectoryMatch>, <Files>, <FilesMatch>, <Location>, and
 <LocationMatch> sections. These sections limit the application of the
 directives which they enclose to particular filesystem locations or
 URLs. They can also be nested, allowing for very fine grained
 configuration.

RATIONALE

There are at least two other modules on CPAN that perform a similar function to this one, Apache::ConfigFile and Apache::ConfigParser. Although both are close to what I need, neither is totally satisfactory.

Apache::ConfigFile suffers from a complete lack of tests and a rather clumsy API. Also, it doesn't support quoted strings correctly.

Apache::ConfigParser comes closer to my needs, but contains code specific to parsing actual Apache configuration files. As such it is unsuitable to parsing an application configuration file in Apache format. Unlike Apache::ConfigFile, Apache::ConfigParser lacks support for Include.

Additionally, neither module supports directive inheritence within blocks. As this is the main benefit of Apache's block syntax I decided I couldn't live without it.

In general, I see no problem with reinventing the wheel as long as you're sure your version will really be better. I believe this is, at least for my purposes.

METHODS

$config = Config::ApacheFormat->new(opt => "value")

This method parses a config file and returns an object that may be used to access the data contained within. The object supports the following attributes, all of which may be set through new():

inheritence_support

Set this to 0 to turn off the inheritence feature, Block inheritence means that variables declared outside a block are available from inside the block unless overriden. Defaults to 1.

include_support

When this is set to 1, the directive "Include" will be treated specially by the parser. It will cause the value to be treated as a filename and that filename will be read in. This matches Apache's behavior and allows users to break up configuration files into multiple, possibly shared, pieces. Defaults to 1.

autoload_support

Set this to 1 and all your directives will be available as object methods. So instead of:

  $config->get("foo");

You can write:

  $config->foo;

Defaults to 0.

case_sensitive

Set this to 1 to preserve the case of directive names. Otherwise, all names will be lc()ed and matched case-insensitively. Defaults to 0.

All of these attributes are also available as accessor methods. Thus, this:

 $config = Config::ApacheFormat->new(inheritence_support => 0,
                                     include_support => 1);

Is equivalent to:

 $config = Config::ApacheFormat->new();
 $config->inheritence_support(0);
 $config->include_support(1);

$config->read("my.conf");

$config->read(\*FILE);

Reads a configuration file into the config object. You must pass either the path of the file to be read or a reference to an open filehandle. If an error is encountered while reading the file, this method will die().

Calling read() more than once will add the new configuration values from another source, overwriting any conflicting values. Call clear() first if you want to read a new set from scratch.

$value = $config->get("var_name")

Returns a value from the configuration file. If the directive contains a single value, it will be returned. If the directive contains a list of values then they will be returned as a list. If the directive does not exist in the configuration file then nothing will be returned (undef in scalar context, empty list in list context).

For example, given this confiuration file:

  Foo 1
  Bar bif baz bop

The following code would work as expected:

  my $foo = $config->get("Foo");   # $foo = 1
  my @bar = $config->get("Bar");   # @bar = ("bif", "baz", "bop")

If the name is the name of a block tag in the configuration file then a list of available block specifiers will be returned. For example, given this configuration file:

  <Site big>
     Size 10
  </Site>

  <Site small>
     Size 1
  </Site>

This call:

  @sites = $config->get("Site");

Will return ([ Site = "big"], [ Site => "small" ])>. These arrays can then be used with the block() method described below.

Calling get() with no arguments will return the names of all available directives.

$block = $config->block("BlockName")

$block = $config->block(Directory => "/foo/bar")

$block = $config->block(Directory => "~" => "^.*/bar")

This method returns a Config::ApacheFormat object used to access the values inside a block. Parameters specified within the block will be available. Also, if inheritence is turned on (the default), values set outside the block that are not overwritten inside the block will also be available. For example, given this file:

  MaxSize 100

  <Site "big">
     Size 10
  </Site>

  <Site "small">
     Size 1
  </Site>

this code:

  print "Max: ", $config->get("MaxSize"), "\n";

  $block = $config->block(Site => "big");
  print "Big: ", $block->get("Size"), " / ", 
                 $block->get("MaxSize"), "\n";

  $block = $config->block(Site => "small");
  print "Small: ", $block->get("Size"), " / ", 
                   $block->get("MaxSize"), "\n";

will print:

  Max: 100
  Big: 10 / 100
  Small: 1 / 100

Note that block() does not require any particular number of parameters. Any number will work, as long as they uniquely identify a block in the configuration file. To get a list of available blocks, use get() with the name of the block tag.

This method will die() if no block can be found matching the specifier passed in.

$config->clear()

Clears out all data in $config. Call before re-calling $config->read() for a fresh read.

TODO

Some possible ideas for future development:

• Unroll the recursion in get() for faster access to inherited values.

• Add a set() method. (useless?)

• Add a write() method to create a new configuration file. (useless?)

BUGS

I know of no bugs in this software. If you find one, please create a bug report at:

  http://rt.cpan.org/

Include the version of the module you're using and a small piece of code that I can run which demonstrates the problem.

COPYRIGHT AND LICENSE

Copyright (C) 2002 Sam Tregar

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.

AUTHOR

Sam Tregar <sam@tregar.com>

SEE ALSO

Apache::ConfigFile

Apache::ConfigParser

cpanm Config::ApacheFormat

perl -MCPAN -e shell
install Config::ApacheFormat