Constructors

  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

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

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

File name rules

  $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

   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

  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

  $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

  $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

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

Custom rule subroutines

  $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

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

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.

Bugs / Feature Requests

Source Code

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

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