NAME Config::Context - Add "" and "" style context matching to hierarchical configfile formats such as Config::General, XML::Simple and Config::Scoped VERSION Version 0.09 SYNOPSIS Apache-style configs (via Config::General) use Config::Context; my $config_text = ' title = "User Area" image_file = 1 '; 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 = ' User Area 1 '; 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 in_the_users_area = 1 At runtime, if "Location" is within "/users", then the configuration within the "" 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 private_area = 1 client_area = 1 # 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 title = "The Widget Emporium" logo = logo.gif advanced_ui = 0 # Admin config private_area = 1 title = "The Widget Emporium - Admin Area" logo = admin_logo.gif advanced_ui = 1 # Client config client_area = 1 title = "The Widget Emporium - Wholesalers" logo = client_logo.gif # 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: # section 1 # section 2 # section 3 # section 4 ...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 = '' weekend = 1 weekend = 1 sky = blue sky = grey '; 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 is_core_module 1 author Nathan Torkington author Richard Jone "; 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: admin_area = 1 admin_area = 1 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 in_the_users_area = 1 '; 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: 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 ... ... 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 ... ... 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 Image = 1 ... 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: UserDir = 1 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: UserDir = 1 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 ... 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 Perl_Module = 1 Core_Module = 1 Installed_Module = 0 # section 2 Core_Module = 0 # 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 Installed_Module = 1 # section 4 FTP_Module = 1 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: 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 "" block. # Config::General parses this as # 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 antagonist = Big Bad Wolf moral = obey the protestant work ethic antagonist = Big Bad Wolf moral = appearances are deceptive antagonist = Big Bad Wolf moral = never talk to strangers moral = talk to strangers and then chop them up 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': 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, "" BUGS Please report any bugs or feature requests to "bug-config-context@rt.cpan.org", or through the web interface at . 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.