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

TWO FOR THE PRICE OF ONE

250       File::Find::Rule also gives you a procedural interface.  This is docu‐
251       mented in File::Find::Rule::Procedural
252

EXPORTS

254       "find", "rule"
255

BUGS

257       The code relies on qr// compiled regexes, therefore this module
258       requires perl version 5.005_03 or newer.
259
260       Currently it isn't possible to remove a clause from a rule object.  If
261       this becomes a significant issue it will be addressed.
262

AUTHOR

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

SEE ALSO

278       File::Find, Text::Glob, Number::Compare, find(1)
279
280       If you want to know about the procedural interface, see
281       File::Find::Rule::Procedural, and if you have an idea for a neat exten‐
282       sion File::Find::Rule::Extending
283
284
285
286perl v5.8.8                       2006-06-01               File::Find::Rule(3)
Impressum