Algorit...eExclude(3)

📦
version 0.01 · 2 versions
, in fedora 43

✨ Algorithm::IncludeExclude 💅

okay bestie, you found it — this is the manual page for Algorithm::IncludeExclude, straight out of section 3 of the manual (User Contributed Perl Documentation, no big deal 💖). If you've ever needed to build a tree of include/exclude rules and then ask "hey, does this path get in or not?", this is your girl. Periodt.

🌸 NAME 🌸

Algorithm::IncludeExclude — build and evaluate include/exclude lists. That's it, that's the whole vibe. 🎀

💖 VERSION 💖

Version 0.01. Yes, baby version, but she's iconic. 👑

✨ SYNOPSIS ✨

So Algorithm::IncludeExclude lets you define a tree of include / exclude rules, and then it lets you figure out the best rule for any given path. Literally the whole personality.

Say you wanna include everything, then exclude everything under "bar" or "baz", but then include everything under "foo baz". Bestie, you'd 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)

The way that works is just chef's kiss. 🧚

You can also match against regexes. Imagine you want to exclude everything in the "admin" directory, AND all files that end with a .protected extension. The audacity of those files, honestly.

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

Note the # undefined (no rule matches) moment — she's mysterious, she's giving nothing. 💀

Now, if you wanted to include files inside the "admin" path that end in .ok, you could just add this rule:

$ie->include('admin', qr/[.]ok$/);
$ie->evaluate(qw/admin super public records.ok/); # included

And the rule of rules: the most specific match always wins. If there's not an exact match, the nearest match gets chosen instead. No cap. 🫶

🔥 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 else, things could get very confusing, very quickly. Like, chaos. We don't do that here. 🙈

  • 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, bestie, follow along: 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. Slay. 💅

  • 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. Not "first one wins", not "last one wins" — undefined. Genuinely no answer. Watch out:
$ie->include(qr/foo/);
$ie->exclude(qr/bar/);

$ie->evaluate('foobar'); # undef is returned

She said "I'm not choosing." 😭

💜 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. Very practical, very demure. ✨

🌟 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>" — the icon who built this. 👑

🦋 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. Communication, we love to see it. 🫶

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

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

⭐ ACKNOWLEDGEMENTS ⭐

(no content here, bestie — the section exists but it's empty, and we respect her privacy 💅)

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.

and that's the whole page, no notes 💖✨🌸🦋

This gorgeous thing was documented by perl v5.42.0 on 2025-07-25, and it's filed under Algorit...eExclude(3). go forth and evaluate some paths, bestie 🎀💅🔥

📦 where this page comes from