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

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>User 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)".

    Note: see the documentation of Config::Context::ConfigScoped for the
    limitations of nesting with Config::Scoped files.

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.

    To read from a config file:

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

    To parse from a 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' },
            ],
        );

    To generate from an existing 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 example 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'
                    match_sections => [
                        {
                            name       => 'LocationMatch',
                            match_type => 'regex',
                        },
                    ],
                    file        => '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',
                        },
                    ],
                    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',
                    },
                ],
                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: the "XMLSimple" 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_sections 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'};

  files
    Returns a list of all the config files read, including any config files
    included in the main file.

  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.

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.

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.