Quick Navigator

Search Site

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

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  ALGORITHM::INCLUDEEXCLUDE (3)

.ds Aq ’


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


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:


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


Please report any bugs or feature requests to bug-algorithm-includeexclude at, or through the web interface at <>. 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:
o AnnoCPAN: Annotated CPAN documentation


o CPAN Ratings


o RT: CPAN’s request tracker


o Search CPAN




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.