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.