File::Find::Object::Rule(3pm)

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.0309
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

VERSION

39       version 0.0309
40

METHODS

42       "new"
43           A constructor.  You need not invoke "new" manually unless you wish
44           to, as each of the rule-making methods will auto-create a suitable
45           object if called as class methods.
46
47   finder
48       The File::Find::Object finder instance itself.
49
50   my @rules = @{$ffor->rules()};
51       The rules to match against. For internal use only.
52
53   Matching Rules
54       "name( @patterns )"
55           Specifies names that should match.  May be globs or regular
56           expressions.
57
58            $set->name( '*.mp3', '*.ogg' ); # mp3s or oggs
59            $set->name( qr/\.(mp3|ogg)$/ ); # the same as a regex
60            $set->name( 'foo.bar' );        # just things named foo.bar
61
62       -X tests
63           Synonyms are provided for each of the -X tests. See "-X" in
64           perlfunc for details.  None of these methods take arguments.
65
66             Test | Method               Test |  Method
67            ------|-------------        ------|----------------
68              -r  |  readable             -R  |  r_readable
69              -w  |  writeable            -W  |  r_writeable
70              -w  |  writable             -W  |  r_writable
71              -x  |  executable           -X  |  r_executable
72              -o  |  owned                -O  |  r_owned
73                  |                           |
74              -e  |  exists               -f  |  file
75              -z  |  empty                -d  |  directory
76              -s  |  nonempty             -l  |  symlink
77                  |                       -p  |  fifo
78              -u  |  setuid               -S  |  socket
79              -g  |  setgid               -b  |  block
80              -k  |  sticky               -c  |  character
81                  |                       -t  |  tty
82              -M  |  modified                 |
83              -A  |  accessed             -T  |  ascii
84              -C  |  changed              -B  |  binary
85
86           Though some tests are fairly meaningless as binary flags
87           ("modified", "accessed", "changed"), they have been included for
88           completeness.
89
90            # find nonempty files
91            $rule->file,
92                 ->nonempty;
93
94       stat tests
95           The following "stat" based methods are provided: "dev", "ino",
96           "mode", "nlink", "uid", "gid", "rdev", "size", "atime", "mtime",
97           "ctime", "blksize", and "blocks".  See "stat" in perlfunc for
98           details.
99
100           Each of these can take a number of targets, which will follow
101           Number::Compare semantics.
102
103            $rule->size( 7 );         # exactly 7
104            $rule->size( ">7Ki" );    # larger than 7 * 1024 * 1024 bytes
105            $rule->size( ">=7" )
106                 ->size( "<=90" );    # between 7 and 90, inclusive
107            $rule->size( 7, 9, 42 );  # 7, 9 or 42
108
109       "any( @rules )"
110       "or( @rules )"
111           Allows shortcircuiting boolean evaluation as an alternative to the
112           default and-like nature of combined rules.  "any" and "or" are
113           interchangeable.
114
115            # find avis, movs, things over 200M and empty files
116            $rule->any( File::Find::Object::Rule->name( '*.avi', '*.mov' ),
117                        File::Find::Object::Rule->size( '>200M' ),
118                        File::Find::Object::Rule->file->empty,
119                      );
120
121       "none( @rules )"
122       "not( @rules )"
123           Negates a rule.  (The inverse of "any".)  "none" and "not" are
124           interchangeable.
125
126             # files that aren't 8.3 safe
127             $rule->file
128                  ->not( $rule->new->name( qr/^[^.]{1,8}(\.[^.]{0,3})?$/ ) );
129
130       "prune"
131           Traverse no further.  This rule always matches.
132
133       "discard"
134           Don't keep this file.  This rule always matches.
135
136       "exec( \&subroutine( $shortname, $path, $fullname ) )"
137           Allows user-defined rules.  Your subroutine will be invoked with
138           parameters of the name, the path you're in, and the full relative
139           filename.  In addition, $_ is set to the current short name, but
140           its use is discouraged since as opposed to File::Find::Rule,
141           File::Find::Object::Rule does not cd to the containing directory.
142
143           Return a true value if your rule matched.
144
145            # get things with long names
146            $rules->exec( sub { length > 20 } );
147
148       ->grep( @specifiers );
149           Opens a file and tests it each line at a time.
150
151           For each line it evaluates each of the specifiers, stopping at the
152           first successful match.  A specifier may be a regular expression or
153           a subroutine.  The subroutine will be invoked with the same
154           parameters as an ->exec subroutine.
155
156           It is possible to provide a set of negative specifiers by enclosing
157           them in anonymous arrays.  Should a negative specifier match the
158           iteration is aborted and the clause is failed.  For example:
159
160            $rule->grep( qr/^#!.*\bperl/, [ sub { 1 } ] );
161
162           Is a passing clause if the first line of a file looks like a perl
163           shebang line.
164
165       "maxdepth( $level )"
166           Descend at most $level (a non-negative integer) levels of
167           directories below the starting point.
168
169           May be invoked many times per rule, but only the most recent value
170           is used.
171
172       "mindepth( $level )"
173           Do not apply any tests at levels less than $level (a non-negative
174           integer).
175
176       "extras( \%extras )"
177           Specifies extra values to pass through to "File::File::find" as
178           part of the options hash.
179
180           For example this allows you to specify following of symlinks like
181           so:
182
183            my $rule = File::Find::Object::Rule->extras({ follow => 1 });
184
185           May be invoked many times per rule, but only the most recent value
186           is used.
187
188       "relative"
189           Trim the leading portion of any path found
190
191       "not_*"
192           Negated version of the rule.  An effective shortand related to ! in
193           the procedural interface.
194
195            $foo->not_name('*.pl');
196
197            $foo->not( $foo->new->name('*.pl' ) );
198
199   Query Methods
200       "in( @directories )"
201           Evaluates the rule, returns a list of paths to matching files and
202           directories.
203
204       "start( @directories )"
205           Starts a find across the specified directories.  Matching items may
206           then be queried using "match".  This allows you to use a rule as an
207           iterator.
208
209            my $rule = File::Find::Object::Rule->file->name("*.jpeg")->start( "/web" );
210            while ( my $image = $rule->match ) {
211                ...
212            }
213
214       "match"
215           Returns the next file which matches, false if there are no more.
216
217   Extensions
218       Extension modules are available from CPAN in the
219       File::Find::Object::Rule namespace.  In order to use these extensions
220       either use them directly:
221
222        use File::Find::Object::Rule::ImageSize;
223        use File::Find::Object::Rule::MMagic;
224
225        # now your rules can use the clauses supplied by the ImageSize and
226        # MMagic extension
227
228       or, specify that File::Find::Object::Rule should load them for you:
229
230        use File::Find::Object::Rule qw( :ImageSize :MMagic );
231
232       For notes on implementing your own extensions, consult
233       File::Find::Object::Rule::Extending
234
235   Further examples
236       Finding perl scripts
237            my $finder = File::Find::Object::Rule->or
238             (
239              File::Find::Object::Rule->name( '*.pl' ),
240              File::Find::Object::Rule->exec(
241                                     sub {
242                                         if (open my $fh, $_) {
243                                             my $shebang = <$fh>;
244                                             close $fh;
245                                             return $shebang =~ /^#!.*\bperl/;
246                                         }
247                                         return 0;
248                                     } ),
249             );
250
251           Based upon this message
252           http://use.perl.org/comments.pl?sid=7052&cid=10842
253
254       ignore CVS directories
255            my $rule = File::Find::Object::Rule->new;
256            $rule->or($rule->new
257                           ->directory
258                           ->name('CVS')
259                           ->prune
260                           ->discard,
261                      $rule->new);
262
263           Note here the use of a null rule.  Null rules match anything they
264           see, so the effect is to match (and discard) directories called
265           'CVS' or to match anything.
266

TWO FOR THE PRICE OF ONE

268       File::Find::Object::Rule also gives you a procedural interface.  This
269       is documented in File::Find::Object::Rule::Procedural
270

EXPORTS

272   find
273   rule

Tests

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

BUGS

397       The code relies on qr// compiled regexes, therefore this module
398       requires perl version 5.005_03 or newer.
399
400       Currently it isn't possible to remove a clause from a rule object.  If
401       this becomes a significant issue it will be addressed.
402

AUTHOR

404       Richard Clamp <richardc@unixbeard.net> with input gained from this
405       use.perl discussion: http://use.perl.org/~richardc/journal/6467
406
407       Additional proofreading and input provided by Kake, Greg McCarroll, and
408       Andy Lester andy@petdance.com.
409
410       Ported to use File::Find::Object as File::Find::Object::Rule by Shlomi
411       Fish.
412

COPYRIGHT

414       Copyright (C) 2002, 2003, 2004, 2006 Richard Clamp.  All Rights
415       Reserved.
416
417       This module is free software; you can redistribute it and/or modify it
418       under the same terms as Perl itself.
419

KNOWN BUGS

432       The tests don't run successfully when directly inside an old Subversion
433       checkout, due to the presence of ".svn" directories. "./Build disttest"
434       or "./Build distruntest" run fine.
435

AUTHORS

437       ·   Richard Clamp <richardc@unixbeard.net> with input gained from this
438
439       ·   and Andy Lester andy@petdance.com.
440

COPYRIGHT AND LICENSE

442       This software is copyright (c) 2018 by Richard Clampwith input gained
443       from this.
444
445       This is free software; you can redistribute it and/or modify it under
446       the same terms as the Perl 5 programming language system itself.
447

BUGS

449       Please report any bugs or feature requests on the bugtracker website
450       <https://github.com/shlomif/file-find-object-rule/issues>
451
452       When submitting a bug or request, please include a test-file or a patch
453       to an existing test-file that illustrates the bug or desired feature.
454

SUPPORT

456   Perldoc
457       You can find documentation for this module with the perldoc command.
458
459         perldoc File::Find::Object::Rule
460
461   Websites
462       The following websites have more information about this module, and may
463       be of help to you. As always, in addition to those websites please use
464       your favorite search engine to discover more resources.
465
466       ·   MetaCPAN
467
468           A modern, open-source CPAN search engine, useful to view POD in
469           HTML format.
470
471           <https://metacpan.org/release/File-Find-Object-Rule>
472
473       ·   Search CPAN
474
475           The default CPAN search engine, useful to view POD in HTML format.
476
477           <http://search.cpan.org/dist/File-Find-Object-Rule>
478
479       ·   RT: CPAN's Bug Tracker
480
481           The RT ( Request Tracker ) website is the default bug/issue
482           tracking system for CPAN.
483
484           <https://rt.cpan.org/Public/Dist/Display.html?Name=File-Find-Object-Rule>
485
486       ·   AnnoCPAN
487
488           The AnnoCPAN is a website that allows community annotations of Perl
489           module documentation.
490
491           <http://annocpan.org/dist/File-Find-Object-Rule>
492
493       ·   CPAN Ratings
494
495           The CPAN Ratings is a website that allows community ratings and
496           reviews of Perl modules.
497
498           <http://cpanratings.perl.org/d/File-Find-Object-Rule>
499
500       ·   CPANTS
501
502           The CPANTS is a website that analyzes the Kwalitee ( code metrics )
503           of a distribution.
504
505           <http://cpants.cpanauthors.org/dist/File-Find-Object-Rule>
506
507       ·   CPAN Testers
508
509           The CPAN Testers is a network of smoke testers who run automated
510           tests on uploaded CPAN distributions.
511
512           <http://www.cpantesters.org/distro/F/File-Find-Object-Rule>
513
514       ·   CPAN Testers Matrix
515
516           The CPAN Testers Matrix is a website that provides a visual
517           overview of the test results for a distribution on various
518           Perls/platforms.
519
520           <http://matrix.cpantesters.org/?dist=File-Find-Object-Rule>
521
522       ·   CPAN Testers Dependencies
523
524           The CPAN Testers Dependencies is a website that shows a chart of
525           the test results of all dependencies for a distribution.
526
527           <http://deps.cpantesters.org/?module=File::Find::Object::Rule>
528
529   Bugs / Feature Requests
530       Please report any bugs or feature requests by email to
531       "bug-file-find-object-rule at rt.cpan.org", or through the web
532       interface at
533       <https://rt.cpan.org/Public/Bug/Report.html?Queue=File-Find-Object-Rule>.
534       You will be automatically notified of any progress on the request by
535       the system.
536
537   Source Code
538       The code is open to the world, and available for you to hack on. Please
539       feel free to browse it and play with it, or whatever. If you want to
540       contribute patches, please send me a diff or prod me to pull from your
541       repository :)
542
543       <https://github.com/shlomif/file-find-object-rule>
544
545         git clone http://bitbucket.org/shlomif/perl-file-find-object-rule
546
547
548
549perl v5.28.0                      2018-07-14       File::Find::Object::Rule(3)