Unix/Linux Go Back    

CentOS 7.0 - man page for file::find::rule (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)

File::Find::Rule(3)	       User Contributed Perl Documentation	      File::Find::Rule(3)

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

	 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->name( '*.pm' );
	 my @files = $rule->in( @INC );

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

	   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.

   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

       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

	    $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::Rule->name( '*.avi', '*.mov' ),
			File::Find::Rule->size( '>200M' ),

       "none( @rules )"
       "not( @rules )"
	   Negates a rule.  (The inverse of "any".)  "none" and "not" are interchangeable.

	     # files that aren't 8.3 safe
		  ->not( $rule->new->name( qr/^[^.]{1,8}(\.[^.]{0,3})?$/ ) );

	   Traverse no further.  This rule always matches.

	   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, the path you're in, and the full relative

	   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

	   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 is used.

	   Trim the leading portion of any path found

	   Negated version of the rule.  An effective shortand related to ! in the procedural


	    $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::Rule->file->name("*.jpeg")->start( "/web" );
	    while ( defined ( my $image = $rule->match ) ) {

	   Returns the next file which matches, false if there are no more.

       Extension modules are available from CPAN in the File::Find::Rule namespace.  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, consult File::Find::Rule::Extending

   Further examples
       Finding perl scripts
	    my $finder = File::Find::Rule->or
	      File::Find::Rule->name( '*.pl' ),
				     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;

	   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.

       File::Find::Rule also gives you a procedural interface.	This is documented in

       "find", "rule"

       As of 0.32 File::Find::Rule doesn't capture the current working directory in a taint-
       unsafe manner.  File::Find itself still does operations that the taint system will flag as
       insecure but you can use the "extras" feature to ask File::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.

       The code makes use of the "our" keyword and as such requires perl version 5.6.0 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.

       Richard Clamp <richardc@unixbeard.net> with input gained from this use.perl discussion:

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

       Copyright (C) 2002, 2003, 2004, 2006, 2009, 2011 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.

       File::Find, Text::Glob, Number::Compare, find(1)

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

perl v5.16.3				    2011-09-19			      File::Find::Rule(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums

All times are GMT -4. The time now is 04:58 PM.