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:

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.

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:

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.

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

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

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

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.

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.

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

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.

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

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 three values:

A true value -- indicates the constraint is satisfied

A false value -- indicates the constraint is not satisfied

"0 but true" -- a special return value that signals that a directory should not be searched recursively

The 0 but true value will shortcut logic (it is treated as "true" for an "or" rule and "false" for an "and" rule). For a directory, it ensures that the directory will not be returned from the iterator and that its children will not be evaluated either. It has no effect on files -- it is equivalent to returning a false value.

For example, this is equivalent to the "max_depth" rule method with a depth of 3:

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":

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:

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.

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.

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.

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.