Matching things other than paths

The Match feature is general enough that you can use it to match other things besides paths and URLs. For instance you could specify a -PathSeparator of :: and use the feature to match against Perl modules:

Merging Multiple Matching Sections

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

This parameter is ignored unless the -MatchType is 'path' or 'hierarchical'.

-SectionType

Allows you to only process certain sections for certain types of strings. 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.

If a -SectionType is not specified in a -MatchSections block, then target strings of a named type will not match it.

Matching by -SectionType is used in CGI::Application::Plugin::Config::General to generate configurations based both on the URL of the request and of the name of the Perl Module and runmode handling the request.

-TrimSectionNames

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 -TrimSectionNames to 0 or undef.

-MergePriority

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

METHODS

Config::General::Match is a subclass of Config::General, so you can use of Config::General's methods. In particular, you can use getall() to get the entire configuration without concern for any section matching.

getall_matching( $target_string )

Returns the merged configuration of all sections matching $target_string, according to the rules set up in the -MatchSections in new(). All -MatchSections are included, regardless of their -SectionType.

getall_matching( $type => $target_string )

Returns the merged configuration matching $target_string, based only the -MatchSections that have a -SectionType of $type.

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:

Please report any bugs or feature requests to bug-config-general-match@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.

SEE ALSO

Config::General
CGI::Application::Plugin::Config::General
Hash::Merge

ACKNOWLEDGEMENTS

This module would not be possible without Thomas Linden's excellent Config::General module.

COPYRIGHT & LICENSE

Copyright 2004-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.

Module Install Instructions

To install Config::General::Match, simply copy and paste either of the commands in to your terminal