File::...::Steps(3pm)

🌸 File::...::Steps(3pm) 🌸

okay bestie, buckle UP, we're doing the File::...::Steps(3pm) page together and it's a long one so hydrate first 💖

---

✨ NAME ✨

File::Finder::Steps — the steps for File::Finder. it's giving backstage crew for the main character, fr fr 👑

---

🦋 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");

like yes you can absolutely just subclass it, look at her go 💅

---

🌈 DESCRIPTION 🌈

so File::Finder::Steps is the whole vibe — it provides the predicates being tested for File::Finder. that's the entire job. she holds the little true/false checkers and hands them over. no notes. ✨

---

🎀 STEPS METHODS 🎀

these methods get called on a class or an instance to add a step. each step adds itself to a list of steps and returns the new object, which means you can chain them together into one big gorgeous formula 🫶

just like in find, the default operator is and, and short-circuiting is performed. so it bails early when it already knows the answer, efficient queen 💅

heads up bestie: the user, nouser, group, nogroup, and ls methods are not available on Win32 systems. not me being excluded from the party 😭

• or — like find's or. the "either/or" of the situation 💜
• 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 — same reason you need them right 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. messy. we don't do messy. 🙈

and listen — mismatched parens will not be found until the formula is used, which causes a fatal error. so like, count your parens, bestie, this is not the moment for chaos 💀

• begin — alias for left. ✨
• end — alias for right. ✨
• not — like find's !. it's a prefix operator, so you can place it in front of individual terms or open parens. can be nested, but honestly what's the point? 😭

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

• true — always returns true. so useful when a subexpression might fail, but you don't want the overall code to fail:

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

and of course this is just the find command's idiom of:

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

• false — always returns false. the hater of the group 🥀
• 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. chef's kiss for 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. she's a follower but like, in a helpful way 🦋
• name(NAME) — true if the 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. a leading - means "all of these bits". a leading + means "any of these bits". the 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. icon behavior 🌟
• 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. she's coming, she's just not here 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. orphan energy 💀
• nogroup — true if the entry doesn't belong to any known group. orphan energy, the sequel 💀
• 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. 🔥

and ngl, the author's own words: "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);

and yeah, "it'd be trivial for me to add a no_chdir method. Soon." — the author said it, not me, I'm just the messenger 💅

• ok(@COMMAND) — like exec, but it displays the command line first, and waits for a response. if the response begins with y or Y, it runs the command. if the command fails, or the response wasn't yes, returns false, otherwise true. consent-based execution, we love to see it 🎀
• prune — sets $File::Find::prune, and returns true. ✂️
• xdev — not yet implemented. soon bestie 🦋
• newer — not yet implemented. soon bestie 🦋
• 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." — the author's exact words and honestly? correct. 😭✨

• 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 $/. respect the input record separator, she's doing her best 🌸

---

🧚 EXTENDING 🧚

a step consists of a compile-time and a run-time component. two eras. two vibes. one step. ✨

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. i'm serious bestie, don't do it 💀

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. choose your chaos wisely 🙈

---

👑 SEE ALSO 👑

File::Finder

---

💀 BUGS 💀

none known yet. she's flawless (allegedly) ✨

---

🎀 AUTHOR 🎀

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

✨ COPYRIGHT AND LICENSE ✨

okay bestie, legal era 💅 this is the part nobody reads but everybody gotta have, so let's make it cute.

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

that's the vibe. two years, one legend, one consulting company, all the credit. 🎀

---

this library is free software, fr fr 🦋 — you can redistribute it and/or modify it under the same terms as Perl itself. and by "same terms as Perl itself" it means:

• Perl version 5.8.2, or
• at your option, any later version of Perl 5 you happen to have available 💖

so like, pick your fighter. either the classic 5.8.2 energy, or literally any newer Perl 5 you've got chilling on your machine. your call, no pressure, the choice is yours and that's iconic. 👑

no cap: "at your option" means you decide, not whoever handed you the code. read it again if you gotta. that's the whole point. 🫶

---

and that's the whole license section. short, sweet, legally binding, slay. ⭐

<div align="center">🌸 🧚 💜 🎀 🌈 💅 🍓 ✨ 🦋 👑 🔥 💖 </div>

so yeah, that wraps the whole page — written by Randal L. Schwartz and friends back in the day, shipped as part of the Perl 5.40.1 distribution, with the doc dated 2025-10-27. go forth and use it responsibly, bestie. mwah. 💋

thanks for reading the whole thing, you're literally the main character for that 🫶