.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "File::Finder::Steps 3"
.TH File::Finder::Steps 3 2024-07-13 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
File::Finder::Steps \- steps for File::Finder
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&  ## 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:\en";
\&  $over_1k\->ls\->in("/tmp");
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\f(CW\*(C`File::Finder::Steps\*(C'\fR provide the predicates being tested for
\&\f(CW\*(C`File::Finder\*(C'\fR.
.SS "STEPS METHODS"
.IX Subsection "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.
.PP
As in \fIfind\fR, the default operator is "and", and short-circuiting is
performed.
.IP or 4
.IX Item "or"
Like \fIfind\fR's \f(CW\*(C`or\*(C'\fR.
.IP left 4
.IX Item "left"
Like a left parenthesis.  Used in nesting pairs with \f(CW\*(C`right\*(C'\fR.
.IP right 4
.IX Item "right"
Like a right parenthesis.  Used in nesting pairs with \f(CW\*(C`left\*(C'\fR.
For example:
.Sp
.Vb 6
\&  my $big_or_old = File::Finder
\&    \->type(\*(Aqf\*(Aq)
\&    \->left
\&      \->size("+100")\->or\->mtime("+90")
\&    \->right;
\&  find($big_or_old\->ls, "/tmp");
.Ve
.Sp
You need parens because the "or" operator is lower precedence than
the implied "and", for the same reason you need them here:
.Sp
.Vb 1
\&  find /tmp \-type f \*(Aq(\*(Aq \-size +100 \-o \-mtime +90 \*(Aq)\*(Aq \-print
.Ve
.Sp
Without the parens, the \-type would bind to \-size, and not to the
choice of \-size or \-mtime.
.Sp
Mismatched parens will not be found until the formula is used, causing
a fatal error.
.IP begin 4
.IX Item "begin"
Alias for \f(CW\*(C`left\*(C'\fR.
.IP end 4
.IX Item "end"
Alias for \f(CW\*(C`right\*(C'\fR.
.IP not 4
.IX Item "not"
Like \fIfind\fR's \f(CW\*(C`!\*(C'\fR.  Prefix operator, can be placed in front of
individual terms or open parens.  Can be nested, but what's the point?
.Sp
.Vb 2
\&  # list all non\-files in /tmp
\&  File::Finder\->not\->type(\*(Aqf\*(Aq)\->ls\->in("/tmp");
.Ve
.IP true 4
.IX Item "true"
Always returns true.  Useful when a subexpression might fail, but
you don't want the overall code to fail:
.Sp
.Vb 1
\&  ... \->left\-> ...[might return false]... \->or\->true\->right\-> ...
.Ve
.Sp
Of course, this is the \fIfind\fR command's idiom of:
.Sp
.Vb 1
\&   find .... \*(Aq(\*(Aq .... \-o \-true \*(Aq)\*(Aq ...
.Ve
.IP false 4
.IX Item "false"
Always returns false.
.IP comma 4
.IX Item "comma"
Like GNU \fIfind\fR'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.
.Sp
.Vb 2
\&  # list all files and dirs, but don\*(Aqt descend into CVS dir contents:
\&  File::Finder\->type(\*(Aqd\*(Aq)\->name(\*(AqCVS\*(Aq)\->prune\->comma\->ls\->in(\*(Aq.\*(Aq);
.Ve
.IP follow 4
.IX Item "follow"
Enables symlink following, and returns true.
.IP name(NAME) 4
.IX Item "name(NAME)"
True if basename matches NAME, which can be given as a glob
pattern or a regular expression object:
.Sp
.Vb 2
\&  my $pm_files = File::Finder\->name(\*(Aq*.pm\*(Aq)\->in(\*(Aq.\*(Aq);
\&  my $pm_files_too = File::Finder\->name(qr/pm$/)\->in(\*(Aq.\*(Aq);
.Ve
.IP perm(PERMISSION) 4
.IX Item "perm(PERMISSION)"
Like \fIfind\fR's \f(CW\*(C`\-perm\*(C'\fR.  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.
.Sp
.Vb 7
\&  my $files = File::Finder\->type(\*(Aqf\*(Aq);
\&  # 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");
.Ve
.IP type(TYPE) 4
.IX Item "type(TYPE)"
Like \fIfind\fR's \f(CW\*(C`\-type\*(C'\fR.  All native Perl types are supported.  Note
that \f(CW\*(C`s\*(C'\fR is a socket, mapping to Perl's \f(CW\*(C`\-S\*(C'\fR, to be consistent with
\&\fIfind\fR.  Returns true or false, as appropriate.
.IP print 4
.IX Item "print"
Prints the fullname to \f(CW\*(C`STDOUT\*(C'\fR, followed by a newline.  Returns true.
.IP print0 4
.IX Item "print0"
Prints the fullname to \f(CW\*(C`STDOUT\*(C'\fR, followed by a NUL.  Returns true.
.IP fstype 4
.IX Item "fstype"
Not implemented yet.
.IP user(USERNAME|UID) 4
.IX Item "user(USERNAME|UID)"
True if the owner is USERNAME or UID.
.IP group(GROUPNAME|GID) 4
.IX Item "group(GROUPNAME|GID)"
True if the group is GROUPNAME or GID.
.IP nouser 4
.IX Item "nouser"
True if the entry doesn't belong to any known user.
.IP nogroup 4
.IX Item "nogroup"
True if the entry doesn't belong to any known group.
.IP "links( +/\- N )" 4
.IX Item "links( +/- N )"
Like \fIfind\fR's \f(CW\*(C`\-links N\*(C'\fR.  Leading plus means "more than", minus
means "less than".
.IP "inum( +/\- N )" 4
.IX Item "inum( +/- N )"
True if the inode number meets the qualification.
.IP "size( +/\- N [c/k])" 4
.IX Item "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).
.IP "atime( +/\- N )" 4
.IX Item "atime( +/- N )"
True if access time (in days) meets the qualification.
.IP "mtime( +/\- N )" 4
.IX Item "mtime( +/- N )"
True if modification time (in days) meets the qualification.
.IP "ctime( +/\- N )" 4
.IX Item "ctime( +/- N )"
True if inode change time (in days) meets the qualification.
.IP exec(@COMMAND) 4
.IX Item "exec(@COMMAND)"
Forks the child process via \f(CWsystem()\fR.  Any appearance of \f(CW\*(C`{}\*(C'\fR in
any argument is replaced by the current filename.  Returns true if the
child exit status is 0.  The list is passed directly to \f(CW\*(C`system\*(C'\fR,
so if it's a single arg, it can contain \f(CW\*(C`/bin/sh\*(C'\fR syntax.  Otherwise,
it's a pre-parsed command that must be found on the PATH.
.Sp
Note that I couldn't figure out how to horse around with the current
directory very well, so I'm using \f(CW$_\fR here instead of the more
traditional \f(CW\*(C`File::Find::name\*(C'\fR.  It still works, because we're still
chdir'ed down into the directory, but it looks weird on a trace.
Trigger \f(CW\*(C`no_chdir\*(C'\fR in \f(CW\*(C`find\*(C'\fR if you want a traditional \fIfind\fR full
path.
.Sp
.Vb 2
\&  my $f = File::Finder\->exec(\*(Aqls\*(Aq, \*(Aq\-ldg\*(Aq, \*(Aq{}\*(Aq);
\&  find({ no_chdir => 1, wanted => $f }, @starting_dirs);
.Ve
.Sp
Yeah, it'd be trivial for me to add a no_chdir method.  Soon.
.IP ok(@COMMAND) 4
.IX Item "ok(@COMMAND)"
Like \f(CW\*(C`exec\*(C'\fR, but displays the command line first, and waits for a
response.  If the response begins with \f(CW\*(C`y\*(C'\fR or \f(CW\*(C`Y\*(C'\fR, runs the command.
If the command fails, or the response wasn't yes, returns false,
otherwise true.
.IP prune 4
.IX Item "prune"
Sets \f(CW$File::Find::prune\fR, and returns true.
.IP xdev 4
.IX Item "xdev"
Not yet implemented.
.IP newer 4
.IX Item "newer"
Not yet implemented.
.IP eval(CODEREF) 4
.IX Item "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.
.Sp
.Vb 1
\&  my $blaster = File::Finder\->atime("+30")\->eval(sub { unlink });
.Ve
.Sp
But wait, there's more.  If the parameter is an object that responds
to \f(CW\*(C`as_wanted\*(C'\fR, that method is automatically called, hoping for a
coderef return. This neat feature allows subroutines to be created and
nested:
.Sp
.Vb 6
\&  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(\*(Aq/tmp\*(Aq);
.Ve
.Sp
Almost too cool for words.
.IP depth 4
.IX Item "depth"
Like \fIfind\fR's \f(CW\*(C`\-depth\*(C'\fR.  Sets a flag for \f(CW\*(C`as_options\*(C'\fR, and returns true.
.IP ls 4
.IX Item "ls"
Like \fIfind\fR's \f(CW\*(C`\-ls\*(C'\fR.  Performs a \f(CW\*(C`ls \-dils\*(C'\fR on the entry to
\&\f(CW\*(C`STDOUT\*(C'\fR (without forking), and returns true.
.IP tar 4
.IX Item "tar"
Not yet implemented.
.IP [n]cpio 4
.IX Item "[n]cpio"
Not yet implemented.
.IP ffr($ffr_object) 4
.IX Item "ffr($ffr_object)"
Incorporate a \f(CW\*(C`File::Find::Rule\*(C'\fR object as a step. Note that this
must be a rule object, and not a result, so don't call or pass \f(CW\*(C`in\*(C'\fR.
For example, using \f(CW\*(C`File::Find::Rule::ImageSize\*(C'\fR to define a
predicate for image files that are bigger than a megapixel in my
friends folder, I get:
.Sp
.Vb 6
\&  require File::Finder;
\&  require File::Find::Rule;
\&  require File::Find::Rule::ImageSize;
\&  my $ffr = File::Find::Rule\->file\->image_x(\*(Aq>1000\*(Aq)\->image_y(\*(Aq>1000\*(Aq);
\&  my @big_friends = File::Finder\->ffr($ffr)
\&    \->in("/Users/merlyn/Pictures/Sorted/Friends");
.Ve
.IP contains(pattern) 4
.IX Item "contains(pattern)"
True if the file contains \f(CW\*(C`pattern\*(C'\fR (either a literal string
treated as a regex, or a true regex object).
.Sp
.Vb 1
\&  my $plugh_files = File::Finder\->type(\*(Aqf\*(Aq)\->contains(qr/plugh/);
.Ve
.Sp
Searching is performed on a line-by-line basis, respecting the
current value of \f(CW$/\fR.
.SS EXTENDING
.IX Subsection "EXTENDING"
A step consists of a compile-time and a run-time component.
.PP
During the creation of a \f(CW\*(C`File::Finder\*(C'\fR object, step methods are
called as if they were methods against the slowly-growing
\&\f(CW\*(C`File::Finder\*(C'\fR 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.
.PP
When a \f(CW\*(C`File::Finder\*(C'\fR object is being evaluated as the \f(CW\*(C`File::Find\*(C'\fR
\&\f(CW\*(C`wanted\*(C'\fR routine, the collected coderefs are evaluated in sequence,
again as method calls against the \f(CW\*(C`File::Finder\*(C'\fR object.  No
additional parameters are passed.  However, the normal \f(CW\*(C`wanted\*(C'\fR
values are available, such as \f(CW$_\fR, \f(CW$File::Find::name\fR, and so on.
The \f(CW\*(C`_\*(C'\fR pseudo-handle has been set properly, so you can safely
use \f(CW\*(C`\-X\*(C'\fR filetests and \f(CW\*(C`stat\*(C'\fR against the pseudo-handle.
The routine is expected to return a true/false value, which becomes
the value of the step.
.PP
Although a \f(CW\*(C`File::Finder\*(C'\fR object is passed both to the compile-time
invocation and the resulting run-time invocation, only the \f(CW\*(C`options\*(C'\fR
self-hash element is properly duplicated through the cloning process.
Do not be tempted to add additional self-hash elements without
overriding \f(CW\*(C`File::Finder\*(C'\fR's \f(CW\*(C`_clone\*(C'\fR.  Instead, pass values from the
compile-time phase to the run-time phase using closure variables, as
shown in the synopsis.
.PP
For simplicity, you can also just mix-in your methods to the existing
\&\f(CW\*(C`File::Finder::Steps\*(C'\fR class, rather than subclassing both classes as
shown above.  However, this may result in conflicting implementations
of a given step name, so beware.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
File::Finder
.SH BUGS
.IX Header "BUGS"
None known yet.
.SH AUTHOR
.IX Header "AUTHOR"
Randal L. Schwartz, <merlyn@stonehenge.com>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2003,2004 by Randal L. Schwartz,
Stonehenge Consulting Services, Inc.
.PP
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.