/ 
File-Find-Rule-0.04
River stage four • 284 direct dependents • 1870 total dependents
/ File::Find::Rule

NAME

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

SYNOPSIS

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

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

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

# all those arrows - circle the wagons! (the procedural interface)
my @files = find(file => name => '*.pm', in => \@INC);

DESCRIPTION

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

Procedural interface

find( @clauses )
rule( @clauses )

find and rule can be used to invoke any methods available to the OO version. rule is a synonym for find

Passing more than one value to a clause is done with an anonymous array:

my $finder = find( name => [ '*.mp3', '*.ogg' ] );

Returns an object, unless one of the arguments is in, in which case it returns a list of things that match the rule.

my @files = find( name => [ '*.mp3', '*.ogg' ], in => $ENV{HOME} );

Please note that in will be the last clause evaluated, and so this code will search for mp3s regardless of size.

my @files = find( name => '*.mp3', in => $ENV{HOME}, size => '<2k' );
                                                   ^
                                                   |
              Clause processing stopped here ------/

It is also possible to invert a single rule by prefixing it with ! like so:

# large files that aren't videos
my @files = find( file    =>
                  '!name' => [ '*.avi', '*.mov' ],
                  size    => '>20M',
                  in      => $ENV{HOME} );

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.

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 target value, which may be relative.

$rule->size( 7 );         # exactly 7
$rule->size( ">7" );      # greater than 7
$rule->size( ">=7" )
     ->size( "<=90" );    # between 7 and 90, inclusive
$rule->size( 7, 9, 42 );  # 7, 9 or 42

This value may also use magnitudes of kilobytes (k, ki), megabytes (m, mi), or gigabytes (g, gi). Those suffixed with an i use the appropriate 2**n version in accordance with the IEC standard: http://physics.nist.gov/cuu/Units/binary.html

$rule->size( '>200M'  ); # larger than 200,000,000 bytes
$rule->size( '>200Mi' ); # larger than 209,715,200 bytse
$rule->size( '<=200k' ); # 200,000 bytes or fewer
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( find( name => [ '*.avi', '*.mov' ] ),
            find( size => '>200M' ),
            find( 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}(\.[^.]{,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 $_ set to the current short name, and with parameters of the name, the path you're in, and the full relative filename.

Return a true value if your rule matched.

# get things with long names
$rules->exec( sub { length > 20 } );
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).

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

Query Methods

test( $shortname, $path, $fullname )

Invoked in the same way as callbacks invoked for "exec" rules.

Returns true or undef if the rule matches (undef indicates that although the rule was succesful, a discard clause fired)

my $rule = File::Find::Rule->name( '*.mp3' );
print $rule->test( 'foo.ogg' ) ? "matches\n" : "no match\n";
                                      # prints "no match";
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 = find( file => name => "*.jpeg", start => "/web" );
while ( my $image = $rule->match ) {
    ...
}
match

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

Further examples

Finding perl scripts
my $finder = File::Find::Rule->or
 (
  File::Find::Rule->name( '*.pl' ),
  File::Find::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::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.

Another way to express this would be

rule( not => rule( directory => name 'CVS', => prune => ) )

Though this is entirely a stylistic choice dependant on how complex your rule needs to be.

EXPORTS

"find", "rule"

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.

COPYRIGHT

Copyright (C) 2002 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, find(1)