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".

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

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

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 is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

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.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

VERSION

SYNOPSIS

DESCRIPTION

METHODS

finder

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

Matching Rules

Query Methods

Extensions

Further examples

TWO FOR THE PRICE OF ONE

EXPORTS

find

rule

Tests

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()

BUGS

AUTHOR

COPYRIGHT

SEE ALSO

KNOWN BUGS

SUPPORT

Websites

Bugs / Feature Requests

Source Code

AUTHORS

BUGS

COPYRIGHT AND LICENSE

Module Install Instructions