File: README

package info (click to toggle)
libpath-iterator-rule-perl 1.015-2
  • links: PTS, VCS
  • area: main
  • in suites: bookworm, sid, trixie
  • size: 416 kB
  • sloc: perl: 819; makefile: 2; sh: 1
file content (758 lines) | stat: -rw-r--r-- 28,058 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
NAME
    Path::Iterator::Rule - Iterative, recursive file finder

VERSION
    version 1.015

SYNOPSIS
      use Path::Iterator::Rule;

      my $rule = Path::Iterator::Rule->new; # match anything
      $rule->file->size(">10k");         # add/chain rules

      # iterator interface
      my $next = $rule->iter( @dirs );
      while ( defined( my $file = $next->() ) ) {
        ...
      }

      # list interface
      for my $file ( $rule->all( @dirs ) ) {
        ...
      }

DESCRIPTION
    This module iterates over files and directories to identify ones
    matching a user-defined set of rules. The API is based heavily on
    File::Find::Rule, but with more explicit distinction between matching
    rules and options that influence how directories are searched. A
    "Path::Iterator::Rule" object is a collection of rules (match criteria)
    with methods to add additional criteria. Options that control directory
    traversal are given as arguments to the method that generates an
    iterator.

    Here is a summary of features for comparison to other file finding
    modules:

    *   provides many "helper" methods for specifying rules

    *   offers (lazy) iterator and flattened list interfaces

    *   custom rules implemented with callbacks

    *   breadth-first (default) or pre- or post-order depth-first searching

    *   follows symlinks (by default, but can be disabled)

    *   directories visited only once (no infinite loop; can be disabled)

    *   doesn't chdir during operation

    *   provides an API for extensions

    As a convenience, the PIR module is an empty subclass of this one that
    is less arduous to type for one-liners.

    Note: paths are constructed with unix-style forward-slashes for
    efficiency rather than using File::Spec. If proper path separators are
    needed, call canonpath on the search results.

USAGE
  Constructors
   "new"
      my $rule = Path::Iterator::Rule->new;

    Creates a new rule object that matches any file or directory. It takes
    no arguments. For convenience, it may also be called on an object, in
    which case it still returns a new object that matches any file or
    directory.

   "clone"
      my $common      = Path::Iterator::Rule->new->file->not_empty;
      my $big_files   = $common->clone->size(">1M");
      my $small_files = $common->clone->size("<10K");

    Creates a copy of a rule object. Useful for customizing different rule
    objects against a common base.

  Matching and iteration
   "iter"
      my $next = $rule->iter( @dirs, \%options);
      while ( defined( my $file = $next->() ) ) {
        ...
      }

    Creates a subroutine reference iterator that returns a single result
    when dereferenced. This iterator is "lazy" -- results are not
    pre-computed.

    It takes as arguments a list of directories to search and an optional
    hash reference of control options. If no search directories are
    provided, the current directory is used ("."). Valid options include:

    *   "depthfirst" -- Controls order of results. Valid values are "1"
        (post-order, depth-first search), "0" (breadth-first search) or "-1"
        (pre-order, depth-first search). Default is 0.

    *   "error_handler" -- Catches errors during execution of rule tests.
        Default handler dies with the filename and error. If set to undef,
        error handling is disabled.

    *   "follow_symlinks" -- Follow directory symlinks when true. Default is
        1.

    *   "report_symlinks" -- Includes symlinks in results when true. Default
        is equal to "follow_symlinks".

    *   "loop_safe" -- Prevents visiting the same directory more than once
        when true. Default is 1.

    *   "relative" -- Return matching items relative to the search
        directory. Default is 0.

    *   "sorted" -- Whether entries in a directory are sorted before
        processing. Default is 1.

    *   "visitor" -- An optional coderef that will be called on items
        matching all rules.

    Filesystem loops might exist from either hard or soft links. The
    "loop_safe" option prevents infinite loops, but adds some overhead by
    making "stat" calls. Because directories are visited only once when
    "loop_safe" is true, matches could come from a symlinked directory
    before the real directory depending on the search order.

    To get only the real files, turn off "follow_symlinks". You can have
    symlinks included in results, but not descend into symlink directories
    if you turn off "follow_symlinks", but turn on "report_symlinks".

    Turning "loop_safe" off and leaving "follow_symlinks" on avoids "stat"
    calls and will be fastest, but with the risk of an infinite loop and
    repeated files. The default is slow, but safe.

    The "error_handler" parameter must be a subroutine reference. It will be
    called when a rule test throws an exception. The first argument will be
    the file name being inspected and the second argument will be the
    exception.

    The optional "visitor" parameter must be a subroutine reference. If set,
    it will be called for any result that matches. It is called the same way
    a custom rule would be (see "EXTENDING") but its return value is
    ignored. It is called when an item is first inspected -- "postorder" is
    not respected.

    The paths inspected and returned will be relative to the search
    directories provided. If these are absolute, then the paths returned
    will have absolute paths. If these are relative, then the paths returned
    will have relative paths.

    If the search directories are absolute and the "relative" option is
    true, files returned will be relative to the search directory. Note that
    if the search directories are not mutually exclusive (whether containing
    subdirectories like @INC or symbolic links), files found could be
    returned relative to different initial search directories based on
    "depthfirst", "follow_symlinks" or "loop_safe".

    When the iterator is exhausted, it will return undef.

   "iter_fast"
    This works just like "iter", except that it optimizes for speed over
    safety. Don't do this unless you're sure you need it and accept the
    consequences. See "PERFORMANCE" for details.

   "all"
      my @matches = $rule->all( @dir, \%options );

    Returns a list of paths that match the rule. It takes the same arguments
    and has the same behaviors as the "iter" method. The "all" method uses
    "iter" internally to fetch all results.

    In scalar context, it will return the count of matched paths.

    In void context, it is optimized to iterate over everything, but not
    store results. This is most useful with the "visitor" option:

        $rule->all( $path, { visitor => \&callback } );

   "all_fast"
    This works just like "all", except that it optimizes for speed over
    safety. Don't do this unless you're sure you need it and accept the
    consequences. See "PERFORMANCE" for details.

   "test"
      if ( $rule->test( $path, $basename, $stash ) ) { ... }

    Test a file path against a rule. Used internally, but provided should
    someone want to create their own, custom iteration algorithm.

  Logic operations
    "Path::Iterator::Rule" provides three logic operations for adding rules
    to the object. Rules may be either a subroutine reference with specific
    semantics (described below in "EXTENDING") or another
    "Path::Iterator::Rule" object.

   "and"
      $rule->and( sub { -r -w -x $_ } ); # stacked filetest example
      $rule->and( @more_rules );

    Adds one or more constraints to the current rule. E.g. "old rule AND
    new1 AND new2 AND ...". Returns the object to allow method chaining.

   "or"
      $rule->or(
        $rule->new->name("foo*"),
        $rule->new->name("bar*"),
        sub { -r -w -x $_ },
      );

    Takes one or more alternatives and adds them as a constraint to the
    current rule. E.g. "old rule AND ( new1 OR new2 OR ... )". Returns the
    object to allow method chaining.

   "not"
      $rule->not( sub { -r -w -x $_ } );

    Takes one or more alternatives and adds them as a negative constraint to
    the current rule. E.g. "old rule AND NOT ( new1 AND new2 AND ...)".
    Returns the object to allow method chaining.

   "skip"
      $rule->skip(
        $rule->new->dir->not_writeable,
        $rule->new->dir->name("foo"),
      );

    Takes one or more alternatives and will prune a directory if any of the
    criteria match or if any of the rules already indicate the directory
    should be pruned. Pruning means the directory will not be returned by
    the iterator and will not be searched.

    For files, it is equivalent to "$rule->not($rule->or(@rules))". Returns
    the object to allow method chaining.

    This method should be called as early as possible in the rule chain. See
    "skip_dirs" below for further explanation and an example.

RULE METHODS
    Rule methods are helpers that add constraints. Internally, they generate
    a closure to accomplish the desired logic and add it to the rule object
    with the "and" method. Rule methods return the object to allow for
    method chaining.

  File name rules
   "name"
      $rule->name( "foo.txt" );
      $rule->name( qr/foo/, "bar.*");

    The "name" method takes one or more patterns and creates a rule that is
    true if any of the patterns match the basename of the file or directory
    path. Patterns may be regular expressions or glob expressions (or
    literal names).

   "iname"
      $rule->iname( "foo.txt" );
      $rule->iname( qr/foo/, "bar.*");

    The "iname" method is just like the "name" method, but matches
    case-insensitively.

   "skip_dirs"
      $rule->skip_dirs( @patterns );

    The "skip_dirs" method skips directories that match one or more
    patterns. Patterns may be regular expressions or globs (just like
    "name"). Directories that match will not be returned from the iterator
    and will be excluded from further search. This includes the starting
    directories. If that isn't what you want, see "skip_subdirs" instead.

    Note: this rule should be specified early so that it has a chance to
    operate before a logical shortcut. E.g.

      $rule->skip_dirs(".git")->file; # OK
      $rule->file->skip_dirs(".git"); # Won't work

    In the latter case, when a ".git" directory is seen, the "file" rule
    shortcuts the rule before the "skip_dirs" rule has a chance to act.

   "skip_subdirs"
      $rule->skip_subdirs( @patterns );

    This works just like "skip_dirs", except that the starting directories
    (depth 0) are not skipped and may be returned from the iterator unless
    excluded by other rules.

  File test rules
    Most of the "-X" style filetest are available as boolean rules. The
    table below maps the filetest to its corresponding method name.

       Test | Method               Test |  Method
      ------|-------------        ------|----------------
        -r  |  readable             -R  |  r_readable
        -w  |  writeable            -W  |  r_writeable
        -w  |  writable             -W  |  r_writable
        -x  |  executable           -X  |  r_executable
        -o  |  owned                -O  |  r_owned
            |                           |
        -e  |  exists               -f  |  file
        -z  |  empty                -d  |  directory, dir
        -s  |  nonempty             -l  |  symlink
            |                       -p  |  fifo
        -u  |  setuid               -S  |  socket
        -g  |  setgid               -b  |  block
        -k  |  sticky               -c  |  character
            |                       -t  |  tty
        -T  |  ascii
        -B  |  binary

    For example:

      $rule->file->nonempty; # -f -s $file

    The -X operators for timestamps take a single argument in a form that
    Number::Compare can interpret.

       Test | Method
      ------|-------------
        -A  |  accessed
        -M  |  modified
        -C  |  changed

    For example:

      $rule->modified(">1"); # -M $file > 1

  Stat test rules
    All of the "stat" elements have a method that takes a single argument in
    a form understood by Number::Compare.

      stat()  |  Method
     --------------------
           0  |  dev
           1  |  ino
           2  |  mode
           3  |  nlink
           4  |  uid
           5  |  gid
           6  |  rdev
           7  |  size
           8  |  atime
           9  |  mtime
          10  |  ctime
          11  |  blksize
          12  |  blocks

    For example:

      $rule->size(">10K")

  Depth rules
      $rule->min_depth(3);
      $rule->max_depth(5);

    The "min_depth" and "max_depth" rule methods take a single argument and
    limit the paths returned to a minimum or maximum depth (respectively)
    from the starting search directory. A depth of 0 means the starting
    directory itself. A depth of 1 means its children. (This is similar to
    the Unix "find" utility.)

  Perl file rules
      # All perl rules
      $rule->perl_file;

      # Individual perl file rules
      $rule->perl_module;     # .pm files
      $rule->perl_pod;        # .pod files
      $rule->perl_test;       # .t files
      $rule->perl_installer;  # Makefile.PL or Build.PL
      $rule->perl_script;     # .pl or 'perl' in the shebang

    These rule methods match file names (or a shebang line) that are typical
    of Perl distribution files.

  Version control file rules
      # Skip all known VCS files
      $rule->skip_vcs;

      # Skip individual VCS files
      $rule->skip_cvs;
      $rule->skip_rcs;
      $rule->skip_svn;
      $rule->skip_git;
      $rule->skip_bzr;
      $rule->skip_hg;
      $rule->skip_darcs;

    Skips files and/or prunes directories related to a version control
    system. Just like "skip_dirs", these rules should be specified early to
    get the correct behavior.

  File content rules
   "contents_match"
      $rule->contents_match(qr/BEGIN .* END/xs);

    The "contents_match" rule takes a list of regular expressions and
    returns files that match one of the expressions.

    The expressions are applied to the file's contents as a single string.
    For large files, this is likely to take significant time and memory.

    Files are assumed to be encoded in UTF-8, but alternative Perl IO layers
    can be passed as the first argument:

      $rule->contents_match(":encoding(iso-8859-1)", qr/BEGIN .* END/xs);

    See perlio for further details.

   "line_match"
      $rule->line_match(qr/^new/i, qr/^Addition/);

    The "line_match" rule takes a list of regular expressions and returns
    files with at least one line that matches one of the expressions.

    Files are assumed to be encoded in UTF-8, but alternative Perl IO layers
    can be passed as the first argument.

   "shebang"
      $rule->shebang(qr/#!.*\bperl\b/);

    The "shebang" rule takes a list of regular expressions or glob patterns
    and checks them against the first line of a file.

  Other rules
   "dangling"
      $rule->symlink->dangling;
      $rule->not_dangling;

    The "dangling" rule method matches dangling symlinks. Use it or its
    inverse to control how dangling symlinks should be treated.

  Negated rules
    Most rule methods have a negated form preceded by "not_".

      $rule->not_name("foo.*")

    Because this happens automatically, it includes somewhat silly ones like
    "not_nonempty" (which is thus a less efficient way of saying "empty").

    Rules that skip directories or version control files do not have a
    negated version.

EXTENDING
  Custom rule subroutines
    Rules are implemented as (usually anonymous) subroutine callbacks that
    return a value indicating whether or not the rule matches. These
    callbacks are called with three arguments. The first argument is a path,
    which is also locally aliased as the $_ global variable for convenience
    in simple tests.

      $rule->and( sub { -r -w -x $_ } ); # tests $_

    The second argument is the basename of the path, which is useful for
    certain types of name checks:

      $rule->and( sub { $_[1] =~ /foo|bar/ } ); "foo" or "bar" in basename;

    The third argument is a hash reference that can be used to maintain
    state. Keys beginning with an underscore are reserved for
    "Path::Iterator::Rule" to provide additional data about the search in
    progress. For example, the "_depth" key is used to support minimum and
    maximum depth checks.

    The custom rule subroutine must return one of four values:

    *   A true value -- indicates the constraint is satisfied

    *   A false value -- indicates the constraint is not satisfied

    *   "\1" -- indicate the constraint is satisfied, and prune if it's a
        directory

    *   "\0" -- indicate the constraint is not satisfied, and prune if it's
        a directory

    A reference is a special flag that signals that a directory should not
    be searched recursively, regardless of whether the directory should be
    returned by the iterator or not.

    The legacy "0 but true" value used previously for pruning is no longer
    valid and will throw an exception if it is detected.

    Here is an example. This is equivalent to the "max_depth" rule method
    with a depth of 3:

      $rule->and(
        sub {
          my ($path, $basename, $stash) = @_;
          return 1 if $stash->{_depth} < 3;
          return \1 if $stash->{_depth} == 3;
          return \0; # should never get here
        }
      );

    Files and directories and directories up to depth 3 will be returned and
    directories will be searched. Files of depth 3 will be returned.
    Directories of depth 3 will be returned, but their contents will not be
    added to the search.

    Returning a reference is "sticky" -- they will propagate through "and"
    and "or" logic.

        0 && \0 = \0    \0 && 0 = \0    0 || \0 = \0    \0 || 0 = \0
        0 && \1 = \0    \0 && 1 = \0    0 || \1 = \1    \0 || 1 = \1
        1 && \0 = \0    \1 && 0 = \0    1 || \0 = \1    \1 || 0 = \1
        1 && \1 = \1    \1 && 1 = \1    1 || \1 = \1    \1 || 1 = \1

    Once a directory is flagged to be pruned, it will be pruned regardless
    of subsequent rules.

        $rule->max_depth(3)->name(qr/foo/);

    This will return files or directories with "foo" in the name, but all
    directories at depth 3 will be pruned, regardless of whether they match
    the name rule.

    Generally, if you want to do directory pruning, you are encouraged to
    use the "skip" method instead of writing your own logic using "\0" and
    "\1".

  Extension modules and custom rule methods
    One of the strengths of File::Find::Rule is the many CPAN modules that
    extend it. "Path::Iterator::Rule" provides the "add_helper" method to
    provide a similar mechanism for extensions.

    The "add_helper" class method takes three arguments, a "name" for the
    rule method, a closure-generating callback, and a flag for not
    generating a negated form of the rule. Unless the flag is true, an
    inverted "not_*" method is generated automatically. Extension classes
    should call this as a class method to install new rule methods. For
    example, this adds a "foo" method that checks if the filename is "foo":

      package Path::Iterator::Rule::Foo;

      use Path::Iterator::Rule;

      Path::Iterator::Rule->add_helper(
        foo => sub {
          my @args = @_; # do this to customize closure with arguments
          return sub {
            my ($item, $basename) = @_;
            return if -d "$item";
            return $basename =~ /^foo$/;
          }
        }
      );

      1;

    This allows the following rule methods:

      $rule->foo;
      $fule->not_foo;

    The "add_helper" method will warn and ignore a helper with the same name
    as an existing method.

  Subclassing
    Instead of processing and returning strings, this module may be
    subclassed to operate on objects that represent files. Such objects must
    stringify to a file path.

    The following private implementation methods must be overridden:

    *   _objectify -- given a path, return an object

    *   _children -- given a directory, return an (unsorted) list of [
        basename, full path ] entries within it, excluding "." and ".."

    Note that "_children" should return a *list* of *tuples*, where the
    tuples are array references containing basename and full path.

    See Path::Class::Rule source for an example.

LEXICAL WARNINGS
    If you run with lexical warnings enabled, "Path::Iterator::Rule" will
    issue warnings in certain circumstances (such as an unreadable directory
    that must be skipped). To disable these categories, put the following
    statement at the correct scope:

      no warnings 'Path::Iterator::Rule';

PERFORMANCE
    By default, "Path::Iterator::Rule" iterator options are "slow but safe".
    They ensure uniqueness, return files in sorted order, and throw nice
    error messages if something goes wrong.

    If you want speed over safety, set these options:

        %options = (
            loop_safe => 0,
            sorted => 0,
            depthfirst => -1,
            error_handler => undef
        );

    Alternatively, use the "iter_fast" and "all_fast" methods instead, which
    set these options for you.

        $iter = $rule->iter( @dirs, \%options );

        $iter = $rule->iter_fast( @dirs ); # same thing

    Depending on the file structure being searched, "depthfirst => -1" may
    or may not be a good choice. If you have lots of nested directories and
    all the files at the bottom, a depth first search might do less work or
    use less memory, particularly if the search will be halted early (e.g.
    finding the first N matches.)

    Rules will shortcut on failure, so be sure to put rules likely to fail
    early in a rule chain.

    Consider:

        $r1 = Path::Iterator::Rule->new->name(qr/foo/)->file;
        $r2 = Path::Iterator::Rule->new->file->name(qr/foo/);

    If there are lots of files, but only a few containing "foo", then $r1
    above will be faster.

    Rules are implemented as code references, so long chains have some
    overhead. Consider testing with a custom coderef that combines several
    tests into one.

    Consider:

        $r3 = Path::Iterator::Rule->new->and( sub { -x -w -r $_ } );
        $r4 = Path::Iterator::Rule->new->executable->writeable->readable;

    Rule $r3 above will be much faster, not only because it stacks the file
    tests, but because it requires only a single code reference.

CAVEATS
    Some features are still unimplemented:

    *   Untainting options

    *   Some File::Find::Rule helpers (e.g. "grep")

    *   Extension class loading via "import()"

    Filetest operators and stat rules are subject to the usual portability
    considerations. See perlport for details.

SEE ALSO
    There are many other file finding modules out there. They all have
    various features/deficiencies, depending on your preferences and needs.
    Here is an (incomplete) list of alternatives, with some comparison
    commentary.

    Path::Class::Rule and IO::All::Rule are subclasses of
    "Path::Iterator::Rule" and operate on Path::Class and IO::All objects,
    respectively. Because of this, they are substantially slower on large
    directory trees than just using this module directly.

    File::Find is part of the Perl core. It requires the user to write a
    callback function to process each node of the search. Callbacks must use
    global variables to determine the current node. It only supports
    depth-first search (both pre- and post-order). It supports pre- and
    post-processing callbacks; the former is required for sorting files to
    process in a directory. File::Find::Closures can be used to help create
    a callback for File::Find.

    File::Find::Rule is an object-oriented wrapper around File::Find. It
    provides a number of helper functions and there are many more
    "File::Find::Rule::*" modules on CPAN with additional helpers. It
    provides an iterator interface, but precomputes all the results.

    File::Next provides iterators for file, directories or "everything". It
    takes two callbacks, one to match files and one to decide which
    directories to descend. It does not allow control over breadth/depth
    order, though it does provide means to sort files for processing within
    a directory. Like File::Find, it requires callbacks to use global
    variables.

    Path::Class::Iterator walks a directory structure with an iterator. It
    is implemented as Path::Class subclasses, which adds a degree of extra
    complexity. It takes a single callback to define "interesting" paths to
    return. The callback gets a Path::Class::Iterator::File or
    Path::Class::Iterator::Dir object for evaluation.

    File::Find::Object and companion File::Find::Object::Rule are like
    File::Find and File::Find::Rule, but without File::Find inside. They use
    an iterator that does not precompute results. They can return
    File::Find::Object::Result objects, which give a subset of the utility
    of Path::Class objects. File::Find::Object::Rule appears to be a literal
    translation of File::Find::Rule, including oddities like making "-M"
    into a boolean.

    File::chdir::WalkDir recursively descends a tree, calling a callback on
    each file. No iterator. Supports exclusion patterns. Depth-first
    post-order by default, but offers pre-order option. Does not process
    symlinks.

    File::Find::Iterator is based on iterator patterns in Higher Order Perl.
    It allows a filtering callback. Symlinks are followed automatically
    without infinite loop protection. No control over order. It offers a
    "state file" option for resuming interrupted work.

    File::Find::Declare has declarative helper rules, no iterator, is
    Moose-based and offers no control over ordering or following symlinks.

    File::Find::Node has no iterator, does matching via callback and offers
    no control over ordering.

    File::Set builds up a set of files to operate on from a list of
    directories to include or exclude, with control over recursion. A
    callback is applied to each file (or directory) in the set. There is no
    iterator. There is no control over ordering. Symlinks are not followed.
    It has several extra features for checksumming the set and creating
    tarballs with /bin/tar.

THANKS
    Thank you to Ricardo Signes (rjbs) for inspiring me to write yet another
    file finder module, for writing file finder optimization benchmarks, and
    tirelessly running my code over and over to see if it got faster.

    *   See the speed of Perl file finders
        <http://rjbs.manxome.org/rubric/entry/1981>

SUPPORT
  Bugs / Feature Requests
    Please report any bugs or feature requests through the issue tracker at
    <https://github.com/dagolden/Path-Iterator-Rule/issues>. You will be
    notified automatically of any progress on your issue.

  Source Code
    This is open source software. The code repository is available for
    public review and contribution under the terms of the license.

    <https://github.com/dagolden/Path-Iterator-Rule>

      git clone https://github.com/dagolden/Path-Iterator-Rule.git

AUTHOR
    David Golden <dagolden@cpan.org>

CONTRIBUTORS
    *   David Steinbrunner <dsteinbrunner@pobox.com>

    *   Diab Jerius <djerius@cfa.harvard.edu>

    *   Edward Betts <edward@4angle.com>

    *   Gian Piero Carrubba <gpiero@butterfly.fdc.rm-rf.it>

    *   Graham Knop <haarg@cpan.org>

    *   Ricardo Signes <rjbs@cpan.org>

    *   Slaven Rezic <slaven.rezic@idealo.de>

    *   Toby Inkster <tobyink@cpan.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2013 by David Golden.

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004