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 "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 For example, this will return "tmp/foobar" on Unix-ish OSes and
177 "tmp\foobar" on Win32.
178 "not_*"
180 Negated version of the rule. An effective shortand related to ! in
181 the procedural interface.
182 $foo->not_name('*.pl');
184 $foo->not( $foo->new->name('*.pl' ) );
186 Query Methods
188 "in( @directories )"
189 Evaluates the rule, returns a list of paths to matching files and
190 directories.
191 "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 my $rule = File::Find::Rule->file->name("*.jpeg")->start( "/web" );
198 while ( defined ( my $image = $rule->match ) ) {
199 ...
200 }
201 "match"
203 Returns the next file which matches, false if there are no more.
204 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 use File::Find::Rule::ImageSize;
210 use File::Find::Rule::MMagic;
211 # now your rules can use the clauses supplied by the ImageSize and
213 # MMagic extension
214 or, specify that File::Find::Rule should load them for you:
216 use File::Find::Rule qw( :ImageSize :MMagic );
218 For notes on implementing your own extensions, consult
220 File::Find::Rule::Extending
221 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 Based upon this message
239 http://use.perl.org/comments.pl?sid=7052&cid=10842
240 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 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
255 File::Find::Rule also gives you a procedural interface. This is
256 documented in File::Find::Rule::Procedural
257
259 "find", "rule"
260
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 my $rule = File::Find::Rule->extras({ untaint => 1 });
269 Please consult File::Find's documentation for "untaint",
271 "untaint_pattern", and "untaint_skip" for more information.
272
274 The code makes use of the "our" keyword and as such requires perl
275 version 5.6.0 or newer.
276 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
281 Richard Clamp <richardc@unixbeard.net> with input gained from this
282 use.perl discussion: http://use.perl.org/~richardc/journal/6467
283 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 This module is free software; you can redistribute it and/or modify it
292 under the same terms as Perl itself.
293
295 File::Find, Text::Glob, Number::Compare, find(1)
296 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
300perl v5.34.0 2021-07-22 File::Find::Rule(3)