Provided by: libfile-find-object-rule-perl_0.0313-1_all 
NAME
File::Find::Object::Rule - Alternative interface to File::Find::Object
VERSION
version 0.0313
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.
SUPPORT
Websites
The following websites have more information about this module, and may be of help to you.
As always, in addition to those websites please use your favorite search engine to
discover more resources.
• 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
Please report any bugs or feature requests by email to "bug-file-find-object-rule at
rt.cpan.org", or through the web interface at
<https://rt.cpan.org/Public/Bug/Report.html?Queue=File-Find-Object-Rule>. You will be
automatically notified of any progress on the request by the system.
Source Code
The code is open to the world, and available for you to hack on. Please feel free to
browse it and play with it, or whatever. If you want to contribute patches, please send me
a diff or prod me to pull from your repository :)
<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
AUTHORS
• Richard Clamp <richardc@unixbeard.net>
• Andy Lester andy@petdance.com.
BUGS
Please report any bugs or feature requests on the bugtracker website
<https://github.com/shlomif/http://bitbucket.org/shlomif/perl-file-find-object-rule/issues>
When submitting a bug or request, please include a test-file or a patch to an existing
test-file that illustrates the bug or desired feature.
COPYRIGHT AND LICENSE
This software is copyright (c) 2021 by Richard Clamp.
This is free software; you can redistribute it and/or modify it under the same terms as
the Perl 5 programming language system itself.