1File::Find::Rule(3) User Contributed Perl Documentation File::Find::Rule(3)
2
6 File::Find::Rule - Alternative interface to File::Find
7
9 use File::Find::Rule;
10 # find all the subdirectories of a given directory
11 my @subdirs = File::Find::Rule->directory->in( $directory );
12 # find all the .pm files in @INC
14 my @files = File::Find::Rule->file()
15 ->name( '*.pm' )
16 ->in( @INC );
17 # 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
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
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 Matching Rules
35 "name( @patterns )"
37 Specifies names that should match. May be globs or regular expres‐
38 sions.
39 $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 -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 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 Though some tests are fairly meaningless as binary flags ("modi‐
69 fied", "accessed", "changed"), they have been included for com‐
70 pleteness.
71 # find nonempty files
73 $rule->file,
74 ->nonempty;
75 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 Each of these can take a number of targets, which will follow Num‐
83 ber::Compare semantics.
84 $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 "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 # 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 "none( @rules )"
104 "not( @rules )"
105 Negates a rule. (The inverse of "any".) "none" and "not" are
106 interchangeable.
107 # files that aren't 8.3 safe
109 $rule->file
110 ->not( $rule->new->name( qr/^[^.]{1,8}(\.[^.]{0,3})?$/ ) );
111 "prune"
113 Traverse no further. This rule always matches.
114 "discard"
116 Don't keep this file. This rule always matches.
117 "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 Return a true value if your rule matched.
124 # get things with long names
126 $rules->exec( sub { length > 20 } );
127 ->grep( @specifiers );
129 Opens a file and tests it each line at a time.
130 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 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 $rule->grep( qr/^#!.*\bperl/, [ sub { 1 } ] );
141 Is a passing clause if the first line of a file looks like a perl
143 shebang line.
144 "maxdepth( $level )"
146 Descend at most $level (a non-negative integer) levels of directo‐
147 ries below the starting point.
148 May be invoked many times per rule, but only the most recent value
150 is used.
151 "mindepth( $level )"
153 Do not apply any tests at levels less than $level (a non-negative
154 integer).
155 "extras( \%extras )"
157 Specifies extra values to pass through to "File::File::find" as
158 part of the options hash.
159 For example this allows you to specify following of symlinks like
161 so:
162 my $rule = File::Find::Rule->extras({ follow => 1 });
164 May be invoked many times per rule, but only the most recent value
166 is used.
167 "relative"
169 Trim the leading portion of any path found
170 "not_*"
172 Negated version of the rule. An effective shortand related to ! in
173 the procedural interface.
174 $foo->not_name('*.pl');
176 $foo->not( $foo->new->name('*.pl' ) );
178 Query Methods
180 "in( @directories )"
182 Evaluates the rule, returns a list of paths to matching files and
183 directories.
184 "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 my $rule = File::Find::Rule->file->name("*.jpeg")->start( "/web" );
191 while ( my $image = $rule->match ) {
192 ...
193 }
194 "match"
196 Returns the next file which matches, false if there are no more.
197 Extensions
199 Extension modules are available from CPAN in the File::Find::Rule
201 namespace. In order to use these extensions either use them directly:
202 use File::Find::Rule::ImageSize;
204 use File::Find::Rule::MMagic;
205 # now your rules can use the clauses supplied by the ImageSize and
207 # MMagic extension
208 or, specify that File::Find::Rule should load them for you:
210 use File::Find::Rule qw( :ImageSize :MMagic );
212 For notes on implementing your own extensions, consult
214 File::Find::Rule::Extending
215 Further examples
217 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 Based upon this message http://use.perl.org/com‐
234 ments.pl?sid=7052&cid=10842
235 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 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
250 File::Find::Rule also gives you a procedural interface. This is docu‐
251 mented in File::Find::Rule::Procedural
252
254 "find", "rule"
255
257 The code relies on qr// compiled regexes, therefore this module
258 requires perl version 5.005_03 or newer.
259 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
264 Richard Clamp <richardc@unixbeard.net> with input gained from this
265 use.perl discussion: http://use.perl.org/~richardc/journal/6467
266 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 This module is free software; you can redistribute it and/or modify it
275 under the same terms as Perl itself.
276
278 File::Find, Text::Glob, Number::Compare, find(1)
279 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
283perl v5.8.8 2006-06-01 File::Find::Rule(3)