1File::Find::Object::RulUes(e3rpmC)ontributed Perl DocumeFnitlaet:i:oFnind::Object::Rule(3pm)
2
6 File::Find::Object::Rule - Alternative interface to File::Find::Object
7
9 version 0.0313
10
12 use File::Find::Object::Rule;
13 # find all the subdirectories of a given directory
14 my @subdirs = File::Find::Object::Rule->directory->in( $directory );
15 # find all the .pm files in @INC
17 my @files = File::Find::Object::Rule->file()
18 ->name( '*.pm' )
19 ->in( @INC );
20 # as above, but without method chaining
22 my $rule = File::Find::Object::Rule->new;
23 $rule->file;
24 $rule->name( '*.pm' );
25 my @files = $rule->in( @INC );
26
28 File::Find::Object::Rule is a friendlier interface to
29 File::Find::Object . It allows you to build rules which specify the
30 desired files and directories.
31 WARNING : This module is a fork of version 0.30 of File::Find::Rule
33 (which has been unmaintained for several years as of February, 2009),
34 and may still have some bugs due to its reliance on File::Find'isms. As
35 such it is considered Alpha software. Please report any problems with
36 File::Find::Object::Rule to its RT CPAN Queue.
37
39 "new"
40 A constructor. You need not invoke "new" manually unless you wish
41 to, as each of the rule-making methods will auto-create a suitable
42 object if called as class methods.
43 finder
45 The File::Find::Object finder instance itself.
46 my @rules = @{$ffor->rules()};
48 The rules to match against. For internal use only.
49 Matching Rules
51 name( @patterns )
52 Specifies names that should match. May be globs or regular
53 expressions.
54 $set->name( '*.mp3', '*.ogg' ); # mp3s or oggs
56 $set->name( qr/\.(mp3|ogg)$/ ); # the same as a regex
57 $set->name( 'foo.bar' ); # just things named foo.bar
58 -X tests
60 Synonyms are provided for each of the -X tests. See "-X" in
61 perlfunc for details. None of these methods take arguments.
62 Test | Method Test | Method
64 ------|------------- ------|----------------
65 -r | readable -R | r_readable
66 -w | writeable -W | r_writeable
67 -w | writable -W | r_writable
68 -x | executable -X | r_executable
69 -o | owned -O | r_owned
70 | |
71 -e | exists -f | file
72 -z | empty -d | directory
73 -s | nonempty -l | symlink
74 | -p | fifo
75 -u | setuid -S | socket
76 -g | setgid -b | block
77 -k | sticky -c | character
78 | -t | tty
79 -M | modified |
80 -A | accessed -T | ascii
81 -C | changed -B | binary
82 Though some tests are fairly meaningless as binary flags
84 ("modified", "accessed", "changed"), they have been included for
85 completeness.
86 # find nonempty files
88 $rule->file,
89 ->nonempty;
90 stat tests
92 The following "stat" based methods are provided: "dev", "ino",
93 "mode", "nlink", "uid", "gid", "rdev", "size", "atime", "mtime",
94 "ctime", "blksize", and "blocks". See "stat" in perlfunc for
95 details.
96 Each of these can take a number of targets, which will follow
98 Number::Compare semantics.
99 $rule->size( 7 ); # exactly 7
101 $rule->size( ">7Ki" ); # larger than 7 * 1024 * 1024 bytes
102 $rule->size( ">=7" )
103 ->size( "<=90" ); # between 7 and 90, inclusive
104 $rule->size( 7, 9, 42 ); # 7, 9 or 42
105 any( @rules )
107 or( @rules )
108 Allows shortcircuiting boolean evaluation as an alternative to the
109 default and-like nature of combined rules. "any" and "or" are
110 interchangeable.
111 # find avis, movs, things over 200M and empty files
113 $rule->any( File::Find::Object::Rule->name( '*.avi', '*.mov' ),
114 File::Find::Object::Rule->size( '>200M' ),
115 File::Find::Object::Rule->file->empty,
116 );
117 none( @rules )
119 not( @rules )
120 Negates a rule. (The inverse of "any".) "none" and "not" are
121 interchangeable.
122 # files that aren't 8.3 safe
124 $rule->file
125 ->not( $rule->new->name( qr/^[^.]{1,8}(\.[^.]{0,3})?$/ ) );
126 "prune"
128 Traverse no further. This rule always matches.
129 "discard"
131 Don't keep this file. This rule always matches.
132 "exec( \&subroutine( $shortname, $path, $fullname ) )"
134 Allows user-defined rules. Your subroutine will be invoked with
135 parameters of the name, the path you're in, and the full relative
136 filename. In addition, $_ is set to the current short name, but
137 its use is discouraged since as opposed to File::Find::Rule,
138 File::Find::Object::Rule does not cd to the containing directory.
139 Return a true value if your rule matched.
141 # get things with long names
143 $rules->exec( sub { length > 20 } );
144 ->grep( @specifiers );
146 Opens a file and tests it each line at a time.
147 For each line it evaluates each of the specifiers, stopping at the
149 first successful match. A specifier may be a regular expression or
150 a subroutine. The subroutine will be invoked with the same
151 parameters as an ->exec subroutine.
152 It is possible to provide a set of negative specifiers by enclosing
154 them in anonymous arrays. Should a negative specifier match the
155 iteration is aborted and the clause is failed. For example:
156 $rule->grep( qr/^#!.*\bperl/, [ sub { 1 } ] );
158 Is a passing clause if the first line of a file looks like a perl
160 shebang line.
161 maxdepth( $level )
163 Descend at most $level (a non-negative integer) levels of
164 directories below the starting point.
165 May be invoked many times per rule, but only the most recent value
167 is used.
168 mindepth( $level )
170 Do not apply any tests at levels less than $level (a non-negative
171 integer).
172 extras( \%extras )
174 Specifies extra values to pass through to "File::File::find" as
175 part of the options hash.
176 For example this allows you to specify following of symlinks like
178 so:
179 my $rule = File::Find::Object::Rule->extras({ follow => 1 });
181 May be invoked many times per rule, but only the most recent value
183 is used.
184 "relative"
186 Trim the leading portion of any path found
187 "not_*"
189 Negated version of the rule. An effective shortand related to ! in
190 the procedural interface.
191 $foo->not_name('*.pl');
193 $foo->not( $foo->new->name('*.pl' ) );
195 Query Methods
197 in( @directories )
198 Evaluates the rule, returns a list of paths to matching files and
199 directories.
200 start( @directories )
202 Starts a find across the specified directories. Matching items may
203 then be queried using "match". This allows you to use a rule as an
204 iterator.
205 my $rule = File::Find::Object::Rule->file->name("*.jpeg")->start( "/web" );
207 while ( my $image = $rule->match ) {
208 ...
209 }
210 "match"
212 Returns the next file which matches, false if there are no more.
213 Extensions
215 Extension modules are available from CPAN in the
216 File::Find::Object::Rule namespace. In order to use these extensions
217 either use them directly:
218 use File::Find::Object::Rule::ImageSize;
220 use File::Find::Object::Rule::MMagic;
221 # now your rules can use the clauses supplied by the ImageSize and
223 # MMagic extension
224 or, specify that File::Find::Object::Rule should load them for you:
226 use File::Find::Object::Rule qw( :ImageSize :MMagic );
228 For notes on implementing your own extensions, consult
230 File::Find::Object::Rule::Extending
231 Further examples
233 Finding perl scripts
234 my $finder = File::Find::Object::Rule->or
235 (
236 File::Find::Object::Rule->name( '*.pl' ),
237 File::Find::Object::Rule->exec(
238 sub {
239 if (open my $fh, $_) {
240 my $shebang = <$fh>;
241 close $fh;
242 return $shebang =~ /^#!.*\bperl/;
243 }
244 return 0;
245 } ),
246 );
247 Based upon this message
249 http://use.perl.org/comments.pl?sid=7052&cid=10842
250 ignore CVS directories
252 my $rule = File::Find::Object::Rule->new;
253 $rule->or($rule->new
254 ->directory
255 ->name('CVS')
256 ->prune
257 ->discard,
258 $rule->new);
259 Note here the use of a null rule. Null rules match anything they
261 see, so the effect is to match (and discard) directories called
262 'CVS' or to match anything.
263
265 File::Find::Object::Rule also gives you a procedural interface. This
266 is documented in File::Find::Object::Rule::Procedural
267
269 find
270 rule
272 accessed
273 Corresponds to "-A".
274 ascii
276 Corresponds to "-T".
277 atime
279 See "stat tests".
280 binary
282 Corresponds to "-b".
283 blksize
285 See "stat tests".
286 block
288 Corresponds to "-b".
289 blocks
291 See "stat tests".
292 changed
294 Corresponds to "-C".
295 character
297 Corresponds to "-c".
298 ctime
300 See "stat tests".
301 dev
303 See "stat tests".
304 directory
306 Corresponds to "-d".
307 empty
309 Corresponds to "-z".
310 executable
312 Corresponds to "-x".
313 exists
315 Corresponds to "-e".
316 fifo
318 Corresponds to "-p".
319 file
321 Corresponds to "-f".
322 gid
324 See "stat tests".
325 ino
327 See "stat tests".
328 mode
330 See "stat tests".
331 modified
333 Corresponds to "-M".
334 mtime
336 See "stat tests".
337 nlink
339 See "stat tests".
340 r_executable
342 Corresponds to "-X".
343 r_owned
345 Corresponds to "-O".
346 nonempty
348 A predicate that determines if the file is empty. Uses "-s".
349 owned
351 Corresponds to "-o".
352 r_readable
354 Corresponds to "-R".
355 r_writeable
357 r_writable
358 Corresponds to "-W".
359 rdev
361 See "stat tests".
362 readable
364 Corresponds to "-r".
365 setgid
367 Corresponds to "-g".
368 setuid
370 Corresponds to "-u".
371 size
373 See stat tests.
374 socket
376 Corresponds to "-S".
377 sticky
379 Corresponds to "-k".
380 symlink
382 Corresponds to "-l".
383 uid
385 See "stat tests".
386 tty
388 Corresponds to "-t".
389 writable()
391 Corresponds to "-w".
392
394 The code relies on qr// compiled regexes, therefore this module
395 requires perl version 5.005_03 or newer.
396 Currently it isn't possible to remove a clause from a rule object. If
398 this becomes a significant issue it will be addressed.
399
401 Richard Clamp <richardc@unixbeard.net> with input gained from this
402 use.perl discussion: http://use.perl.org/~richardc/journal/6467
403 Additional proofreading and input provided by Kake, Greg McCarroll, and
405 Andy Lester andy@petdance.com.
406 Ported to use File::Find::Object as File::Find::Object::Rule by Shlomi
408 Fish.
409
411 Copyright (C) 2002, 2003, 2004, 2006 Richard Clamp. All Rights
412 Reserved.
413 This module is free software; you can redistribute it and/or modify it
415 under the same terms as Perl itself.
416
418 File::Find::Object, Text::Glob, Number::Compare, find(1)
419 If you want to know about the procedural interface, see
421 File::Find::Object::Rule::Procedural, and if you have an idea for a
422 neat extension, see File::Find::Object::Rule::Extending .
423 Path::Class::Rule ’s SEE ALSO contains a review of many directory
425 traversal modules on CPAN, including File::Find::Object::Rule and
426 File::Find::Rule (on which this module is based).
427
429 The tests don't run successfully when directly inside an old Subversion
430 checkout, due to the presence of ".svn" directories. "./Build disttest"
431 or "./Build distruntest" run fine.
432
434 Websites
435 The following websites have more information about this module, and may
436 be of help to you. As always, in addition to those websites please use
437 your favorite search engine to discover more resources.
438 • MetaCPAN
440 A modern, open-source CPAN search engine, useful to view POD in
442 HTML format.
443 <https://metacpan.org/release/File-Find-Object-Rule>
445 • RT: CPAN's Bug Tracker
447 The RT ( Request Tracker ) website is the default bug/issue
449 tracking system for CPAN.
450 <https://rt.cpan.org/Public/Dist/Display.html?Name=File-Find-Object-Rule>
452 • CPANTS
454 The CPANTS is a website that analyzes the Kwalitee ( code metrics )
456 of a distribution.
457 <http://cpants.cpanauthors.org/dist/File-Find-Object-Rule>
459 • CPAN Testers
461 The CPAN Testers is a network of smoke testers who run automated
463 tests on uploaded CPAN distributions.
464 <http://www.cpantesters.org/distro/F/File-Find-Object-Rule>
466 • CPAN Testers Matrix
468 The CPAN Testers Matrix is a website that provides a visual
470 overview of the test results for a distribution on various
471 Perls/platforms.
472 <http://matrix.cpantesters.org/?dist=File-Find-Object-Rule>
474 • CPAN Testers Dependencies
476 The CPAN Testers Dependencies is a website that shows a chart of
478 the test results of all dependencies for a distribution.
479 <http://deps.cpantesters.org/?module=File::Find::Object::Rule>
481 Bugs / Feature Requests
483 Please report any bugs or feature requests by email to
484 "bug-file-find-object-rule at rt.cpan.org", or through the web
485 interface at
486 <https://rt.cpan.org/Public/Bug/Report.html?Queue=File-Find-Object-Rule>.
487 You will be automatically notified of any progress on the request by
488 the system.
489 Source Code
491 The code is open to the world, and available for you to hack on. Please
492 feel free to browse it and play with it, or whatever. If you want to
493 contribute patches, please send me a diff or prod me to pull from your
494 repository :)
495 <https://github.com/shlomif/http://bitbucket.org/shlomif/perl-file-find-object-rule>
497 git clone git://github.com/shlomif/http://bitbucket.org/shlomif/perl-file-find-object-rule.git
499
501 • Richard Clamp <richardc@unixbeard.net>
502 • Andy Lester andy@petdance.com.
504
506 Please report any bugs or feature requests on the bugtracker website
507 <https://github.com/shlomif/http://bitbucket.org/shlomif/perl-file-find-object-rule/issues>
508 When submitting a bug or request, please include a test-file or a patch
510 to an existing test-file that illustrates the bug or desired feature.
511
513 This software is copyright (c) 2021 by Richard Clamp.
514 This is free software; you can redistribute it and/or modify it under
516 the same terms as the Perl 5 programming language system itself.
517perl v5.38.0 2023-07-20 File::Find::Object::Rule(3pm)