Algorithm::IncludeExclude.3pm

Langue: en

Version: 2007-02-08 (fedora - 01/12/10)

Section: 3 (Bibliothèques de fonctions)

NAME

Algorithm::IncludeExclude - build and evaluate include/exclude lists

VERSION

Version 0.01

SYNOPSIS

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 "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>

ACKNOWLEDGEMENTS

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.