1Algorithm::IncludeExcluUdsee(r3)Contributed Perl DocumenAtlagtoirointhm::IncludeExclude(3)
2
6 Algorithm::IncludeExclude - build and evaluate include/exclude lists
7
9 Version 0.01
10
12 Algorithm::IncludeExclude lets you define a tree of include / exclude
13 rules and then allows you to determine the best rule for a given path.
14 For example, to include everything, then exclude everything under "bar"
16 or "baz" but then include everything under "foo baz", you could write:
17 my $ie = Algorithm::IncludeExclude->new;
19 # setup rules
21 $ie->include(); # default to include
22 $ie->exclude('foo');
23 $ie->exclude('bar');
24 $ie->include(qw/foo baz/);
25 # evaluate candidates
27 $ie->evaluate(qw/foo bar/); # exclude (due to 'foo' rule)
28 $ie->evaluate(qw/bar baz/); # exclude (due to 'bar' rule)
29 $ie->evaluate(qw/quux foo bar/); # include (due to '' rule)
30 $ie->evaluate(qw/foo baz quux/); # include (due to 'foo/baz' rule)
31 You can also match against regexes. Let's imagine you want to exclude
33 everything in the "admin" directory, as well as all files that end with
34 a ".protected" extension.
35 Here's how to implement that:
37 my $ie = Algorithm::IncludeExclude->new;
39 $ie->exclude('admin');
40 $ie->exclude(qr/[.]protected$/);
41 $ie->evaluate(qw/admin let me in/); # exclude (due to 'admin' rule)
43 $ie->evaluate(qw/a path.protected/); # exclude (due to regex)
44 $ie->evaluate(qw/foo bar/); # undefined (no rule matches)
45 $ie->include(qw/foo bar/);
47 $ie->evaluate(qw/foo bar/); # now it's included
48 If you wanted to include files inside the "admin" path ending in ".ok",
50 you could just add this rule:
51 $ie->include('admin', qr/[.]ok$/);
53 $ie->evaluate(qw/admin super public records.ok/); # included
54 The most specific match always wins -- if there's not an exact match,
56 the nearest match is chosen instead.
57
59 · Regexes can only appear as the last element in a rule:
60 $ie->include(qr/foo/, qr/bar/);
62 $ie->exclude(qr/foo/, qr/bar/);
63 If regexes were allowed anywhere, things could get very confusing,
65 very quickly.
66 · Regexes are matched against any remaining path elements when they
68 are first encountered. In the following example:
69 $ie->include('foo', qr/bar/);
71 $ie->evaluate('foo', 'baz', 'quux', 'bar'); # include
72 The match works like this. First, 'foo' (from the include rule)
74 and 'foo' (from the path being evaluated) are compared. Since
75 there's a match, the next element in the path is examined against
76 "foo"'s subtree. The only remaining item in the rule tree is a
77 regex, so the regex is compared to the rest of the path being
78 evaluated, joined by the "join" argument to new (see
79 "METHODS/new"); namely:
80 baz/quux/bar
82 Since the regular expression matches this string, the include rule
84 is matched.
85 · Regex rules are checked before non-regex rules. For example:
87 $ie->exclude('foo', 'bar');
89 $ie->include(qr/bar/);
90 $ie->evaluate('foo', 'bar'); # include, due to regex
92 · If two or more regular expressions at the same level match a path,
94 the result is undefined:
95 $ie->include(qr/foo/);
97 $ie->exclude(qr/bar/);
98 $ie->evaluate('foobar'); # undef is returned
100
102 new
103 Create a new instance. Accepts an optional hashref of arguments. The
104 arguments may be:
105 join
107 String to join remaining path elements with when matching against a
108 regex. Defaults to "/", which is good for matching against URLs or
109 filesystem paths.
110 include(@path)
112 Add an include path to the rule tree. @path may end with a regex.
113 exclude(@path)
115 Add an exclude path to the rule tree. @path may end with a regex.
116 evaluate(@path)
118 Evaluate whether @path should be included (true) or excluded (false).
119 If the include/exclude status cannot be determined (no rules match,
120 more than one regex matches), "undef" is returned.
121
123 Jonathan Rockway, "<jrockway at cpan.org>"
124
126 Please report any bugs or feature requests to
127 "bug-algorithm-includeexclude at rt.cpan.org", or through the web
128 interface at
129 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Algorithm-IncludeExclude>.
130 I will be notified, and then you'll automatically be notified of
131 progress on your bug as I make changes.
132
134 You can find documentation for this module with the perldoc command.
135 perldoc Algorithm::IncludeExclude
137 You can also look for information at:
139 · AnnoCPAN: Annotated CPAN documentation
141 <http://annocpan.org/dist/Algorithm-IncludeExclude>
143 · CPAN Ratings
145 <http://cpanratings.perl.org/d/Algorithm-IncludeExclude>
147 · RT: CPAN's request tracker
149 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Algorithm-IncludeExclude>
151 · Search CPAN
153 <http://search.cpan.org/dist/Algorithm-IncludeExclude>
155
158 Copyright 2007 Jonathan Rockway, all rights reserved.
159 This program is free software; you can redistribute it and/or modify it
161 under the same terms as Perl itself.
162perl v5.32.0 2020-07-28 Algorithm::IncludeExclude(3)