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       "not_*"
171           Negated version of the rule.  An effective shortand related to ! in
172           the procedural interface.
173
174            $foo->not_name('*.pl');
175
176            $foo->not( $foo->new->name('*.pl' ) );
177
178   Query Methods
179       "in( @directories )"
180           Evaluates the rule, returns a list of paths to matching files and
181           directories.
182
183       "start( @directories )"
184           Starts a find across the specified directories.  Matching items may
185           then be queried using "match".  This allows you to use a rule as an
186           iterator.
187
188            my $rule = File::Find::Rule->file->name("*.jpeg")->start( "/web" );
189            while ( defined ( my $image = $rule->match ) ) {
190                ...
191            }
192
193       "match"
194           Returns the next file which matches, false if there are no more.
195
196   Extensions
197       Extension modules are available from CPAN in the File::Find::Rule
198       namespace.  In order to use these extensions either use them directly:
199
200        use File::Find::Rule::ImageSize;
201        use File::Find::Rule::MMagic;
202
203        # now your rules can use the clauses supplied by the ImageSize and
204        # MMagic extension
205
206       or, specify that File::Find::Rule should load them for you:
207
208        use File::Find::Rule qw( :ImageSize :MMagic );
209
210       For notes on implementing your own extensions, consult
211       File::Find::Rule::Extending
212
213   Further examples
214       Finding perl scripts
215            my $finder = File::Find::Rule->or
216             (
217              File::Find::Rule->name( '*.pl' ),
218              File::Find::Rule->exec(
219                                     sub {
220                                         if (open my $fh, $_) {
221                                             my $shebang = <$fh>;
222                                             close $fh;
223                                             return $shebang =~ /^#!.*\bperl/;
224                                         }
225                                         return 0;
226                                     } ),
227             );
228
229           Based upon this message
230           http://use.perl.org/comments.pl?sid=7052&cid=10842
231
232       ignore CVS directories
233            my $rule = File::Find::Rule->new;
234            $rule->or($rule->new
235                           ->directory
236                           ->name('CVS')
237                           ->prune
238                           ->discard,
239                      $rule->new);
240
241           Note here the use of a null rule.  Null rules match anything they
242           see, so the effect is to match (and discard) directories called
243           'CVS' or to match anything.
244

TWO FOR THE PRICE OF ONE

246       File::Find::Rule also gives you a procedural interface.  This is
247       documented in File::Find::Rule::Procedural
248

EXPORTS

250       "find", "rule"
251

TAINT MODE INTERACTION

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

BUGS

265       The code makes use of the "our" keyword and as such requires perl
266       version 5.6.0 or newer.
267
268       Currently it isn't possible to remove a clause from a rule object.  If
269       this becomes a significant issue it will be addressed.
270

AUTHOR

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

SEE ALSO

286       File::Find, Text::Glob, Number::Compare, find(1)
287
288       If you want to know about the procedural interface, see
289       File::Find::Rule::Procedural, and if you have an idea for a neat
290       extension File::Find::Rule::Extending
291
292
293
294perl v5.12.4                      2011-09-19               File::Find::Rule(3)
Impressum