finder

my @rules = @{$ffor->rules()};

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

 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.

find

rule

accessed

ascii

atime

binary

blksize

block

blocks

changed

character

ctime

dev

directory

empty

executable

exists

fifo

file

gid

ino

mode

modified

mtime

nlink

r_executable

r_owned

nonempty

owned

r_readable

r_writeable

r_writable

rdev

readable

setgid

setuid

size

socket

sticky

symlink

uid

tty

writable()

Websites

• MetaCPAN

  A modern, open-source CPAN search engine, useful to view POD in HTML format.

  <https://metacpan.org/release/File-Find-Object-Rule>

• RT: CPAN's Bug Tracker

  The RT ( Request Tracker ) website is the default bug/issue tracking system for CPAN.

  <https://rt.cpan.org/Public/Dist/Display.html?Name=File-Find-Object-Rule>

• CPANTS

  The CPANTS is a website that analyzes the Kwalitee ( code metrics ) of a distribution.

  <http://cpants.cpanauthors.org/dist/File-Find-Object-Rule>

• CPAN Testers

  The CPAN Testers is a network of smoke testers who run automated tests on uploaded CPAN distributions.

  <http://www.cpantesters.org/distro/F/File-Find-Object-Rule>

• CPAN Testers Matrix

  The CPAN Testers Matrix is a website that provides a visual overview of the test results for a distribution on various Perls/platforms.

  <http://matrix.cpantesters.org/?dist=File-Find-Object-Rule>

• CPAN Testers Dependencies

  The CPAN Testers Dependencies is a website that shows a chart of the test results of all dependencies for a distribution.

  <http://deps.cpantesters.org/?module=File::Find::Object::Rule>

Bugs / Feature Requests

Source Code

<https://github.com/shlomif/http://bitbucket.org/shlomif/perl-file-find-object-rule>

  git clone git://github.com/shlomif/http://bitbucket.org/shlomif/perl-file-find-object-rule.git