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
Algorithm::IncludeExclude(3) User Contributed Perl Documentation Algorithm::IncludeExclude(3)

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

Version 0.01

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.

  • 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
        

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.

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.

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.

Jonathan Rockway, "<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.

    perldoc Algorithm::IncludeExclude

You can also look for information at:

  • AnnoCPAN: Annotated CPAN documentation

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

  • CPAN Ratings

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

  • RT: CPAN's request tracker

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

  • Search CPAN

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

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.

2007-02-08 perl v5.32.1

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

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