MAN page from OpenSuSE perl-File-Find-Rule-0.350.0-2.4.noarch.rpm

File::Find::Rule

Section: User Contributed Perl Documentation (3)
Updated: 2025-06-11
Index

NAME

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

SYNOPSIS

  use File::Find::Rule;  # find all the subdirectories of a given directory  my @subdirs = File::Find::Rule->directory->in( $directory );  # find all the .pm files in @INC  my @files = File::Find::Rule->file()                              ->name( '*.pm' )                              ->in( @INC );  # as above, but without method chaining  my $rule =  File::Find::Rule->new;  $rule->file;  $rule->name( '*.pm' );  my @files = $rule->in( @INC );

DESCRIPTION

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

METHODS

"new": A constructor. You need not invoke "new" manually unless you wishto, as each of the rule-making methods will auto-create a suitableobject if called as class methods.

Matching Rules

name( @patterns )

Specifies names that should match. May be globs or regularexpressions.

 $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 fordetails. 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 perlfuncfor details.

Each of these can take a number of targets, which will followNumber::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 thedefault and-like nature of combined rules. "any" and "or" areinterchangeable.

 # find avis, movs, things over 200M and empty files $rule->any( File::Find::Rule->name( '*.avi', '*.mov' ),             File::Find::Rule->size( '>200M' ),             File::Find::Rule->file->empty,           );

none( @rules )

not( @rules )

Negates a rule. (The inverse of "any".) "none" and "not" areinterchangeable.

  # 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 $_set to the current short name, and with parameters of the name, thepath you're in, and the full relative filename.

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 thefirst successful match. A specifier may be a regular expression or asubroutine. The subroutine will be invoked with the same parametersas an ->exec subroutine.

It is possible to provide a set of negative specifiers by enclosingthem in anonymous arrays. Should a negative specifier match theiteration 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 perlshebang line.

maxdepth( $level )

Descend at most $level (a non-negative integer) levels of directoriesbelow the starting point.

May be invoked many times per rule, but only the most recent value isused.

mindepth( $level )

Do not apply any tests at levels less than $level (a non-negativeinteger).

extras( \%extras )

Specifies extra values to pass through to "File::File::find" as partof the options hash.

For example this allows you to specify following of symlinks like so:

 my $rule = File::Find::Rule->extras({ follow => 1 });

May be invoked many times per rule, but only the most recent value isused.

"relative"

Trim the leading portion of any path found

"canonpath"

Normalize paths found using "File::Spec-"canonpath>. This will return pathswith a file-seperator that is native to your OS (as determined by File::Spec),
instead of the default "/".

For example, this will return "tmp/foobar" on Unix-ish OSesand "tmp\foobar" on Win32.

"not_*"

Negated version of the rule. An effective shortand related to ! inthe 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 anddirectories.

start( @directories )

Starts a find across the specified directories. Matching items maythen be queried using "match". This allows you to use a rule as aniterator.

 my $rule = File::Find::Rule->file->name("*.jpeg")->start( "/web" ); while ( defined ( 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::Rulenamespace. In order to use these extensions either use them directly:

 use File::Find::Rule::ImageSize; use File::Find::Rule::MMagic; # now your rules can use the clauses supplied by the ImageSize and # MMagic extension

or, specify that File::Find::Rule should load them for you:

 use File::Find::Rule qw( :ImageSize :MMagic );

For notes on implementing your own extensions, consultFile::Find::Rule::Extending

Further examples

Finding perl scripts

 my $finder = File::Find::Rule->or  (   File::Find::Rule->name( '*.pl' ),   File::Find::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::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 tomatch anything.

TWO FOR THE PRICE OF ONE

File::Find::Rule also gives you a procedural interface. This isdocumented in File::Find::Rule::Procedural

EXPORTS

"find", "rule"

TAINT MODE INTERACTION

As of 0.32 File::Find::Rule doesn't capture the current working directory ina taint-unsafe manner. File::Find itself still does operations that the taintsystem will flag as insecure but you can use the "extras" feature to askFile::Find to internally "untaint" file paths with a regex like so:

    my $rule = File::Find::Rule->extras({ untaint => 1 });

Please consult File::Find's documentation for "untaint","untaint_pattern", and "untaint_skip" for more information.

BUGS

The code makes use of the "our" keyword and as such requires perl version5.6.0 or newer.

Currently it isn't possible to remove a clause from a rule object. Ifthis becomes a significant issue it will be addressed.

AUTHOR

Richard Clamp <richardcAATTunixbeard.net> with input gained from thisuse.perl discussion: http://use.perl.org/~richardc/journal/6467

Additional proofreading and input provided by Kake, Greg McCarroll,and Andy Lester andyAATTpetdance.com.

COPYRIGHT

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

TWO FOR THE PRICE OF ONE

EXPORTS

TAINT MODE INTERACTION

This document was created byman2html,using the manual pages.