Wanted(3pm)

💖 Wanted(3pm) — like, the manual page, but make it make sense 💖

okay bestie, gather round, because we're talking about File::Find::Wanted, a lil Perl module from the User Contributed Perl Documentation collection, and honestly? it's giving "why is this not just how things work already." 🎀

---

✨ NAME ✨

File::Find::Wanted — a way more obvious wrapper around File::Find. periodt.

---

🌸 VERSION 🌸

Version 1.00. she's v1.00 and she knows it. 💅

---

🦋 SYNOPSIS 🦋

okay so here's the tea. File::Find is a genuinely great module... except for the tiny detail that it does not actually find anything?? 😭 iconic behaviour honestly.

Its find() function walks a directory tree and calls a callback function. and the callback function is deceptively named wanted, which lowkey implies it should return a boolean saying whether you want the file. bestie. that is NOT how it works. 🙈

so like, most of the time you call find(), you just want to build a list of files. sure, there are other modules that do this for you — most notably Richard Clamp's great File::Find::Rule — but in many cases that's overkill, and you'd have to learn a whole new syntax. no thanks, we're tired. 💀

enter find_wanted. you supply a callback sub and a list of starting directories, and the sub actually should return a boolean saying whether you want the file in your list or not. that's it. that's the whole vibe. ✨

to get a list of all files ending in .jpg:

my @files = find_wanted( sub { -f && /\.jpg$/ }, $dir );

for a list of all directories that are not CVS or .svn:

my @files = find_wanted( sub { -d && !/^(CVS|\.svn)$/ }, $dir ) );

It's easy, direct, and simple. 🫶

---

💜 WHY DO THIS? 💜

the cynical girlies may say "that's just the same as doing this":

my @files;
find( sub { push @files, $File::Find::name if -f && /\.jpg$/ }, $dir );

sure it is! but File::Find::Wanted makes it more obvious, and saves a line of code. that's worth it to me. and I'd like it if find_wanted() made its way into the File::Find distro, but for now, this will do. 🌈

---

🧚 FUNCTIONS 🧚

⭐ find_wanted( &wanted, @directories )

descends through @directories, calling the wanted function as it finds each file. the function returns a list of all the files and directories for which the wanted function returned a true value. no cap. 🔥

this is just a wrapper around File::Find::find(). see File::Find for details on how to modify its behavior. iykyk. 👑

---

👑 COPYRIGHT & LICENSE 👑

Copyright 2005-2012 Andy Lester.

This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License v2.0.

---

💌 and that's the whole page, bestie — this was Wanted(3pm) from perl v5.32.0, dated 2021-01-05. go forth and find_wanted() responsibly. mwah. 💖✨🎀