NAME
    Config::Context - Add "<Location>" and "<LocationMatch>" style context
    matching to hierarchical configfile formats such as Config::General,
    XML::Simple and Config::Scoped

VERSION
    Version 0.05

SYNOPSIS
  Apache-style configs (via Config::General)
        use Config::Context;

        my $config_text = '

            <Location /users>
                title = "User Area"
            </Location>

            <LocationMatch \.*(jpg|gif|png)$>
                image_file = 1
            </LocationMatch>

        ';

        my $conf = Config::Context->new(
            string        => $config_text,
            driver        => 'ConfigGeneral',
            match_sections => [
                {
                    name          => 'Location',
                    match_type    => 'path',
                },
                {
                    name          => 'LocationMatch',
                    match_type    => 'regex',
                },
            ],
        );

        my %config = $conf->context('/users/~mary/index.html');

        use Data::Dumper;
        print Dumper(\%config);
        --------
        $VAR1 = {
            'title'         => 'User Area',
            'image_file'    => undef,
        };

        my %config = $conf->context('/users/~biff/images/flaming_logo.gif');
        print Dumper(\%config);
        --------
        $VAR1 = {
            'title'         => 'User Area',
            'image_file'    => 1,
        };

  XML configs (via XML::Simple)
        use Config::Context;

        my $config_text = '
            <opt>

              <Location name="/users">
                <title>Bork Area</title>
              </Location>

              <LocationMatch name="\.*(jpg|gif|png)$">
                <image_file>1</image_file>
              </LocationMatch>

            </opt>
        ';

        my $conf = Config::Context->new(
            string        => $config_text,
            driver        => 'XMLSimple',
            match_sections => [
                {
                    name          => 'Location',
                    match_type    => 'path',
                },
                {
                    name          => 'LocationMatch',
                    match_type    => 'regex',
                },
            ],
        );

        my %config = $conf->context('/users/~mary/index.html');

        use Data::Dumper;
        print Dumper(\%config);
        --------
        $VAR1 = {
            'title'         => 'User Area',
            'image_file'    => undef,
        };

        my %config = $conf->context('/users/~biff/images/flaming_logo.gif');
        print Dumper(\%config);
        --------
        $VAR1 = {
            'title'         => 'User Area',
            'image_file'    => 1,
        };

  Config::Scoped style configs
        use Config::Context;

        my $config_text = '
            Location /users {
                user_area = 1
            }

            LocationMatch '\.*(jpg|gif|png)$' {
                image_file = 1
            }
        ';

        my $conf = Config::Context->new(
            string        => $config_text,
            driver        => 'ConfigScoped',
            match_sections => [
                {
                    name          => 'Location',
                    match_type    => 'path',
                },
                {
                    name          => 'LocationMatch',
                    match_type    => 'regex',
                },
            ],
        );

        my %config = $conf->context('/users/~mary/index.html');

        use Data::Dumper;
        print Dumper(\%config);
        --------
        $VAR1 = {
            'title'         => 'User Area',
            'image_file'    => undef,
        };

        my %config = $conf->context('/users/~biff/images/flaming_logo.gif');
        print Dumper(\%config);
        --------
        $VAR1 = {
            'title'         => 'User Area',
            'image_file'    => 1,
        };

DESCRIPTION
  Introduction
    This module provides a consistent interface to many hierarchical
    configuration file formats such as "Config::General", "XML::Simple" and
    "Config::Scoped".

    It also provides Apache-style context matching. You can include blocks
    of configuration that match or not based on run-time parameters.

    For instance (using "Config::General" syntax):

        company_name      = ACME
        in_the_users_area = 0

        <Location /users>
            in_the_users_area = 1
        </Location>

    At runtime, if "Location" is within "/users", then the configuration
    within the "<Location>" block is merged into the top level. Otherwise,
    the block is ignored.

    So if "Location" is "/users/gary", the configuration is reduced to:

         {
             company_name      => 'ACME',
             in_the_users_area => 1,
         }

    But if "Location" is outside of the "/users" area (e.g.
    "/admin/documents.html"), the configuration is reduced to:

         {
             company_name      => 'ACME',
             in_the_users_area => 0,
         }

    The exact mechanics of how "Location" matches "/users" is extensively
    customizable. You can configure a particular block to match based on
    exact string matches, a substring, a path, or a regex.

    This kind of context-based matching was inspired by Apache's
    context-based configuration files.

    "Config::Context" works with Apache-style config files (via
    "Config::General"), XML documents (via "XML::Simple"), and
    "Config::Scoped" config files. You select the type config file with the
    "driver" option to "new".

    The examples in this document use "Config::General" (Apache-style)
    syntax. For details on other configuration formats, see the
    documentation for the appropriate driver.

    For a real world example of "Config::Context" in action, see
    "CGI::Application::Plugin::Config::Context", which determines
    configurations based on the URL of the request, the name of the Perl
    Module, and the virtual host handling the web request.

  The Default Section
    Config values that appear outside of any block act like defaults. Values
    in matching sections are merged with the default values. For instance:

        private_area = 0
        client_area  = 0

        <Location /admin>
            private_area = 1
        </Location>

        <Location /clients>
            client_area  = 1
        </Location>

        # Admin Area URL
        my %config = $conf->context('/admin/index.html');
        use Data::Dumper;
        print Dumper(\%config);
        $VAR1 = {
            'private_area' => 1,
            'client_area' => 0,
        };

        # Client Area URL
        my %config = $conf->context('/clients/index.html');
        print Dumper(\%config);
        $VAR1 = {
            'private_area' => 0,
            'client_area'  => 1,
        };

        # Neither Client nor Admin
        my %config = $conf->context('/public/index.html');
        print Dumper(\%config);
        $VAR1 = {
            'private_area' => 0,
            'client_area'  => 0,
        };

    When using the "Config::Context::ConfigScoped" driver, you must be
    careful with the use of the default section, since "Config::Scoped" does
    its own inheritance from the global scope into named sections. See the
    documentation for "Config::Context::ConfigScoped" for more information.

  Subsections are preserved
    When a block matches, and its configuration is merged into the top
    level, any subsections that it contained are preserved along with single
    values. For instance:

        # Default config
        private_area = 0
        client_area  = 0
        <page_settings>
            title       = "The Widget Emporium"
            logo        = logo.gif
            advanced_ui = 0
        </page_settings>

        # Admin config
        <Location /admin>
            private_area = 1
            <page_settings>
                title       = "The Widget Emporium - Admin Area"
                logo        = admin_logo.gif
                advanced_ui = 1
            </page_settings>
        </Location>

        # Client config
        <Location /clients>
            client_area  = 1
            <page_settings>
                title = "The Widget Emporium - Wholesalers"
                logo  = client_logo.gif
            </page_settings>
        </Location>

        # Admin Area URL
        my %config = $conf->context('/admin/index.html');

        use Data::Dumper;
        print Dumper(\%config);
        --------
        $VAR1 = {
            'page_settings' => {
                                'advanced_ui' => '1',
                                'title' => 'The Widget Emporium - Admin Area',
                                'logo' => 'admin_logo.gif'
                               },
            'private_area' => '1',
            'client_area' => '0'
        };

        # Client Area URL
        my %config = $conf->context('/clients/index.html');

        print Dumper(\%config);
        --------
        $VAR1 = {
            'page_settings' => {
                                'advanced_ui' => '0',
                                'title' => 'The Widget Emporium - Wholesalers',
                                'logo' => 'client_logo.gif'
                               },
            'client_area' => '1',
            'private_area' => '0'
        };

        # Neither Client nor Admin
        my %config = $conf->context('/public/index.html');

        print Dumper(\%config);
        --------
        $VAR1 = {

            'page_settings' => {
                                'advanced_ui' => '0',
                                'title' => 'The Widget Emporium',
                                'logo' => 'logo.gif'
                               },
            'client_area' => '0',
            'private_area' => '0'

        };

  Multiple Sections Matching
    Often more than one section will match the target string. When this
    happens, the matching sections are merged together using the
    "Hash::Merge" module. Typically this means that sections that are merged
    later override the values set in earlier sections. (But you can change
    this behaviour. See "Changing Hash::Merge behaviour" below.)

    The order of merging matters. The sections are merged first according to
    each section's "merge_priority" value (lowest values are merged first),
    and second by the length of the substring that matched (shortest matches
    are merged first). If you don't specify "merge_priority" for any
    section, they all default to a priority of 0 which means all sections
    are treated equally and matches are prioritized based soley on the
    length of the matching strings.

    When two sections have the same priority, the section with the shorter
    match is merged first. The idea is that longer matches are more
    specific, and should have precidence.

    The order of sections in the config file is ignored.

    For instance, if your config file looks like this:

        <Dir /foo/bar/baz>
            # section 1
        </Dir>

        <Path /foo>
            # section 2
        </Path>

        <Dir /foo/bar>
            # section 3
        </Dir>

        <Directory /foo/bar/baz/bam>
            # section 4
        </Directory>

    ...and you construct your $conf object like this:

        my $conf         = Config::Context->new(
            driver         => 'ConfigGeneral',
            match_sections => [
                { name    => 'Directory',  match_type => 'path' merge_priority => 1 },
                { name    => 'Dir',        match_type => 'path' merge_priority => 1 },
                { name    => 'Path',       match_type => 'path' merge_priority => 2 },
            ],
        );

    ...then the target string '/foo/bar/baz/bam/boom' would match all
    sections the order of 1, 3, 4, 2.

  Matching Context based on More than one String
    You have different sections match against different run time values. For
    instance, you could match some sections against the day of the week and
    other sections against weather:

        my $config = '

        weekend    = 0
        background = ''

        <Day Saturday>
            weekend = 1
        </Day>

        <Weekday Sunday>
            weekend = 1
        </Weekday>

        <Weather sunny>
            sky = blue
        </Weather>

        <Weather cloudy>
            sky = grey
        </Weather>
        ';

        my $conf = Config::Context->new(
            driver         => 'ConfigGeneral',
            match_sections => [
                { name => 'Day',      section_type => 'day',     match_type => 'path' },
                { name => 'Weekday',  section_type => 'day',     match_type => 'path' },
                { name => 'Weather',  section_type => 'weather', match_type => 'regex' },
            ],
        );

        my %config = $conf->context(day => 'Friday', weather => 'sunny');

        print Dumper(\%config);
        --------
        $VAR1 = {
            'weekend' => 0,
            'sky'     => 'blue',
        };

        my %config = $conf->context(day => 'Sunday', weather => 'partially cloudy');

        print Dumper(\%config);
        --------
        $VAR1 = {

            'weekend' => 1,
            'sky'     => 'grey',
        };

  Matching other path-like strings
    You can use "Config::Context" to match other hierarchical strings
    besides paths and URLs. For instance you could specify a
    "path_separator" of "::" and use the path feature to match against Perl
    modules:

        my $config_text = "

            is_core_module 0
            <Module NET::FTP>
                is_core_module 1
                author         Nathan Torkington
            </Module>

            <Module NET::FTPServer>
                author Richard Jone
            </Module>

        ";

        my $conf = Config::Context->new(
            driver         => 'ConfigGeneral',
            string         => $config_text,
            match_sections => [
                {
                    name           => 'Module',
                    path_separator => '::',
                    match_type     => 'path',
                },
            ],
        );

        my %config = $conf->context('Net::FTP');

        use Data::Dumper;
        print Dumper(\%config);
        --------
        $VAR1 = {
            'is_core_module' => 1,
            'author'         => 'Nathan Torkington',
        };

  Nested Matching
    You can have matching sections within matching sections:

        <Site bookshop>
            <Location /admin>
                admin_area = 1
            </Location>
        </Site>
        <Site recordshop>
            <Location /admin>
                admin_area = 1
            </Location>
        </Site>

    Enable this feature by setting "nesting_depth" parameter to "new", or by
    calling "$conf->nesting_depth($some_value)".

CONSTRUCTOR
  new(...)
    Creates and returns a new "Config::Context" object.

    The configuration can be read from a file, parsed from a string, or can
    be generated from a perl data struture.

        # Read from somefile.conf
        my $conf = Config::Context->new(
            file           => 'somefile.conf',
            driver         => 'ConfigGeneral',
            match_sections => [
               {  name  => 'Directory',  match_type => 'path' },
            ],
        );

        # Parse from string
        my $text = '
            in_the_users_area = 0
            <Directory /users>
                in_the_users_area = 1
            </Directory>
        ';

        my $conf = Config::Context->new(
            string         => $text,
            driver         => 'ConfigGeneral',
            match_sections => [
               {  name => 'Directory',    match_type => 'path' },
            ],
        );

        # Parse from perl data structure
        my %config = (
            'in_the_user_area' => '0'
            'Location' => {
                '/users' => {
                    'in_the_user_area' => '1'
                },
            },
        );

        my $conf = Config::Context->new(
            config         => \%config,
            driver         => 'ConfigGeneral',
            match_sections => [
               {  name => 'Directory',    match_type => 'path' },
            ],
        );

    The parameters to new are described below:

   file
    The config file.

   string
    A string containing the configuration to be parsed. If "string" is
    specified then "file" is ignored.

   config
    A Perl multi-level data structure containing the configuration. If
    "config" is specified, then both "file" and "string" are ignored

   driver
    Which "Config::Context" driver should parse the config. Currently
    supported drivers are:

        driver            module name
        ------            -----------
        ConfigGeneral     Config::Context::ConfigGeneral
        ConfigScoped      Config::Context::ConfigScoped
        XMLSimple         Config::Context::XMLSimple

   driver_options
    Options to pass directly on to the driver. This is a multi-level hash,
    where the top level keys are the driver names:

        my $conf = Config::Context->new(
            driver => 'ConfigScoped',
            driver_options => {
               ConfigGeneral => {
                   -AutoLaunder => 1,
               },
               ConfigScoped = > {
                   warnings => {
                       permissions  => 'off',
                   }
               },
            },
        );

    In this case the options under "ConfigScoped" will be passed to the
    "ConfigScoped" driver. (The options under "ConfigGeneral" will be
    ignored because "driver" is not set to 'ConfigGeneral'.)

   match_sections
    The "match_sections" parameter defines how "Config::Context" matches
    runtime values against configuration sections.

    "match_sections" takes a list of specification hashrefs. Each
    specification has the following fields:

    name
        The name of the section. For a name of 'Location', the section would
        look like:

            <Location /somepath>
            </Location>

    match_type
        Specifies the method by which the section strings should match the
        target string.

        The valid types of matches are 'exact', 'substring', 'regex',
        'path', and 'hierarchical'

        exact
            The config section string matches only if it is equal to the
            target string. For instance:

                # somefile.conf
                <Site mysite>
                    ...
                </Site>
                ...

                my $conf = Config::Context->new(
                    driver         => 'ConfigGeneral'
                    match_sections => [
                        {
                            name       => 'Site',
                            match_type => 'exact',
                        },
                    ],
                    file => 'somefile.conf',
                );

            In this case, only the exact string "mysite" would match the
            section.

        substring
            The config section string is tested to see if it is a substring
            of the target string. For instance:

                # somefile.conf
                <Location foo>
                    ...
                </Location>

                ...

                my $conf = Config::Context->new(
                    driver         => 'ConfigGeneral'
                    match_sections => [
                        {
                            name       => 'LocationMatch',
                            match_type => 'substring',
                        },
                    ],
                    file => 'somefile.conf',
                );

            In this case, the following target strings would all match:

                /foo
                big_foo.html
                /hotfood

        regex
            The config section string is treated as a regular expression
            against which the target string is matched. For instance:

                # somefile.conf
                <LocationMatch (\.jpg)|(\.gif)(\.png)$>
                    Image = 1
                </LocationMatch>

                ...

                my $conf = Config::Context->new(
                    driver         => 'ConfigGeneral'
                    -MatchSections => [
                        {
                            -Name      => 'LocationMatch',
                            -MatchType => 'regex',
                        },
                    ],
                    -ConfigFile => 'somefile.conf',
                );

                my %config = $conf->context('banner.jpg');

            The regex can contain any valid Perl regular expression. So to
            match case-insensitively you can use the "(?i:)" syntax:

                <LocationMatch (?i:/UsErS)>
                    UserDir = 1
                </LocationMatch>

            Also note that the regex is not tied to the beginning of the
            target string by default. So for regexes involving paths you
            will probably want to do so explicitly:

                <LocationMatch ^/users>
                    UserDir = 1
                </LocationMatch>

        path
            This method is useful for matching paths, URLs, Perl Modules and
            other hierarchical strings.

            The config section string is tested against the the target
            string. It matches if the following are all true:

            *   The section string is a substring of the target string

            *   The section string starts at the first character of the
                target string

            *   In the target string, the section string is followed
                immediately by "path_separator" or the end-of-string.

            For instance:

                # somefile.conf
                <Location /foo>
                </Location>

                ...

                my $conf = Config::Context->new(
                    driver         => 'ConfigGeneral'
                    match_sections => [
                        {
                            name       => 'LocationMatch',
                            match_Type => 'path',
                        },
                    ],
                    config_file => 'somefile.conf',
                );

            In this case, the following target strings would all match:

                /foo
                /foo/
                /foo/bar
                /foo/bar.txt

            But the following strings would not match:

                /foo.txt
                /food
                /food/bar.txt
                foo.txt

        hierarchical
            A synonym for 'path'.

    path_separator
        The path separator when matching hierarchical strings (paths, URLs,
        Module names, etc.). It defaults to '/'.

        This parameter is ignored unless the "match_type" is 'path' or
        'hierarchical'.

    section_type
        Allows you to match certain sections against certain run time
        values. For instance, you could match some sections against a given
        filesystem path and some sections against a Perl module name, using
        the same config file.

            # somefile.conf
            # section 1
            <FileMatch \.pm$>
                Perl_Module      = 1
                Core_Module      = 1
                Installed_Module = 0
            </FileMatch>

            # section 2
            <FileMatch ^/.*/lib/perl5/site_perl>
                Core_Module = 0
            </FileMatch>

            # section 3
            # Note the whitespace at the end of the section name, to prevent File from
            # being parsed as a stand-alone block by Config::General
            <File /usr/lib/perl5/ >
                Installed_Module = 1
            </File>

            # section 4
            <Module NET::FTP>
                FTP_Module = 1
            </Module>

            my $conf = Config::Context->new(
                driver         => 'ConfigGeneral'
                match_sections => [
                    {
                        name         => 'FileMatch',
                        match_type   => 'regex',
                        section_type => 'file',
                    },
                    {
                        name         => 'File',
                        match_type   => 'path',
                        section_type => 'file',
                    },
                    {
                        name         => 'Module',
                        match_type   => 'path',
                        separator    => '::',
                        section_type => 'module',
                    },
                ],
                config_file => 'somefile.conf',

                # need to turn off C-style comment parsing because of the
                # */ in the name of section 2
                driver_options => {
                    ConfigGeneral => {
                        -CComments => 0,
                    }
                },
            );

            my %config = $conf->context(
                file   => '/usr/lib/perl5/site_perl/5.6.1/NET/FTP/Common.pm',
                module => 'NET::FTP::Common',
            );

        This tests "/usr/lib/perl5/site_perl/5.6.1/NET/FTP/Common.pm"
        against sections 1, 2 and 3 (and merging them in the order of
        shortest to longest match, i.e. 1, 3, 2).

        Then it tests 'NET::FTP::Common' against section 4 (which also
        matches). The resulting configuration is:

            use Data::Dumper;
            print Dumper(\%config);
            --------
            $VAR1 = {
                'Perl_Module'      => 1,
                'Core_Module'      => 0,
                'FTP_Module'       => 1,
                'Installed_Module' => 1,
            };

        Another example:

            my %config = $conf->context(
                file   => '/var/www/cgi-lib/FTP/FTPServer.pm',
                module => 'NET::FTPServer',
            );

        This tests "/var/www/cgi-lib/NET/FTPServer.pm" against sections 1, 2
        and 3, and matches only against section 1. Then it matches
        'NET::FTPServer' against section 4 (which does not match). The
        result is:

            use Data::Dumper;
            print Dumper(\%config);
            --------
            $VAR1 = {
                'Perl_Module'      => 1,
                'Core_Module'      => 0,
                'FTP_Module'       => 0,
                'Installed_Module' => 0,
            };

        If a "section_type" is not specified in a "match_sections" block,
        then target strings of a named type will not match it.

        For another example, see "Matching Context based on More than one
        String", above.

        Matching by "section_type" is used in
        "CGI::Application::Plugin::Config::Context" to determine
        configurations based both on the URL of the request and of the name
        of the Perl Module and runmode handling the request.

    trim_section_names
        By default, section names are trimmed of leading and trailing
        whitespace before they are used to match. This is to allow for
        sections like:

            <Path /foo/bar/ >
            </Path>

        The whitespace at the end of the section name is necessary to
        prevent "Config::General"'s parser from thinking that the first tag
        is an empty "<Path />" block.

            <Path /foo/bar/>  # Config::General parses this as <Path />
            </Path>           # Config::General now considers this to be spurious

        If leading and trailing whitespace is significant to your matches,
        you can disable trimming by setting trim_section_names to 0 or
        "undef".

    merge_priority
        Sections with a lower "merge_priority" are merged before sections
        with a higher "merge_priority". If two or more sections have the
        same "merge_priority" they are weighted the same and they are merged
        according to the "best match" against the target string (i.e. the
        longest matching substring).

        See the description above under "Multiple Sections Matching".

   nesting_depth
    This option alows you to match against nested structures.

        # stories.conf
        <Story Three Little Pigs>
            antagonist = Big Bad Wolf
            moral      = obey the protestant work ethic
        </Story>

        <Location /aesop>
            <Story Wolf in Sheep's Clothing>
                antagonist = Big Bad Wolf
                moral      = appearances are deceptive
            </Story>
        </Location>

        <Story Little Red Riding Hood>
            antagonist = Big Bad Wolf

            <Location /perrault>
                moral      = never talk to strangers
            </Location>

            <Location /grimm>
                moral      = talk to strangers and then chop them up
            </Location>
        </Story>

        my $conf = Config::Context->new(
            match_sections => [
                {
                    name         => 'Story',
                    match_type   => 'substring',
                    section_type => 'story',
                },
                {
                    name         => 'Location',
                    match_type   => 'path',
                    section_type => 'path',
                },
            ],
            file          => 'stories.conf',
            nesting_depth => 2,
        );

        $config = $conf->context(
            story => 'Wolf in Sheep\'s Clothing',
            path  => '/aesop/wolf-in-sheeps-clothing',
        );

        use Data::Dumper;
        print Dumper($config);
        --------
        $VAR1 = {
            'antagonist' => 'Big Bad Wolf',
            'moral'      => 'appearances are deceptive'
        };

    You can also change the nesting depth by calling
    "$self->nesting_depth($depth)" after you have constructed the
    "Config::Context" object.

   lower_case_names
    Attempts to force all section and key names to lower case. If
    "lower_case_names" is true, then the following sections would all match
    'location':

        <Location /somepath>
        </Location>

        <loCATtion /somepath>
        </Location>

        <lOcAtion /somepath>
        </LOCATION>

    Note that the "XML::Simple" driver does not support this option.

   cache_config_files
    Whether or not to cache configuration files. Enabled, by default. This
    option is useful in a persistent environment such as "mod_perl". See
    "Config File Caching" under "ADVANCED USAGE", below.

   stat_config
    If config file caching is enabled, this option controls how often the
    config files are checked to see if they have changed. The default is 60
    seconds. This option is useful in a persistent environment such as
    "mod_perl". See "Config File Caching" under "ADVANCED USAGE", below.

METHODS
  raw()
    Returns the raw configuration data structure as read by the driver,
    before any context matching is performed.

  context( $target_string )
    Returns the merged configuration of all sections matching
    $target_string, according to the rules set up in "match_sections" in
    "new()". All "match_sections" are included, regardless of their
    "section_type".

  context( $type => $target_string )
    Returns the merged configuration matching $target_string, based only the
    "match_section"s that have a "section_type" of $type.

  context( $type1 => $target_string1, $type2 => $target_string2 )
    Returns the merged configuration of all sections of "section_type"
    $type1 matching $target_string1 and all sections of "section_type"
    $type2 matching $target_string2.

    The order of the parameters to "context()" is retained, so $type1
    sections will be matched first, followed by $type2 sections.

  context( )
    If you call "context" without parameters, it will return the same
    configuration that was generated by the last call to "context".

    If you call "context" in a scalar context, you will receive a reference
    to the config hash:

        my $config = $conf->context($target_string);
        my $value  = $config->{'somekey'};

    In a list context, "context" returns a hash:

        my %config = $conf->context($target_string);
        my $value  = $config{'somekey'};

  nesting_depth()
    Changes the default nesting depth, for matching nested structures. See
    the "nesting_depth" parameter to "new".

  clear_file_cache
    Clears the internal file cache. Class method.

        Config::Context->clear_file_cache;
        $conf->clear_file_cache;

ADVANCED USAGE
  Config File Caching
    By default each config file is read only once when the conf object is
    first initialized. Thereafter, on each init, the cached config is used.

    This means that in a persistent environment like mod_perl, the config
    file is parsed on the first request, but not on subsequent requests.

    If enough time has passed (sixty seconds by default) the config file is
    checked to see if it has changed. If it has changed, then the file is
    reread.

    If the driver supports it, any included files will be checked for
    changes along the main file. If you use "Config::General", you must use
    version 2.28 or greater for this feature to work correctly.

    To disable caching of config files pass a false value to the
    cache_config_files parameter to new, e.g:

        my $conf = Config::Context->new(
            cache_config_files => 0,
            # ... other options here ...
        );

    To change how often config files are checked for changes, change the
    value of the stat_config paramter to init, e.g.:

        my $conf = Config::Context->new(
            stat_config => 1, # check the config file every second
            # ... other options here ...
        );

    Internally the configuration cache is implemented by a hash, keyed by
    the absolute path of the configuration file. This means that if you have
    two applications running in the same process that both use the same
    configuration file, they will use the same cache.

    However, matching is performed on the config retrieved from the cache,
    so the two applications could each use different matching options
    creating different configurations from the same file.

  Changing Hash::Merge behaviour
    Matching sections are merged together using the "Hash::Merge" module. If
    you want to change how this module does its work you can call
    subroutines in the "Hash::Merge" package directly. For instance, to
    change the merge strategy so that earlier sections have precidence over
    later sections, you could call:

        # Note American Spelling :)
        Hash::Merge::set_behavior('RIGHT_PRECEDENT')

    You should do this before you call "context()".

    For more information on how to change merge options, see the
    "Hash::Merge" docs. =head1 AUTHOR

    Michael Graham, "<mag-perl@occamstoothbrush.com>"

BUGS
    Please report any bugs or feature requests to
    "bug-config-context@rt.cpan.org", or through the web interface at
    <http://rt.cpan.org>. I will be notified, and then you'll automatically
    be notified of progress on your bug as I make changes.

ACKNOWLEDGEMENTS
COPYRIGHT & LICENSE
    Copyright 2005 Michael Graham, All Rights Reserved.

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

