GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  ALGORITHM::INCLUDEEXCLUDE (3)

.ds Aq ’

NAME

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

CONTENTS

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

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

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

o 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



o 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>. 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:
o AnnoCPAN: Annotated CPAN documentation

<http://annocpan.org/dist/Algorithm-IncludeExclude>

o CPAN Ratings

<http://cpanratings.perl.org/d/Algorithm-IncludeExclude>

o RT: CPAN’s request tracker

<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Algorithm-IncludeExclude>

o Search CPAN

<http://search.cpan.org/dist/Algorithm-IncludeExclude>

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.

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 ALGORITHM::INCLUDEEXCLUDE (3) 2007-02-08

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.