Provided by: libfile-find-object-rule-perl_0.0306-1_all bug

NAME

       File::Find::Object::Rule - Alternative interface to File::Find::Object

SYNOPSIS

         use File::Find::Object::Rule;
         # find all the subdirectories of a given directory
         my @subdirs = File::Find::Object::Rule->directory->in( $directory );

         # find all the .pm files in @INC
         my @files = File::Find::Object::Rule->file()
                                     ->name( '*.pm' )
                                     ->in( @INC );

         # as above, but without method chaining
         my $rule =  File::Find::Object::Rule->new;
         $rule->file;
         $rule->name( '*.pm' );
         my @files = $rule->in( @INC );

DESCRIPTION

       File::Find::Object::Rule is a friendlier interface to File::Find::Object .  It allows you
       to build rules which specify the desired files and directories.

       WARNING : This module is a fork of version 0.30 of File::Find::Rule (which has been
       unmaintained for several years as of February, 2009), and may still have some bugs due to
       its reliance on File::Find'isms. As such it is considered Alpha software. Please report
       any problems with File::Find::Object::Rule to its RT CPAN Queue.

METHODS

       "new"
           A constructor.  You need not invoke "new" manually unless you wish to, as each of the
           rule-making methods will auto-create a suitable object if called as class methods.

   finder
       The File::Find::Object finder instance itself.

   my @rules = @{$ffor->rules()};
       The rules to match against. For internal use only.

   Matching Rules
       "name( @patterns )"
           Specifies names that should match.  May be globs or regular expressions.

            $set->name( '*.mp3', '*.ogg' ); # mp3s or oggs
            $set->name( qr/\.(mp3|ogg)$/ ); # the same as a regex
            $set->name( 'foo.bar' );        # just things named foo.bar

       -X tests
           Synonyms are provided for each of the -X tests. See "-X" in perlfunc for details.
           None of these methods take arguments.

             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
              -s  |  nonempty             -l  |  symlink
                  |                       -p  |  fifo
              -u  |  setuid               -S  |  socket
              -g  |  setgid               -b  |  block
              -k  |  sticky               -c  |  character
                  |                       -t  |  tty
              -M  |  modified                 |
              -A  |  accessed             -T  |  ascii
              -C  |  changed              -B  |  binary

           Though some tests are fairly meaningless as binary flags ("modified", "accessed",
           "changed"), they have been included for completeness.

            # find nonempty files
            $rule->file,
                 ->nonempty;

       stat tests
           The following "stat" based methods are provided: "dev", "ino", "mode", "nlink", "uid",
           "gid", "rdev", "size", "atime", "mtime", "ctime", "blksize", and "blocks".  See "stat"
           in perlfunc for details.

           Each of these can take a number of targets, which will follow Number::Compare
           semantics.

            $rule->size( 7 );         # exactly 7
            $rule->size( ">7Ki" );    # larger than 7 * 1024 * 1024 bytes
            $rule->size( ">=7" )
                 ->size( "<=90" );    # between 7 and 90, inclusive
            $rule->size( 7, 9, 42 );  # 7, 9 or 42

       "any( @rules )"
       "or( @rules )"
           Allows shortcircuiting boolean evaluation as an alternative to the default and-like
           nature of combined rules.  "any" and "or" are interchangeable.

            # find avis, movs, things over 200M and empty files
            $rule->any( File::Find::Object::Rule->name( '*.avi', '*.mov' ),
                        File::Find::Object::Rule->size( '>200M' ),
                        File::Find::Object::Rule->file->empty,
                      );

       "none( @rules )"
       "not( @rules )"
           Negates a rule.  (The inverse of "any".)  "none" and "not" are interchangeable.

             # files that aren't 8.3 safe
             $rule->file
                  ->not( $rule->new->name( qr/^[^.]{1,8}(\.[^.]{0,3})?$/ ) );

       "prune"
           Traverse no further.  This rule always matches.

       "discard"
           Don't keep this file.  This rule always matches.

       "exec( \&subroutine( $shortname, $path, $fullname ) )"
           Allows user-defined rules.  Your subroutine will be invoked with parameters of the
           name, the path you're in, and the full relative filename.  In addition, $_ is set to
           the current short name, but its use is discouraged since as opposed to
           File::Find::Rule, File::Find::Object::Rule does not cd to the containing directory.

           Return a true value if your rule matched.

            # get things with long names
            $rules->exec( sub { length > 20 } );

       ->grep( @specifiers );
           Opens a file and tests it each line at a time.

           For each line it evaluates each of the specifiers, stopping at the first successful
           match.  A specifier may be a regular expression or a subroutine.  The subroutine will
           be invoked with the same parameters as an ->exec subroutine.

           It is possible to provide a set of negative specifiers by enclosing them in anonymous
           arrays.  Should a negative specifier match the iteration is aborted and the clause is
           failed.  For example:

            $rule->grep( qr/^#!.*\bperl/, [ sub { 1 } ] );

           Is a passing clause if the first line of a file looks like a perl shebang line.

       "maxdepth( $level )"
           Descend at most $level (a non-negative integer) levels of directories below the
           starting point.

           May be invoked many times per rule, but only the most recent value is used.

       "mindepth( $level )"
           Do not apply any tests at levels less than $level (a non-negative integer).

       "extras( \%extras )"
           Specifies extra values to pass through to "File::File::find" as part of the options
           hash.

           For example this allows you to specify following of symlinks like so:

            my $rule = File::Find::Object::Rule->extras({ follow => 1 });

           May be invoked many times per rule, but only the most recent value is used.

       "relative"
           Trim the leading portion of any path found

       "not_*"
           Negated version of the rule.  An effective shortand related to ! in the procedural
           interface.

            $foo->not_name('*.pl');

            $foo->not( $foo->new->name('*.pl' ) );

   Query Methods
       "in( @directories )"
           Evaluates the rule, returns a list of paths to matching files and directories.

       "start( @directories )"
           Starts a find across the specified directories.  Matching items may then be queried
           using "match".  This allows you to use a rule as an iterator.

            my $rule = File::Find::Object::Rule->file->name("*.jpeg")->start( "/web" );
            while ( my $image = $rule->match ) {
                ...
            }

       "match"
           Returns the next file which matches, false if there are no more.

   Extensions
       Extension modules are available from CPAN in the File::Find::Object::Rule namespace.  In
       order to use these extensions either use them directly:

        use File::Find::Object::Rule::ImageSize;
        use File::Find::Object::Rule::MMagic;

        # now your rules can use the clauses supplied by the ImageSize and
        # MMagic extension

       or, specify that File::Find::Object::Rule should load them for you:

        use File::Find::Object::Rule qw( :ImageSize :MMagic );

       For notes on implementing your own extensions, consult File::Find::Object::Rule::Extending

   Further examples
       Finding perl scripts
            my $finder = File::Find::Object::Rule->or
             (
              File::Find::Object::Rule->name( '*.pl' ),
              File::Find::Object::Rule->exec(
                                     sub {
                                         if (open my $fh, $_) {
                                             my $shebang = <$fh>;
                                             close $fh;
                                             return $shebang =~ /^#!.*\bperl/;
                                         }
                                         return 0;
                                     } ),
             );

           Based upon this message http://use.perl.org/comments.pl?sid=7052&cid=10842

       ignore CVS directories
            my $rule = File::Find::Object::Rule->new;
            $rule->or($rule->new
                           ->directory
                           ->name('CVS')
                           ->prune
                           ->discard,
                      $rule->new);

           Note here the use of a null rule.  Null rules match anything they see, so the effect
           is to match (and discard) directories called 'CVS' or to match anything.

TWO FOR THE PRICE OF ONE

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

EXPORTS

   find
   rule

Tests

   accessed
       Corresponds to "-A".

   ascii
       Corresponds to "-T".

   atime
       See "stat tests".

   binary
       Corresponds to "-b".

   blksize
       See "stat tests".

   block
       Corresponds to "-b".

   blocks
       See "stat tests".

   changed
       Corresponds to "-C".

   character
       Corresponds to "-c".

   ctime
       See "stat tests".

   dev
       See "stat tests".

   directory
       Corresponds to "-d".

   empty
       Corresponds to "-z".

   executable
       Corresponds to "-x".

   exists
       Corresponds to "-e".

   fifo
       Corresponds to "-p".

   file
       Corresponds to "-f".

   gid
       See "stat tests".

   ino
       See "stat tests".

   mode
       See "stat tests".

   modified
       Corresponds to "-M".

   mtime
       See "stat tests".

   nlink
       See "stat tests".

   r_executable
       Corresponds to "-X".

   r_owned
       Corresponds to "-O".

   nonempty
       A predicate that determines if the file is empty. Uses "-s".

   owned
       Corresponds to "-o".

   r_readable
       Corresponds to "-R".

   r_writeable
   r_writable
       Corresponds to "-W".

   rdev
       See "stat tests".

   readable
       Corresponds to "-r".

   setgid
       Corresponds to "-g".

   setuid
       Corresponds to "-u".

   size
       See stat tests.

   socket
       Corresponds to "-S".

   sticky
       Corresponds to "-k".

   symlink
       Corresponds to "-l".

   uid
       See "stat tests".

   tty
       Corresponds to "-t".

   writable()
       Corresponds to "-w".

BUGS

       The code relies on qr// compiled regexes, therefore this module requires perl version
       5.005_03 or newer.

       Currently it isn't possible to remove a clause from a rule object.  If this becomes a
       significant issue it will be addressed.

AUTHOR

       Richard Clamp <richardc@unixbeard.net> with input gained from this use.perl discussion:
       http://use.perl.org/~richardc/journal/6467

       Additional proofreading and input provided by Kake, Greg McCarroll, and Andy Lester
       andy@petdance.com.

       Ported to use File::Find::Object as File::Find::Object::Rule by Shlomi Fish.

COPYRIGHT

       Copyright (C) 2002, 2003, 2004, 2006 Richard Clamp.  All Rights Reserved.

       This module is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.

SEE ALSO

       File::Find::Object, Text::Glob, Number::Compare, find(1)

       If you want to know about the procedural interface, see
       File::Find::Object::Rule::Procedural, and if you have an idea for a neat extension, see
       File::Find::Object::Rule::Extending .

       Path::Class::Rule Xs SEE ALSO contains a review of many directory traversal modules on
       CPAN, including File::Find::Object::Rule and File::Find::Rule (on which this module is
       based).

KNOWN BUGS

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