Jonathan Rockway > Algorithm-IncludeExclude > Algorithm::IncludeExclude

Download:
Algorithm-IncludeExclude-0.01.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.01   Source  

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 ^

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

ACKNOWLEDGEMENTS ^

COPYRIGHT & 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.

syntax highlighting: