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 )"
36 Specifies names that should match. May be globs or regular
37 expressions.
38 $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 -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 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 Though some tests are fairly meaningless as binary flags
68 ("modified", "accessed", "changed"), they have been included for
69 completeness.
70 # find nonempty files
72 $rule->file,
73 ->nonempty;
74 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 Each of these can take a number of targets, which will follow
82 Number::Compare semantics.
83 $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 "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 # 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 "none( @rules )"
103 "not( @rules )"
104 Negates a rule. (The inverse of "any".) "none" and "not" are
105 interchangeable.
106 # files that aren't 8.3 safe
108 $rule->file
109 ->not( $rule->new->name( qr/^[^.]{1,8}(\.[^.]{0,3})?$/ ) );
110 "prune"
112 Traverse no further. This rule always matches.
113 "discard"
115 Don't keep this file. This rule always matches.
116 "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 Return a true value if your rule matched.
123 # get things with long names
125 $rules->exec( sub { length > 20 } );
126 "grep( @specifiers )"
128 Opens a file and tests it each line at a time.
129 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 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 $rule->grep( qr/^#!.*\bperl/, [ sub { 1 } ] );
140 Is a passing clause if the first line of a file looks like a perl
142 shebang line.
143 "maxdepth( $level )"
145 Descend at most $level (a non-negative integer) levels of
146 directories below the starting point.
147 May be invoked many times per rule, but only the most recent value
149 is used.
150 "mindepth( $level )"
152 Do not apply any tests at levels less than $level (a non-negative
153 integer).
154 "extras( \%extras )"
156 Specifies extra values to pass through to "File::File::find" as
157 part of the options hash.
158 For example this allows you to specify following of symlinks like
160 so:
161 my $rule = File::Find::Rule->extras({ follow => 1 });
163 May be invoked many times per rule, but only the most recent value
165 is used.
166 "relative"
168 Trim the leading portion of any path found
169 "not_*"
171 Negated version of the rule. An effective shortand related to ! in
172 the procedural interface.
173 $foo->not_name('*.pl');
175 $foo->not( $foo->new->name('*.pl' ) );
177 Query Methods
179 "in( @directories )"
180 Evaluates the rule, returns a list of paths to matching files and
181 directories.
182 "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 my $rule = File::Find::Rule->file->name("*.jpeg")->start( "/web" );
189 while ( defined ( my $image = $rule->match ) ) {
190 ...
191 }
192 "match"
194 Returns the next file which matches, false if there are no more.
195 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 use File::Find::Rule::ImageSize;
201 use File::Find::Rule::MMagic;
202 # now your rules can use the clauses supplied by the ImageSize and
204 # MMagic extension
205 or, specify that File::Find::Rule should load them for you:
207 use File::Find::Rule qw( :ImageSize :MMagic );
209 For notes on implementing your own extensions, consult
211 File::Find::Rule::Extending
212 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 Based upon this message
230 http://use.perl.org/comments.pl?sid=7052&cid=10842
231 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 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
246 File::Find::Rule also gives you a procedural interface. This is
247 documented in File::Find::Rule::Procedural
248
250 "find", "rule"
251
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 my $rule = File::Find::Rule->extras({ untaint => 1 });
260 Please consult File::Find's documentation for "untaint",
262 "untaint_pattern", and "untaint_skip" for more information.
263
265 The code makes use of the "our" keyword and as such requires perl
266 version 5.6.0 or newer.
267 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
272 Richard Clamp <richardc@unixbeard.net> with input gained from this
273 use.perl discussion: http://use.perl.org/~richardc/journal/6467
274 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 This module is free software; you can redistribute it and/or modify it
283 under the same terms as Perl itself.
284
286 File::Find, Text::Glob, Number::Compare, find(1)
287 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
291perl v5.16.3 2011-09-19 File::Find::Rule(3)