SYNOPSIS

# # Parse the standard Apache httpd.conf # use Apache::ConfigFile; my $ac = Apache::ConfigFile->read("/etc/apache/httpd.conf"); # You can get at individual configuration commands using # the cmd_config() method: my $hostname = $ac->cmd_config('ServerName'); my $doc_root = $ac->cmd_config('DocumentRoot'); # Multiple values are returned as a list, meaning that you # can directly assign them to an array: my @perlmods = $ac->cmd_config('PerlModule'); # And, you can use the cmd_config_hash() routine to get at # multiple settings where the first is a type of "key": my %ftypes = $ac->cmd_config_hash('FileTypeSuffix'); # Then, you can reset the context of the calls using the # cmd_context() method so that you are accessing the # appropriate values. For example, if you had a context # block like # # <VirtualHost "10.1.1.2"> # ServerName "www.mydomain.com" # DocumentRoot "/www/mydomain.com/htdocs" # </VirtualHost> # # You would get to this definition via: my $vh = $ac->cmd_context(VirtualHost => '10.1.1.2'); my $vhost_server_name = $vh->cmd_config('ServerName'); my $vhost_doc_root = $vh->cmd_config('DocumentRoot'); # If you had multiple VirtualHost declarations for a # given IP (as would be the case if you're using # NameVirtualHosts), you could cycle through them with: for my $vh ($ac->cmd_context(VirtualHost => '10.1.1.3')) { my $vhost_server_name = $vh->cmd_config('ServerName'); my $vhost_doc_root = $vh->cmd_config('DocumentRoot'); } # In fact, even better you can "search" for one by specifying # an additional set of criteria to cmd_config(). To just get # the VirtualHost "docs.mydomain.com", for example, try:

DESCRIPTION

This module parses the Apache httpd.conf, or any compatible config
file, and provides methods for you to access the values from the
config file. The above examples show basic usage of this module,
which boils down to reading a given config file and then using
the "cmd_config()" and "cmd_context()" functions to access its
information.

By default, the config file is parsed more or less ``verbatim'',
meaning that directives are case-sensitive, variables are not
interpolated, and so forth. These features can be changed by
options given to the "read()" function (see below).

The "read()" function is the constructor, which reads in a
configuration file and returns an object with methods that can
be used to access directives from the file. The simplest usage
is something like this:

Which would parse the Apache "httpd.conf" file and give you back
an $ac object with the following methods:

cmd_config()

Used to access individual configuration commands

cmd_context()

Used to change the context of the commands you're accessing

dir_config()

Used to access values set via the "PerlSetVar" command (like "mod_perl")

For more examples of standard Apache usage, you should read the
``SYNOPSIS'' above or skip down to the ``FUNCTIONS''.

In addition to reading an Apache config file, this module provides
some options that allow the Apache syntax to be extended. This is
useful if you're writing your own application and want to use a
config file resembling Apache's.

There are several things to note. First, all our "cmd_" functions
are now case-insensitive, since we turned on the "ignore_case"
flag (which is off by default). Second, notice a couple things
about our "unless" statement. Since we specified "fix_booleans",
the words ``Yes'', ``True'', and ``On'' will be converted to 1 (true),
and ``No'', ``False'', and ``Off'' will become 0 (false). As such,
we can use these directives in boolean statements throughout our
code.

In addition, since this module provides autoloading so that all
config commands are turned into functions, you can access values
directly, as shown by the statement "$rel->supported". This
statement is equivalent to the longer "$rel->cmd_config('supported')".

Finally, if you just wish to manually navigate the data structure
(which is a huge hash of hashes of arrays) without using the
accessor functions, you can return the thing verbatim:

my %conf = $ac->data;
print "Release is $conf{'release'}\n";

However, note that the internal representation is subject to change,
so using the accessor functions is recommended.

FUNCTIONS

read(filename)

read(file => filename, opt => val, opt => val)

The "read()" function reads the configuration file specified and
returns an object with methods to access its directives. "read()"
has two calling forms. In the simplest version, you just specify
a filename, and a new "Apache::ConfigFile" object is returned.
Or, if you want to specify options, you specify each one as a
key/value pair. For example:

Path to configuration file. If not provided then
"/usr/local/apache/conf/httpd.conf" is used by default.

ignore_case

If set to 1, then all directives will be case-insensitive
and stored in lowercase. Defaults to 0.

fix_booleans

If set to 1, then the words ``Yes'', ``True'', and ``On'' will be
converted to 1 (true), and ``No'', ``False'', and ``Off'' will
become 0 (false). This allows you to easily use these
types of directives in if statements. Defaults to 0.

expand_vars

If set to 1, then you can reuse variables that you have
defined elsewhere in the config file by prefixing them
with a "$". For example:

BaseDir "/export"
HomeDir "$BaseDir/home"

Currently, you can only reuse variables defined at the very
top-level. Variables defined within context blocks of any
kind cannot be reused.

raise_error

If set to 1, any type of error becomes fatal. Defaults to 0.

cmd_config(directive)

This is the meat-and-potatoes of the module; the method that
lets you access configuration directives from your file.
Examples:

This is a fairly straightforward function. You just give it the
name of the directive you wish to access and you get its value back.
Each time you call it, you will get the value for the next available
instance of that variable. If called in a scalar context, you will
just get the first value, assumed to be the ``key''.

Code is 404 and script is /errors/404.cgi
Code is 500 and script is /errors/500.cgi

Assuming the same configuration as above.

cmd_config_hash(directive)

This is perhaps the most useful form. It returns a set of key/value
pairs where the key is the first element and the value is the
rest of the line. This is great for handling "FileTypeSuffix"
or "AddHandler" lines, for example:

my %handler = $ac->cmd_config_hash('AddHandler');

This would return a hash where the keys would be the first field,
such as "cgi-script" or "server-parsed", and value is the
remaining line as an array reference.

As such, you could access a specific one as:

print "Suffixes for CGI scripts are: @{$handler{cgi-script}}\n";

Which should print out something like this:

Suffixes for CGI scripts are: .cgi .pl

Note that you had to derefence the value inside of a "@{}" since
the value is an array reference. This is so that you can get a list
of values reliably. For example:

That way you could use an Apache style config file to setup a
custom form based application.

cmd_context(context => specification)

You use this command to change the current context of what you
are looking at. When you start, you are looking at the very
top-level of the config file. However, you may want to look
at a specific virtual host or directory. You can do so with
this command.

You'll notice that the "cmd_context()" call returns an
object will all the same methods, but the data structure
now starts from that point down. The context has been altered
so that you are looking at the "<VirtualHost "10.1.1.2">".
block. As such, any commands that you do will affect that part
of the configuration.

In some cases, you may have multiple definitions for a certain
context level. One example is "VirtualHost" blocks if you're
using "NameVirtualHosts". You have two options. First, you
could cycle through all of them in sequence:

However, you may not know what you're looking for. In this case,
if you just want to get the ``keys'' of all the "VirtualHost"
definitions and then iterate through all of them, you might do
something like this:

Since "cmd_context()" returns an object pointing to the next
context, you can chain calls together to get to a deeply nested
level.

dir_config()

This routine is provided for "mod_perl" compatibility. It allows
you to access configuration commands specified via the "PerlSetVar"
directive. So, assuming the above example, you could access the
settings for "MyUploadModule" like so:

Note, though, that the following would not work unless you had
set the "ignore_case" option:

my $doc_root = $ac->documentroot; # won't work

This is because it will look for the directive "Documentroot",
which probably doesn't exist.

ALIASES

When I initially wrote this module, I tried to follow the internal
Apache API pretty closely. However, for those unfamiliar with
Apache these method names probably make little sense. As such,
the following function aliases are provided

NOTES

Currently "LogFormat" and any other directive with embedded quotes,
even if escaped, are not handled correctly. I know there is a fix for
it but I have a mental block and can't figure it out. Help!

This module does not mimic the behavior of a live Apache config.
In particular, there is no configuration ``inheritance''. This means
that subdirectories and virtual hosts do not inherit their defaults
from the upper levels of the configuration. This may or may not
change in a future version.

Currently, the order of context blocks is not maintained. So, if
you define two blocks:

There will be no way for you to tell the order in which these were defined.
Normally this should not matter, since the idea of a context section is to
create a logical entity. However, patches to overcome this limitation
are welcomed.

This module has only been tested and used on UNIX platforms. Patches
to fix problems with other OSes are welcome.