NAME
    Apache::ConfigFile - Parse an Apache style httpd.conf config file

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 or even a hash:

        my @perlmods = $ac->cmd_config('PerlModule');
        my %ftypes   = $ac->cmd_config('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:
 
        my $docs_svr = $ac->cmd_context(VirtualHost => '10.1.1.3',
                                        ServerName  => 'docs.mydomain.com');
        my $docs_base_dir = $docs_svr->cmd_config('DocumentRoot');

        # In addition, this module will automatically autoload
        # directive-based functions, meaning you can get to
        # commonly-used commands by name:

        my $host = $ac->server_name;
        my $root = $ac->server_root;
        my $html = $ac->document_root;

        # You also get the mod_perl dir_config() command to get
        # at PerlSetVar declarations by name. So, the block:
        #
        #   <Location /myapp>
        #       SetHandler perl-script
        #       PerlHandler Apache::MyApp
        #       PerlSetVar MyAppRoot "/usr/myapp"
        #       PerlSetVar MyAppRefresh "30m"
        #   </Location>
        #
        # Would be accessed as:

        my $loc = $ac->cmd_context(Location => '/myapp');
        my $app_root = $loc->dir_config('MyAppRoot');
        my $app_refr = $loc->dir_config('MyAppRefresh');

        # Finally, you get two other utility methods. The first
        # will return the current data structure verbatim, and
        # the second one will return a dump which you can print
        # out or parse or whatever:

        my %config = $self->data;
        warn "DEBUG: ", $self->dump, "\n";

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:

        use Apache::ConfigFile;
        my $ac = Apache::ConfigFile->read("/path/to/httpd.conf");

    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 (for
        "mod_perl")

    For more examples of standard Apache usage, you should read the the
    section on "SYNOPSIS" above or skip down to the the section on
    "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.

        use Apache::ConfigFile;
        my $ac = Apache::ConfigFile->read(
                        file => "/path/to/httpd.conf",
                        ignore_case  => 1,
                        expand_vars  => 1,
                        fix_booleans => 1
                 );

    These options would allow us to write a custom config file looking like
    this:

        BaseDir    "/export"
        ImageDir   "$BaseDir/images"
        BuildDir   "$BaseDir/images"

        <Release "sw7">
            OfficialName "Software Update 7"
            BuildPath "$BuildDir/sw7/REL"         
            Platforms Solaris Linux IRIX HP-UX
            Supported Yes
        </Release>

    Then, you would be able to access it as follows:

        use Apache::ConfigFile;
        my $swcfg = Apache::ConfigFile->read("releases.conf");

        # Note that case does not matter
        my $rel = $swcfg->cmd_context(release => 'sw7');
        my $ofn = $rel->cmd_config('bUiLdPaTh');
    
        # This is autoloading + fix_booleans
        unless ($rel->supported) {
            die "Sorry, that release is not supported";
        } 

    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:

       # keep default options
       my $ac = Apache::ConfigFile->read("httpd.conf");

       # override the case sensitivity and boolean translation
       my $ac = Apache::ConfigFile->read(file => "httpd.conf",
                                         ignore_case  => 1,
                                         fix_booleans => 1);

    The list of valid options is:

    file
        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:

        my $server_name = $ac->cmd_config('ServerName');
        my $doc_root = $ac->cmd_config('DocumentRoot');

    This is a straightforward function. You just give it the name of the
    directive you wish to access and you get its value back. Multiple values
    are returned as a list, meaning that you can directly assign them to an
    array or even a hash (if the data structure is guaranteed to be
    consistent enough):

        my @perlmods = $ac->cmd_config('PerlModule');
        my %ftypes   = $ac->cmd_config('FileTypeSuffix');

  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.

        my $vhost = $ac->cmd_context(VirtualHost => '10.1.1.2');
        my $server_name = $vhost->cmd_config('ServerName');
        my $doc_root    = $vhost->cmd_config('DocumentRoot');

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

        for my $vhost ($ac->cmd_context(VirtualHost => '10.1.1.2')) {
            # ... do stuff ...
        }

    Or, if you know which one you want specifically, you can specify one
    additional "search" parameter. For example, if you want the "superfoo"
    server, you could say:

        my $sf = $ac->cmd_context(VirtualHost => '10.1.1.2',
                                  ServerName  => 'superfoo');

    And this would look for a context block that looked something like this:

        <VirtualHost "10.1.1.2">
            ServerName "superfoo"
            # ... more config options ...
        </VirtualHost>

    You can access nested configurations as well. If you had a configuration
    like this:

        <Location "/upload">
            SetHandler perl-script
            PerlHandler Apache::MyUploadModule
            PerlSetVar MyUploadModuleMaxsize "5M"
            PerlSetVar MyUploadModuleTimeout "300s"
            <Limit>
                require user "bob"
                require user "jim"
            </Limit>
        </Location>

    And you wanted to find out what the valid users were who could access
    this page, you would navigate it like so:

        my $loc = $ac->cmd_context(Location => '/upload');
        my $lim = $loc->cmd_context('Limit');
        my @users = $lim->cmd_config('require');

    Or, more succintly:

        my @users = $ac->cmd_context(Location => '/upload')
                       ->cmd_context('Limit')->cmd_config('require');

    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:

        my $upload = $ac->cmd_context(Location => '/upload');

        my $maxsize = $upload->dir_config('MyUploadModuleMaxsize');
        my $timeout = $upload->dir_config('MyUploadModuleTimeout');

    The idea is to provide an interface which walks and talks roughly like
    Apache actually would.

  data()

    This returns the entire data structure under the current context
    verabatim. So, you could get all the values for a "VirtualHost" with:

        my $vh = $ac->cmd_context(VirtualHost => '10.1.1.4');
        my %vhost = $vh->data;

    If you specified "ignore_case", then all the keys will be lowercase;
    otherwise, they will be in whatever case they are in the config file.

  dump()

    This returns a dump of the current data structure in string form. So for
    debugging purposes you can dump the config with something like this:

        warn "DUMP: ", $ac->dump, "\n";

  reread()

    You can use this function to reread the configuration file. For example,
    maybe you want your application to reread its config if it receives a
    "SIGHUP":

        $SIG{HUP} = \&handler;
        sub handler {
            my $sig = shift;
            if ($sig eq 'HUP') {
                # reread our config file on kill -HUP
                $config->reread;
            }
        }

    The above would handle a "SIGHUP" by rereading the config file.

  write([file])

    This writes the configuration out to disk. If no file is specified, then
    the one passed to "read()" is used. This method is currently under
    development and does not work. Patches welcome.

  autoloaded calls

    In addition to the above, you can also access values by calling a
    function named for the config command directly:

        my $server_name = $ac->cmd_config('ServerName');

    Is the same as:

        my $server_name = $ac->server_name;

    Underscores in the function name are taken as a place to put an
    uppercase letter. So these are all equivalent:

        my $doc_root = $ac->cmd_config('DocumentRoot');
        my $doc_root = $ac->DocumentRoot;   # looks silly
        my $doc_root = $ac->document_root;

    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.

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

    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.

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

    There are currently no tests written for this module. Sorry, short on
    time. Inventive (or even non-inventive!) tests welcome.

VERSION
    $Id: ConfigFile.pm,v 1.14 2001/09/06 23:57:54 nwiger Exp $

AUTHOR
    Copyright (c) 1999-2001, Nathan Wiger <nate@wiger.org>. All Rights
    Reserved.

    This module is free software; you may copy this under the terms of the
    GNU General Public License, or the Artistic License, copies of which
    should have accompanied your Perl kit.