File::Find::Object::Rule(3)

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.