File::Find::Object::Rule - Alternative interface to File::Find::Object
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 );
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.
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.
The File::Find::Object finder instance itself.
The rules to match against. For internal use only.
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
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.
modified
accessed
changed
# find nonempty files $rule->file, ->nonempty;
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.
stat
dev
ino
mode
nlink
uid
gid
rdev
size
atime
mtime
ctime
blksize
blocks
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.
any
or
# 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.
none
not
# 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 } );
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.
$level
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.
File::File::find
For example this allows you to specify following of symlinks like so:
my $rule = File::Find::Object::Rule->extras({ follow => 1 });
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' ) );
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.
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
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
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.
File::Find::Object::Rule also gives you a procedural interface. This is documented in File::Find::Object::Rule::Procedural
Corresponds to -A.
-A
Corresponds to -T.
-T
See "stat tests".
Corresponds to -b.
-b
Corresponds to -C.
-C
Corresponds to -c.
-c
Corresponds to -d.
-d
Corresponds to -z.
-z
Corresponds to -x.
-x
Corresponds to -e.
-e
Corresponds to -p.
-p
Corresponds to -f.
-f
Corresponds to -M.
-M
Corresponds to -X.
-X
Corresponds to -O.
-O
A predicate that determines if the file is empty. Uses -s.
-s
Corresponds to -o.
-o
Corresponds to -R.
-R
Corresponds to -W.
-W
Corresponds to -r.
-r
Corresponds to -g.
-g
Corresponds to -u.
-u
See stat tests.
Corresponds to -S.
-S
Corresponds to -k.
-k
Corresponds to -l.
-l
Corresponds to -t.
-t
Corresponds to -w.
-w
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.
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 (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.
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 ’s 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).
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.
.svn
./Build disttest
./Build distruntest
To install File::Find::Object::Rule, copy and paste the appropriate command in to your terminal.
cpanm
cpanm File::Find::Object::Rule
CPAN shell
perl -MCPAN -e shell install File::Find::Object::Rule
For more information on module installation, please visit the detailed CPAN module installation guide.