Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
File::Finder::Steps(3)User Contributed Perl DocumentatioFile::Finder::Steps(3)

NAME
       File::Finder::Steps - steps for File::Finder

SYNOPSIS
	 ## See	File::Finder for normal	use of steps

	 ## subclassing	example:
	 BEGIN {
	   package My::File::Finder;
	   use base File::Finder;

	   sub _steps_class { "My::File::Finder::Steps"	}
	 }
	 BEGIN {
	   package My::File::Finder::Steps;
	   use base File::Finder::Steps;

	   sub bigger_than { # true if bigger than N bytes
	     my	$self =	shift;
	     my	$bytes = shift;
	     return sub	{
	       -s > $bytes;
	     }
	   }
	 }

	 my $over_1k = My::File::Finder->bigger_than(1024);
	 print "Temp files over	1k:\n";
	 $over_1k->ls->in("/tmp");

DESCRIPTION
       "File::Finder::Steps" provide the predicates being tested for
       "File::Finder".

   STEPS METHODS
       These methods are called	on a class or instance to add a	"step".	 Each
       step adds itself	to a list of steps, returning the new object.  This
       allows you to chain steps together to form a formula.

       As in find, the default operator	is "and", and short-circuiting is
       performed.

       or  Like	find's "or".

       left
	   Like	a left parenthesis.  Used in nesting pairs with	"right".

       right
	   Like	a right	parenthesis.  Used in nesting pairs with "left".  For
	   example:

	     my	$big_or_old = File::Finder
	       ->type('f')
	       ->left
		 ->size("+100")->or->mtime("+90")
	       ->right;
	     find($big_or_old->ls, "/tmp");

	   You need parens because the "or" operator is	lower precedence than
	   the implied "and", for the same reason you need them	here:

	     find /tmp -type f '(' -size +100 -o -mtime	+90 ')'	-print

	   Without the parens, the -type would bind to -size, and not to the
	   choice of -size or -mtime.

	   Mismatched parens will not be found until the formula is used,
	   causing a fatal error.

       begin
	   Alias for "left".

       end Alias for "right".

       not Like	find's "!".  Prefix operator, can be placed in front of
	   individual terms or open parens.  Can be nested, but	what's the
	   point?

	     # list all	non-files in /tmp
	     File::Finder->not->type('f')->ls->in("/tmp");

       true
	   Always returns true.	 Useful	when a subexpression might fail, but
	   you don't want the overall code to fail:

	     ... ->left-> ...[might return false]... ->or->true->right-> ...

	   Of course, this is the find command's idiom of:

	      find ....	'(' .... -o -true ')' ...

       false
	   Always returns false.

       comma
	   Like	GNU find's ",".	 The result of the expression (or
	   subexpression if in parens) up to this point	is discarded, and
	   execution continues afresh.	Useful when a part of the expression
	   is needed for its side effects, but shouldn't affect	the rest of
	   the "and"-ed	chain.

	     # list all	files and dirs,	but don't descend into CVS dir contents:
	     File::Finder->type('d')->name('CVS')->prune->comma->ls->in('.');

       follow
	   Enables symlink following, and returns true.

       name(NAME)
	   True	if basename matches NAME, which	can be given as	a glob pattern
	   or a	regular	expression object:

	     my	$pm_files = File::Finder->name('*.pm')->in('.');
	     my	$pm_files_too =	File::Finder->name(qr/pm$/)->in('.');

       perm(PERMISSION)
	   Like	find's "-perm".	 Leading "-" means "all	of these bits".
	   Leading "+" means "any of these bits".  Value is de-octalized if a
	   leading 0 is	present, which is likely only if it's being passed as
	   a string.

	     my	$files = File::Finder->type('f');
	     # find files that are exactly mode	644
	     my	$files_644 = $files->perm(0644);
	     # find files that are at least world executable:
	     my	$files_world_exec = $files->perm("-1");
	     # find files that have some executable bit	set:
	     my	$files_exec = $files->perm("+0111");

       type(TYPE)
	   Like	find's "-type".	 All native Perl types are supported.  Note
	   that	"s" is a socket, mapping to Perl's "-S", to be consistent with
	   find.  Returns true or false, as appropriate.

       print
	   Prints the fullname to "STDOUT", followed by	a newline.  Returns
	   true.

       print0
	   Prints the fullname to "STDOUT", followed by	a NUL.	Returns	true.

       fstype
	   Not implemented yet.

       user(USERNAME|UID)
	   True	if the owner is	USERNAME or UID.

       group(GROUPNAME|GID)
	   True	if the group is	GROUPNAME or GID.

       nouser
	   True	if the entry doesn't belong to any known user.

       nogroup
	   True	if the entry doesn't belong to any known group.

       links( +/- N )
	   Like	find's "-links N".  Leading plus means "more than", minus
	   means "less than".

       inum( +/- N )
	   True	if the inode number meets the qualification.

       size( +/- N [c/k])
	   True	if the file size meets the qualification.  By default, N is in
	   half-K blocks.  Append a trailing "k" to the	number to indicate 1K
	   blocks, or "c" to indicate characters (bytes).

       atime( +/- N )
	   True	if access time (in days) meets the qualification.

       mtime( +/- N )
	   True	if modification	time (in days) meets the qualification.

       ctime( +/- N )
	   True	if inode change	time (in days) meets the qualification.

       exec(@COMMAND)
	   Forks the child process via "system()".  Any	appearance of "{}" in
	   any argument	is replaced by the current filename.  Returns true if
	   the child exit status is 0.	The list is passed directly to
	   "system", so	if it's	a single arg, it can contain "/bin/sh" syntax.
	   Otherwise, it's a pre-parsed	command	that must be found on the
	   PATH.

	   Note	that I couldn't	figure out how to horse	around with the
	   current directory very well,	so I'm using $_	here instead of	the
	   more	traditional "File::Find::name".	 It still works, because we're
	   still chdir'ed down into the	directory, but it looks	weird on a
	   trace.  Trigger "no_chdir" in "find"	if you want a traditional find
	   full	path.

	     my	$f = File::Finder->exec('ls', '-ldg', '{}');
	     find({ no_chdir =>	1, wanted => $f	}, @starting_dirs);

	   Yeah, it'd be trivial for me	to add a no_chdir method.  Soon.

       ok(@COMMAND)
	   Like	"exec",	but displays the command line first, and waits for a
	   response.  If the response begins with "y" or "Y", runs the
	   command.  If	the command fails, or the response wasn't yes, returns
	   false, otherwise true.

       prune
	   Sets	$File::Find::prune, and	returns	true.

       xdev
	   Not yet implemented.

       newer
	   Not yet implemented.

       eval(CODEREF)
	   Ah yes, the master escape, with extra benefits.  Give it a coderef,
	   and it evaluates that code at the proper time.  The return value is
	   noted for true/false	and used accordingly.

	     my	$blaster = File::Finder->atime("+30")->eval(sub	{ unlink });

	   But wait, there's more.  If the parameter is	an object that
	   responds to "as_wanted", that method	is automatically called,
	   hoping for a	coderef	return.	This neat feature allows subroutines
	   to be created and nested:

	     my	$old = File::Finder->atime("+30");
	     my	$big = File::Finder->size("+100");
	     my	$old_or_big = File::Finder->eval($old)->or->eval($big);
	     my	$killer	= File::Finder->eval(sub { unlink });
	     my	$kill_old_or_big = File::Finder->eval($old_or_big)->ls->eval($killer);
	     $kill_old_or_big->in('/tmp');

	   Almost too cool for words.

       depth
	   Like	find's "-depth".  Sets a flag for "as_options",	and returns
	   true.

       ls  Like	find's "-ls".  Performs	a "ls -dils" on	the entry to "STDOUT"
	   (without forking), and returns true.

       tar Not yet implemented.

       [n]cpio
	   Not yet implemented.

       ffr($ffr_object)
	   Incorporate a "File::Find::Rule" object as a	step. Note that	this
	   must	be a rule object, and not a result, so don't call or pass
	   "in".  For example, using "File::Find::Rule::ImageSize" to define a
	   predicate for image files that are bigger than a megapixel in my
	   friends folder, I get:

	     require File::Finder;
	     require File::Find::Rule;
	     require File::Find::Rule::ImageSize;
	     my	$ffr = File::Find::Rule->file->image_x('>1000')->image_y('>1000');
	     my	@big_friends = File::Finder->ffr($ffr)
	       ->in("/Users/merlyn/Pictures/Sorted/Friends");

       contains(pattern)
	   True	if the file contains "pattern" (either a literal string
	   treated as a	regex, or a true regex object).

	     my	$plugh_files = File::Finder->type('f')->contains(qr/plugh/);

	   Searching is	performed on a line-by-line basis, respecting the
	   current value of $/.

   EXTENDING
       A step consists of a compile-time and a run-time	component.

       During the creation of a	"File::Finder" object, step methods are	called
       as if they were methods against the slowly-growing "File::Finder"
       instance, including any additional parameters as	in a normal method
       call.  The step is expected to return a coderef (possibly a closure) to
       be executed at run-time.

       When a "File::Finder" object is being evaluated as the "File::Find"
       "wanted"	routine, the collected coderefs	are evaluated in sequence,
       again as	method calls against the "File::Finder"	object.	 No additional
       parameters are passed.  However,	the normal "wanted" values are
       available, such as $_, $File::Find::name, and so	on.  The "_" pseudo-
       handle has been set properly, so	you can	safely use "-X"	filetests and
       "stat" against the pseudo-handle.  The routine is expected to return a
       true/false value, which becomes the value of the	step.

       Although	a "File::Finder" object	is passed both to the compile-time
       invocation and the resulting run-time invocation, only the "options"
       self-hash element is properly duplicated	through	the cloning process.
       Do not be tempted to add	additional self-hash elements without
       overriding "File::Finder"'s "_clone".  Instead, pass values from	the
       compile-time phase to the run-time phase	using closure variables, as
       shown in	the synopsis.

       For simplicity, you can also just mix-in	your methods to	the existing
       "File::Finder::Steps" class, rather than	subclassing both classes as
       shown above.  However, this may result in conflicting implementations
       of a given step name, so	beware.

SEE ALSO
       File::Finder

BUGS
       None known yet.

AUTHOR
       Randal L. Schwartz, <merlyn@stonehenge.com>

COPYRIGHT AND LICENSE
       Copyright (C) 2003,2004 by Randal L. Schwartz, Stonehenge Consulting
       Services, Inc.

       This library is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself, either Perl	version	5.8.2 or, at
       your option, any	later version of Perl 5	you may	have available.

perl v5.32.1			  2005-04-08		File::Finder::Steps(3)

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | BUGS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=File::Finder::Steps&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help