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

- NAME
- 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

Back to Top

# NAME

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

Back to Top

# 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 );

Back to Top

# DESCRIPTION

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

WARNING : This module is a fork of version 0.30 of the File::Find::Rule manpage (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 the File::Find::Object::Rule manpage to its RT CPAN Queue.

Back to Top

# 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 the File::Find::Object manpage 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 the perlfunc manpage 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 the perlfunc manpage for details.

  Each of these can take a number of targets, which will follow the Number::Compare manpage 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 the File::Find::Object::Rule::Extending manpage

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

Back to Top

# TWO FOR THE PRICE OF ONE

File::Find::Object::Rule also gives you a procedural interface. This is documented in the File::Find::Object::Rule::Procedural manpage

Back to Top

# EXPORTS

## find

## rule

Back to Top

# 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`.

Back to Top

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

Back to Top

# 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 the File::Find::Object manpage as File::Find::Object::Rule by Shlomi Fish.

Back to Top

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

Back to Top

# SEE ALSO

the File::Find::Object manpage, the Text::Glob manpage, the Number::Compare manpage, `find(1)`

If you want to know about the procedural interface, see the File::Find::Object::Rule::Procedural manpage, and if you have an idea for a neat extension, see the File::Find::Object::Rule::Extending manpage .

the Path::Class::Rule manpage ’s SEE ALSO contains a review of many directory traversal modules on CPAN, including the File::Find::Object::Rule manpage and the File::Find::Rule manpage (on which this module is based).

Back to Top

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

Back to Top

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