1File::Find::Rule(3)   User Contributed Perl Documentation  File::Find::Rule(3)
2
3
4

NAME

6       File::Find::Rule - Alternative interface to File::Find
7

SYNOPSIS

9         use File::Find::Rule;
10         # find all the subdirectories of a given directory
11         my @subdirs = File::Find::Rule->directory->in( $directory );
12
13         # find all the .pm files in @INC
14         my @files = File::Find::Rule->file()
15                                     ->name( '*.pm' )
16                                     ->in( @INC );
17
18         # as above, but without method chaining
19         my $rule =  File::Find::Rule->new;
20         $rule->file;
21         $rule->name( '*.pm' );
22         my @files = $rule->in( @INC );
23

DESCRIPTION

25       File::Find::Rule is a friendlier interface to File::Find.  It allows
26       you to build rules which specify the desired files and directories.
27

METHODS

29       "new"
30           A constructor.  You need not invoke "new" manually unless you wish
31           to, as each of the rule-making methods will auto-create a suitable
32           object if called as class methods.
33
34   Matching Rules
35       "name( @patterns )"
36           Specifies names that should match.  May be globs or regular
37           expressions.
38
39            $set->name( '*.mp3', '*.ogg' ); # mp3s or oggs
40            $set->name( qr/\.(mp3|ogg)$/ ); # the same as a regex
41            $set->name( 'foo.bar' );        # just things named foo.bar
42
43       -X tests
44           Synonyms are provided for each of the -X tests. See "-X" in
45           perlfunc for details.  None of these methods take arguments.
46
47             Test | Method               Test |  Method
48            ------|-------------        ------|----------------
49              -r  |  readable             -R  |  r_readable
50              -w  |  writeable            -W  |  r_writeable
51              -w  |  writable             -W  |  r_writable
52              -x  |  executable           -X  |  r_executable
53              -o  |  owned                -O  |  r_owned
54                  |                           |
55              -e  |  exists               -f  |  file
56              -z  |  empty                -d  |  directory
57              -s  |  nonempty             -l  |  symlink
58                  |                       -p  |  fifo
59              -u  |  setuid               -S  |  socket
60              -g  |  setgid               -b  |  block
61              -k  |  sticky               -c  |  character
62                  |                       -t  |  tty
63              -M  |  modified                 |
64              -A  |  accessed             -T  |  ascii
65              -C  |  changed              -B  |  binary
66
67           Though some tests are fairly meaningless as binary flags
68           ("modified", "accessed", "changed"), they have been included for
69           completeness.
70
71            # find nonempty files
72            $rule->file,
73                 ->nonempty;
74
75       stat tests
76           The following "stat" based methods are provided: "dev", "ino",
77           "mode", "nlink", "uid", "gid", "rdev", "size", "atime", "mtime",
78           "ctime", "blksize", and "blocks".  See "stat" in perlfunc for
79           details.
80
81           Each of these can take a number of targets, which will follow
82           Number::Compare semantics.
83
84            $rule->size( 7 );         # exactly 7
85            $rule->size( ">7Ki" );    # larger than 7 * 1024 * 1024 bytes
86            $rule->size( ">=7" )
87                 ->size( "<=90" );    # between 7 and 90, inclusive
88            $rule->size( 7, 9, 42 );  # 7, 9 or 42
89
90       "any( @rules )"
91       "or( @rules )"
92           Allows shortcircuiting boolean evaluation as an alternative to the
93           default and-like nature of combined rules.  "any" and "or" are
94           interchangeable.
95
96            # find avis, movs, things over 200M and empty files
97            $rule->any( File::Find::Rule->name( '*.avi', '*.mov' ),
98                        File::Find::Rule->size( '>200M' ),
99                        File::Find::Rule->file->empty,
100                      );
101
102       "none( @rules )"
103       "not( @rules )"
104           Negates a rule.  (The inverse of "any".)  "none" and "not" are
105           interchangeable.
106
107             # files that aren't 8.3 safe
108             $rule->file
109                  ->not( $rule->new->name( qr/^[^.]{1,8}(\.[^.]{0,3})?$/ ) );
110
111       "prune"
112           Traverse no further.  This rule always matches.
113
114       "discard"
115           Don't keep this file.  This rule always matches.
116
117       "exec( \&subroutine( $shortname, $path, $fullname ) )"
118           Allows user-defined rules.  Your subroutine will be invoked with $_
119           set to the current short name, and with parameters of the name, the
120           path you're in, and the full relative filename.
121
122           Return a true value if your rule matched.
123
124            # get things with long names
125            $rules->exec( sub { length > 20 } );
126
127       "grep( @specifiers )"
128           Opens a file and tests it each line at a time.
129
130           For each line it evaluates each of the specifiers, stopping at the
131           first successful match.  A specifier may be a regular expression or
132           a subroutine.  The subroutine will be invoked with the same
133           parameters as an ->exec subroutine.
134
135           It is possible to provide a set of negative specifiers by enclosing
136           them in anonymous arrays.  Should a negative specifier match the
137           iteration is aborted and the clause is failed.  For example:
138
139            $rule->grep( qr/^#!.*\bperl/, [ sub { 1 } ] );
140
141           Is a passing clause if the first line of a file looks like a perl
142           shebang line.
143
144       "maxdepth( $level )"
145           Descend at most $level (a non-negative integer) levels of
146           directories below the starting point.
147
148           May be invoked many times per rule, but only the most recent value
149           is used.
150
151       "mindepth( $level )"
152           Do not apply any tests at levels less than $level (a non-negative
153           integer).
154
155       "extras( \%extras )"
156           Specifies extra values to pass through to "File::File::find" as
157           part of the options hash.
158
159           For example this allows you to specify following of symlinks like
160           so:
161
162            my $rule = File::Find::Rule->extras({ follow => 1 });
163
164           May be invoked many times per rule, but only the most recent value
165           is used.
166
167       "relative"
168           Trim the leading portion of any path found
169
170       "canonpath"
171           Normalize paths found using "File::Spec-"canonpath>. This will
172           return paths with a file-seperator that is native to your OS (as
173           determined by File::Spec),
174            instead of the default "/".
175
176           For example, this will return "tmp/foobar" on Unix-ish OSes and
177           "tmp\foobar" on Win32.
178
179       "not_*"
180           Negated version of the rule.  An effective shortand related to ! in
181           the procedural interface.
182
183            $foo->not_name('*.pl');
184
185            $foo->not( $foo->new->name('*.pl' ) );
186
187   Query Methods
188       "in( @directories )"
189           Evaluates the rule, returns a list of paths to matching files and
190           directories.
191
192       "start( @directories )"
193           Starts a find across the specified directories.  Matching items may
194           then be queried using "match".  This allows you to use a rule as an
195           iterator.
196
197            my $rule = File::Find::Rule->file->name("*.jpeg")->start( "/web" );
198            while ( defined ( my $image = $rule->match ) ) {
199                ...
200            }
201
202       "match"
203           Returns the next file which matches, false if there are no more.
204
205   Extensions
206       Extension modules are available from CPAN in the File::Find::Rule
207       namespace.  In order to use these extensions either use them directly:
208
209        use File::Find::Rule::ImageSize;
210        use File::Find::Rule::MMagic;
211
212        # now your rules can use the clauses supplied by the ImageSize and
213        # MMagic extension
214
215       or, specify that File::Find::Rule should load them for you:
216
217        use File::Find::Rule qw( :ImageSize :MMagic );
218
219       For notes on implementing your own extensions, consult
220       File::Find::Rule::Extending
221
222   Further examples
223       Finding perl scripts
224            my $finder = File::Find::Rule->or
225             (
226              File::Find::Rule->name( '*.pl' ),
227              File::Find::Rule->exec(
228                                     sub {
229                                         if (open my $fh, $_) {
230                                             my $shebang = <$fh>;
231                                             close $fh;
232                                             return $shebang =~ /^#!.*\bperl/;
233                                         }
234                                         return 0;
235                                     } ),
236             );
237
238           Based upon this message
239           http://use.perl.org/comments.pl?sid=7052&cid=10842
240
241       ignore CVS directories
242            my $rule = File::Find::Rule->new;
243            $rule->or($rule->new
244                           ->directory
245                           ->name('CVS')
246                           ->prune
247                           ->discard,
248                      $rule->new);
249
250           Note here the use of a null rule.  Null rules match anything they
251           see, so the effect is to match (and discard) directories called
252           'CVS' or to match anything.
253

TWO FOR THE PRICE OF ONE

255       File::Find::Rule also gives you a procedural interface.  This is
256       documented in File::Find::Rule::Procedural
257

EXPORTS

259       "find", "rule"
260

TAINT MODE INTERACTION

262       As of 0.32 File::Find::Rule doesn't capture the current working
263       directory in a taint-unsafe manner.  File::Find itself still does
264       operations that the taint system will flag as insecure but you can use
265       the "extras" feature to ask File::Find to internally "untaint" file
266       paths with a regex like so:
267
268           my $rule = File::Find::Rule->extras({ untaint => 1 });
269
270       Please consult File::Find's documentation for "untaint",
271       "untaint_pattern", and "untaint_skip" for more information.
272

BUGS

274       The code makes use of the "our" keyword and as such requires perl
275       version 5.6.0 or newer.
276
277       Currently it isn't possible to remove a clause from a rule object.  If
278       this becomes a significant issue it will be addressed.
279

AUTHOR

281       Richard Clamp <richardc@unixbeard.net> with input gained from this
282       use.perl discussion: http://use.perl.org/~richardc/journal/6467
283
284       Additional proofreading and input provided by Kake, Greg McCarroll, and
285       Andy Lester andy@petdance.com.
286
288       Copyright (C) 2002, 2003, 2004, 2006, 2009, 2011 Richard Clamp.  All
289       Rights Reserved.
290
291       This module is free software; you can redistribute it and/or modify it
292       under the same terms as Perl itself.
293

SEE ALSO

295       File::Find, Text::Glob, Number::Compare, find(1)
296
297       If you want to know about the procedural interface, see
298       File::Find::Rule::Procedural, and if you have an idea for a neat
299       extension File::Find::Rule::Extending
300
301
302
303perl v5.36.0                      2022-07-22               File::Find::Rule(3)
Impressum