1File::Find::Object::RulUes(e3r)Contributed Perl DocumentFaitlieo:n:Find::Object::Rule(3)
2
3
4

NAME

6       File::Find::Object::Rule - Alternative interface to File::Find::Object
7

VERSION

9       version 0.0313
10

SYNOPSIS

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
16         # find all the .pm files in @INC
17         my @files = File::Find::Object::Rule->file()
18                                     ->name( '*.pm' )
19                                     ->in( @INC );
20
21         # 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

DESCRIPTION

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
32       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

METHODS

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
44   finder
45       The File::Find::Object finder instance itself.
46
47   my @rules = @{$ffor->rules()};
48       The rules to match against. For internal use only.
49
50   Matching Rules
51       "name( @patterns )"
52           Specifies names that should match.  May be globs or regular
53           expressions.
54
55            $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
59       -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
63             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
83           Though some tests are fairly meaningless as binary flags
84           ("modified", "accessed", "changed"), they have been included for
85           completeness.
86
87            # find nonempty files
88            $rule->file,
89                 ->nonempty;
90
91       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
97           Each of these can take a number of targets, which will follow
98           Number::Compare semantics.
99
100            $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
106       "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
112            # 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
118       "none( @rules )"
119       "not( @rules )"
120           Negates a rule.  (The inverse of "any".)  "none" and "not" are
121           interchangeable.
122
123             # files that aren't 8.3 safe
124             $rule->file
125                  ->not( $rule->new->name( qr/^[^.]{1,8}(\.[^.]{0,3})?$/ ) );
126
127       "prune"
128           Traverse no further.  This rule always matches.
129
130       "discard"
131           Don't keep this file.  This rule always matches.
132
133       "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
140           Return a true value if your rule matched.
141
142            # get things with long names
143            $rules->exec( sub { length > 20 } );
144
145       ->grep( @specifiers );
146           Opens a file and tests it each line at a time.
147
148           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
153           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
157            $rule->grep( qr/^#!.*\bperl/, [ sub { 1 } ] );
158
159           Is a passing clause if the first line of a file looks like a perl
160           shebang line.
161
162       "maxdepth( $level )"
163           Descend at most $level (a non-negative integer) levels of
164           directories below the starting point.
165
166           May be invoked many times per rule, but only the most recent value
167           is used.
168
169       "mindepth( $level )"
170           Do not apply any tests at levels less than $level (a non-negative
171           integer).
172
173       "extras( \%extras )"
174           Specifies extra values to pass through to "File::File::find" as
175           part of the options hash.
176
177           For example this allows you to specify following of symlinks like
178           so:
179
180            my $rule = File::Find::Object::Rule->extras({ follow => 1 });
181
182           May be invoked many times per rule, but only the most recent value
183           is used.
184
185       "relative"
186           Trim the leading portion of any path found
187
188       "not_*"
189           Negated version of the rule.  An effective shortand related to ! in
190           the procedural interface.
191
192            $foo->not_name('*.pl');
193
194            $foo->not( $foo->new->name('*.pl' ) );
195
196   Query Methods
197       "in( @directories )"
198           Evaluates the rule, returns a list of paths to matching files and
199           directories.
200
201       "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
206            my $rule = File::Find::Object::Rule->file->name("*.jpeg")->start( "/web" );
207            while ( my $image = $rule->match ) {
208                ...
209            }
210
211       "match"
212           Returns the next file which matches, false if there are no more.
213
214   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
219        use File::Find::Object::Rule::ImageSize;
220        use File::Find::Object::Rule::MMagic;
221
222        # now your rules can use the clauses supplied by the ImageSize and
223        # MMagic extension
224
225       or, specify that File::Find::Object::Rule should load them for you:
226
227        use File::Find::Object::Rule qw( :ImageSize :MMagic );
228
229       For notes on implementing your own extensions, consult
230       File::Find::Object::Rule::Extending
231
232   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
248           Based upon this message
249           http://use.perl.org/comments.pl?sid=7052&cid=10842
250
251       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
260           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

TWO FOR THE PRICE OF ONE

265       File::Find::Object::Rule also gives you a procedural interface.  This
266       is documented in File::Find::Object::Rule::Procedural
267

EXPORTS

269   find
270   rule

Tests

272   accessed
273       Corresponds to "-A".
274
275   ascii
276       Corresponds to "-T".
277
278   atime
279       See "stat tests".
280
281   binary
282       Corresponds to "-b".
283
284   blksize
285       See "stat tests".
286
287   block
288       Corresponds to "-b".
289
290   blocks
291       See "stat tests".
292
293   changed
294       Corresponds to "-C".
295
296   character
297       Corresponds to "-c".
298
299   ctime
300       See "stat tests".
301
302   dev
303       See "stat tests".
304
305   directory
306       Corresponds to "-d".
307
308   empty
309       Corresponds to "-z".
310
311   executable
312       Corresponds to "-x".
313
314   exists
315       Corresponds to "-e".
316
317   fifo
318       Corresponds to "-p".
319
320   file
321       Corresponds to "-f".
322
323   gid
324       See "stat tests".
325
326   ino
327       See "stat tests".
328
329   mode
330       See "stat tests".
331
332   modified
333       Corresponds to "-M".
334
335   mtime
336       See "stat tests".
337
338   nlink
339       See "stat tests".
340
341   r_executable
342       Corresponds to "-X".
343
344   r_owned
345       Corresponds to "-O".
346
347   nonempty
348       A predicate that determines if the file is empty. Uses "-s".
349
350   owned
351       Corresponds to "-o".
352
353   r_readable
354       Corresponds to "-R".
355
356   r_writeable
357   r_writable
358       Corresponds to "-W".
359
360   rdev
361       See "stat tests".
362
363   readable
364       Corresponds to "-r".
365
366   setgid
367       Corresponds to "-g".
368
369   setuid
370       Corresponds to "-u".
371
372   size
373       See stat tests.
374
375   socket
376       Corresponds to "-S".
377
378   sticky
379       Corresponds to "-k".
380
381   symlink
382       Corresponds to "-l".
383
384   uid
385       See "stat tests".
386
387   tty
388       Corresponds to "-t".
389
390   writable()
391       Corresponds to "-w".
392

BUGS

394       The code relies on qr// compiled regexes, therefore this module
395       requires perl version 5.005_03 or newer.
396
397       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

AUTHOR

401       Richard Clamp <richardc@unixbeard.net> with input gained from this
402       use.perl discussion: http://use.perl.org/~richardc/journal/6467
403
404       Additional proofreading and input provided by Kake, Greg McCarroll, and
405       Andy Lester andy@petdance.com.
406
407       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
414       This module is free software; you can redistribute it and/or modify it
415       under the same terms as Perl itself.
416

SEE ALSO

418       File::Find::Object, Text::Glob, Number::Compare, find(1)
419
420       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
424       Path::Class::Rule Xs 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

KNOWN BUGS

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

SUPPORT

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
439       •   MetaCPAN
440
441           A modern, open-source CPAN search engine, useful to view POD in
442           HTML format.
443
444           <https://metacpan.org/release/File-Find-Object-Rule>
445
446       •   RT: CPAN's Bug Tracker
447
448           The RT ( Request Tracker ) website is the default bug/issue
449           tracking system for CPAN.
450
451           <https://rt.cpan.org/Public/Dist/Display.html?Name=File-Find-Object-Rule>
452
453       •   CPANTS
454
455           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
456           of a distribution.
457
458           <http://cpants.cpanauthors.org/dist/File-Find-Object-Rule>
459
460       •   CPAN Testers
461
462           The CPAN Testers is a network of smoke testers who run automated
463           tests on uploaded CPAN distributions.
464
465           <http://www.cpantesters.org/distro/F/File-Find-Object-Rule>
466
467       •   CPAN Testers Matrix
468
469           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
473           <http://matrix.cpantesters.org/?dist=File-Find-Object-Rule>
474
475       •   CPAN Testers Dependencies
476
477           The CPAN Testers Dependencies is a website that shows a chart of
478           the test results of all dependencies for a distribution.
479
480           <http://deps.cpantesters.org/?module=File::Find::Object::Rule>
481
482   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
490   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
496       <https://github.com/shlomif/http://bitbucket.org/shlomif/perl-file-find-object-rule>
497
498         git clone git://github.com/shlomif/http://bitbucket.org/shlomif/perl-file-find-object-rule.git
499

AUTHORS

501       •   Richard Clamp <richardc@unixbeard.net>
502
503       •   Andy Lester andy@petdance.com.
504

BUGS

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
509       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
515       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.
517
518
519
520perl v5.34.0                      2021-08-27       File::Find::Object::Rule(3)
Impressum