Algorithm::IncludeExclUser3Contributed Perl DocumeAlgorithm::IncludeExclude(3)NAMEAlgorithm::IncludeExclude - build and evaluate include/exclude lists
VERSION
Version 0.01
SYNOPSISAlgorithm::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 "bar"
or "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 ".protected" extension.
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.
NOTES
· 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 "join" argument to new (see
"METHODS/new"); namely:
baz/quux/bar
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
METHODS
new
Create a new instance. Accepts an optional hashref of arguments. The
arguments may be:
join
String to join remaining path elements with when matching against a
regex. Defaults to "/", which is good for matching against URLs or
filesystem paths.
include(@path)
Add an include path to the rule tree. @path may end with a regex.
exclude(@path)
Add an exclude path to the rule tree. @path may end with a regex.
evaluate(@path)
Evaluate whether @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.
AUTHOR
Jonathan Rockway, "<jrockway at cpan.org>"
BUGS
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
<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.
SUPPORT
You can find documentation for this module with the perldoc command.
perldoc Algorithm::IncludeExclude
You can also look for information at:
· AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Algorithm-IncludeExclude
<http://annocpan.org/dist/Algorithm-IncludeExclude>
· CPAN Ratings
http://cpanratings.perl.org/d/Algorithm-IncludeExclude
<http://cpanratings.perl.org/d/Algorithm-IncludeExclude>
· RT: CPAN's request tracker
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Algorithm-IncludeExclude
<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Algorithm-IncludeExclude>
· Search CPAN
http://search.cpan.org/dist/Algorithm-IncludeExclude
<http://search.cpan.org/dist/Algorithm-IncludeExclude>
ACKNOWLEDGEMENTSCOPYRIGHT & LICENSE
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.
perl v5.14.1 2007-02-08 Algorithm::IncludeExclude(3)
