1Algorithm::IncludeExcluUdsee(r3)Contributed Perl DocumenAtlagtoirointhm::IncludeExclude(3)
2
3
4

NAME

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

VERSION

9       Version 0.01
10

SYNOPSIS

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
15       For example, to include everything, then exclude everything under "bar"
16       or "baz" but then include everything under "foo baz", you could write:
17
18          my $ie = Algorithm::IncludeExclude->new;
19
20          # setup rules
21          $ie->include();                      # default to include
22          $ie->exclude('foo');
23          $ie->exclude('bar');
24          $ie->include(qw/foo baz/);
25
26          # 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
32       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
36       Here's how to implement that:
37
38          my $ie = Algorithm::IncludeExclude->new;
39          $ie->exclude('admin');
40          $ie->exclude(qr/[.]protected$/);
41
42          $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
46          $ie->include(qw/foo bar/);
47          $ie->evaluate(qw/foo bar/);          # now it's included
48
49       If you wanted to include files inside the "admin" path ending in ".ok",
50       you could just add this rule:
51
52          $ie->include('admin', qr/[.]ok$/);
53          $ie->evaluate(qw/admin super public records.ok/); # included
54
55       The most specific match always wins -- if there's not an exact match,
56       the nearest match is chosen instead.
57

NOTES

59       •   Regexes can only appear as the last element in a rule:
60
61              $ie->include(qr/foo/, qr/bar/);
62              $ie->exclude(qr/foo/, qr/bar/);
63
64           If regexes were allowed anywhere, things could get very confusing,
65           very quickly.
66
67       •   Regexes are matched against any remaining path elements when they
68           are first encountered.  In the following example:
69
70              $ie->include('foo', qr/bar/);
71              $ie->evaluate('foo', 'baz', 'quux', 'bar'); # include
72
73           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
81              baz/quux/bar
82
83           Since the regular expression matches this string, the include rule
84           is matched.
85
86       •   Regex rules are checked before non-regex rules.  For example:
87
88             $ie->exclude('foo', 'bar');
89             $ie->include(qr/bar/);
90
91             $ie->evaluate('foo', 'bar'); # include, due to regex
92
93       •   If two or more regular expressions at the same level match a path,
94           the result is undefined:
95
96             $ie->include(qr/foo/);
97             $ie->exclude(qr/bar/);
98
99             $ie->evaluate('foobar'); # undef is returned
100

METHODS

102   new
103       Create a new instance.  Accepts an optional hashref of arguments.  The
104       arguments may be:
105
106       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
111   include(@path)
112       Add an include path to the rule tree.  @path may end with a regex.
113
114   exclude(@path)
115       Add an exclude path to the rule tree.  @path may end with a regex.
116
117   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

AUTHOR

123       Jonathan Rockway, "<jrockway at cpan.org>"
124

BUGS

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

SUPPORT

134       You can find documentation for this module with the perldoc command.
135
136           perldoc Algorithm::IncludeExclude
137
138       You can also look for information at:
139
140       •   AnnoCPAN: Annotated CPAN documentation
141
142           <http://annocpan.org/dist/Algorithm-IncludeExclude>
143
144       •   CPAN Ratings
145
146           <http://cpanratings.perl.org/d/Algorithm-IncludeExclude>
147
148       •   RT: CPAN's request tracker
149
150           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Algorithm-IncludeExclude>
151
152       •   Search CPAN
153
154           <http://search.cpan.org/dist/Algorithm-IncludeExclude>
155

ACKNOWLEDGEMENTS

158       Copyright 2007 Jonathan Rockway, all rights reserved.
159
160       This program is free software; you can redistribute it and/or modify it
161       under the same terms as Perl itself.
162
163
164
165perl v5.32.1                      2021-01-26      Algorithm::IncludeExclude(3)



        

    


            
        

        

            Impressum