- COPYRIGHT & LICENSE
Algorithm::IncludeExclude - build and evaluate include/exclude lists
Algorithm::IncludeExclude lets you define a tree of include / exclude rules and then allows you to determine the best rule for a given path.
For example, to include everything, then exclude everything under
baz but then include everything under
foo baz, you could write:
my $ie = Algorithm::IncludeExclude->new; # setup rules $ie->include(); # default to include $ie->exclude('foo'); $ie->exclude('bar'); $ie->include(qw/foo baz/); # evaluate candidates $ie->evaluate(qw/foo bar/); # exclude (due to 'foo' rule) $ie->evaluate(qw/bar baz/); # exclude (due to 'bar' rule) $ie->evaluate(qw/quux foo bar/); # include (due to '' rule) $ie->evaluate(qw/foo baz quux/); # include (due to 'foo/baz' rule)
You can also match against regexes. Let's imagine you want to exclude everything in the
admin directory, as well as all files that end with a
Here's how to implement that:
my $ie = Algorithm::IncludeExclude->new; $ie->exclude('admin'); $ie->exclude(qr/[.]protected$/); $ie->evaluate(qw/admin let me in/); # exclude (due to 'admin' rule) $ie->evaluate(qw/a path.protected/); # exclude (due to regex) $ie->evaluate(qw/foo bar/); # undefined (no rule matches) $ie->include(qw/foo bar/); $ie->evaluate(qw/foo bar/); # now it's included
If you wanted to include files inside the
admin path ending in
.ok, you could just add this rule:
$ie->include('admin', qr/[.]ok$/); $ie->evaluate(qw/admin super public records.ok/); # included
The most specific match always wins -- if there's not an exact match, the nearest match is chosen instead.
Regexes can only appear as the last element in a rule:
$ie->include(qr/foo/, qr/bar/); $ie->exclude(qr/foo/, qr/bar/);
If regexes were allowed anywhere, things could get very confusing, very quickly.
Regexes are matched against any remaining path elements when they are first encountered. In the following example:
$ie->include('foo', qr/bar/); $ie->evaluate('foo', 'baz', 'quux', 'bar'); # include
The match works like this. First, 'foo' (from the include rule) and 'foo' (from the path being evaluated) are compared. Since there's a match, the next element in the path is examined against
foo's subtree. The only remaining item in the rule tree is a regex, so the regex is compared to the rest of the path being evaluated, joined by the
joinargument to new (see "METHODS/new"); namely:
Since the regular expression matches this string, the include rule is matched.
Regex rules are checked before non-regex rules. For example:
$ie->exclude('foo', 'bar'); $ie->include(qr/bar/); $ie->evaluate('foo', 'bar'); # include, due to regex
If two or more regular expressions at the same level match a path, the result is undefined:
$ie->include(qr/foo/); $ie->exclude(qr/bar/); $ie->evaluate('foobar'); # undef is returned
Create a new instance. Accepts an optional hashref of arguments. The arguments may be:
String to join remaining path elements with when matching against a regex. Defaults to
/, which is good for matching against URLs or filesystem paths.
Add an include path to the rule tree.
@path may end with a regex.
Add an exclude path to the rule tree.
@path may end with a regex.
@path should be included (true) or excluded (false). If the include/exclude status cannot be determined (no rules match, more than one regex matches),
undef is returned.
<jrockway at cpan.org>
Please report any bugs or feature requests to
bug-algorithm-includeexclude at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Algorithm-IncludeExclude. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
You can find documentation for this module with the perldoc command.
You can also look for information at:
AnnoCPAN: Annotated CPAN documentation
RT: CPAN's request tracker
Copyright 2007 Jonathan Rockway, all rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.