NAME
    Path::Class::Rule - File finder using Path::Class

VERSION
    version 0.001

SYNOPSIS
      use Path::Class::Rule;

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

      # iterator interface
      my $next = $rule->iter( @dirs );
      while ( 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::Class::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

    *   returns Path::Class objects

    *   custom rules implemented with callbacks

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

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

    *   doesn't chdir during operation

    *   provides an API for extensions

USAGE
  Constructors
   "new"
      my $rule = Path::Class::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 hat matches any file or
    directory.

   "clone"
      my $common      = Path::Class::Rule->new->file->not_empty;
      my $big_files   = $common->clone->size(">1MB");
      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 ( my $file = $next->() ) {
        ...
      }

    Creates a subroutine reference iterator that returns a single
    Path::Class object 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.

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

    Following symlinks may result in files be returned more than once;
    turning it off requires overhead of a stat call. Set this appropriate to
    your needs.

    Note: each directory path will only be entered once. Due to symlinks,
    this could mean a physical directory is entered more than once.

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

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

    Returns a list of Path::Class objects 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.

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

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

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

    A rule subroutine gets a Path::Class argument (which is also locally
    aliased into the $_ global variable). It 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.

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

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

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

    The "skip_dirs" method skips directories that match or 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.

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

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

  Negated rules
    All 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").

EXTENDING
    One of the strengths of File::Find::Rule is the many CPAN modules that
    extend it. "Path::Class::Rule" provides the "add_helper" method to
    provide a similar mechanism for extensions.

  "add_helper"
    The "add_helper" method takes two arguments, a "name" for the rule
    method and a closure-generating callback. 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::Class::Rule::Foo;

      use Path::Class::Rule;

      Path::Class::Rule->add_helper(
        foo => sub {
          my @args = @_; # do this to customize closure with arguments
          return sub {
            my ($item) = shift;
            return $item->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.

CAVEATS
    This is an early release for community feedback and contribution. The
    API may still change. Some features are still unimplemented:

    *   True loop detection

    *   Taint mode support

    *   Error handling callback

    *   Depth limitations

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

    *   Extension class loading via "import()"

    Test coverage is still poor.

    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 one's preferences and needs.
    Here is an (incomplete) list of alternatives, with some comparison
    commentary.

  File::Find
    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
    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
    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
    varaibles.

  Path::Class::Iterator
    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::Declare
    File::Find::Declare has declarative helper rules, no iterator, is
    Moose-based and offers no control over ordering or following symlinks.

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

SUPPORT
  Bugs / Feature Requests
    Please report any bugs or feature requests by email to
    "bug-path-class-rule at rt.cpan.org", or through the web interface at
    <http://rt.cpan.org/Public/Dist/Display.html?Name=Path-Class-Rule>. You
    will be automatically notified of any progress on the request by the
    system.

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

    <http://github.com/dagolden/path-class-rule>

      git clone http://github.com/dagolden/path-class-rule

AUTHOR
    David Golden <dagolden@cpan.org>

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

    This is free software, licensed under:

      The Apache License, Version 2.0, January 2004

