Pod::Find(3)

💖 Pod::Find — find POD documents in directory trees ✨

okay bestie, welcome to Pod::Find(3) 💅 this little icon lives in the User Contributed Perl Documentation corner of the universe, and she's here to help you hunt down POD files like it's a scavenger hunt in the group chat 🎀

---

🌸 SYNOPSIS 🌸

use Pod::Find qw(pod_find simplify_name);
my %pods = pod_find({ -verbose => 1, -inc => 1 });
foreach(keys %pods) {
   print "found library POD `$pods{$_}' in $_\n";
}

print "podname=",simplify_name('a/b/c/mymodule.pod'),"\n";

$location = pod_where( { -inc => 1 }, "Pod::Find" );

that's the whole vibe right there, no cap 💫

---

🦋 DESCRIPTION 🦋

⚠️ NOTE: this module is considered legacy, bestie. modern Perl releases (5.31.1 and higher) are literally going to remove Pod-Parser from core and use Pod::Simple for all things POD. so like… just know that going in 😭

Pod::Find provides a set of functions to locate POD files. note that no function is exported by default — that's on purpose, to avoid pollution of your namespace — so be sure to specify them in the use statement if you need them:

use Pod::Find qw(pod_find);

from this version on, the typical SCM (software configuration management) directories are ignored. these are: RCS, CVS, SCCS, .svn, .hg, .git, .sync — yeah we're not digging through those, we have standards 💅

✨ pod_find( { %opts } , @directories ) ✨

the function pod_find searches for POD documents in a given set of files and/or directories. it returns a hash with the file names as keys and the POD name as value 🫶 the POD name is derived from the file name and its position in the directory tree.

e.g. when searching in $HOME/perl5lib, the file $HOME/perl5lib/MyModule.pm would get the POD name MyModule, whereas $HOME/perl5lib/Myclass/Subclass.pm would be Myclass::Subclass. the name information can be used for POD translators 🌈

only text files containing at least one valid POD command are found. picky? yes. iconic? also yes 👑

a warning is printed if more than one POD file with the same POD name is found, e.g. CPAN.pm in different directories. this usually indicates duplicate occurrences of modules in the @INC search path — so like, a vibe check for your install 💀

🌸 OPTIONS 🌸

the first argument for pod_find may be a hash reference with options. the rest are either directories that are searched recursively or files. the POD names of files are the plain basenames with any Perl-like extension (.pm, .pl, .pod) stripped ✂️

• -verbose => 1 — print progress information while scanning. so you can watch her work 💖
• -perl => 1 — apply Perl-specific heuristics to find the correct PODs. this includes stripping Perl-like extensions, omitting subdirectories that are numeric but do not match the current Perl interpreter's version id, suppressing site_perl as a module hierarchy name etc. big brain energy fr 🧠
• -script => 1 — search for PODs in the current Perl interpreter's installation scriptdir. this is taken from the local Config module 🎀
• -inc => 1 — search for PODs in the current Perl interpreter's @INC paths. this automatically considers paths specified in the "PERL5LIB" environment as this is included in @INC by the Perl interpreter itself ✨

🎀 simplify_name( $str ) 🎀

the function simplify_name is equivalent to basename, but also strips Perl-like extensions (.pm, .pl, .pod) and extensions like .bat, .cmd on Win32 and OS/2, or .com on VMS, respectively 🌟 she's flexible like that.

💜 pod_where( { %opts }, $pod ) 💜

returns the location of a pod document given a search directory and a module (e.g. "File::Find") or script (e.g. "perldoc") name 🔥

options:

• -inc => 1 — search @INC for the pod and also the "scriptdir" defined in the Config module.
• -dirs => [ $dir1, $dir2, ... ] — reference to an array of search directories. these are searched in order before looking in @INC (if -inc). current directory is used if none are specified 📁
• -verbose => 1 — list directories as they are searched 👀

returns the full path of the first occurrence to the file. package names (eg 'A::B') are automatically converted to directory names in the selected directory. (eg on unix 'A::B' is converted to 'A/B'). additionally, .pm, .pl and .pod are appended to the search automatically if required 💫

a subdirectory pod/ is also checked if it exists in any of the given search directories. this ensures that e.g. perlfunc is found 🍓

it is assumed that if a module name is supplied, that that name matches the file name. pods are not opened to check for the 'NAME' entry — no peeking, we trust the filename 🙈

a check is made to make sure that the file that is found does contain some pod documentation — so no catfishing, the file has to actually have the goods 💅

🧚 contains_pod( $file , $verbose ) 🧚

returns true if the supplied filename (not POD module) contains some pod information ⭐ simple as that, she just tells you yes or no.

---

👑 AUTHOR 👑

please report bugs using <http://rt.cpan.org> 🫶

Marek Rouchal <marekr@cpan.org>, heavily borrowing code from Nick Ing-Simmons' PodToHtml.

Tim Jenness <t.jenness@jach.hawaii.edu> provided "pod_where" and "contains_pod" 🌟

Pod::Find is part of the Pod::Parser distribution.

---

🌈 SEE ALSO 🌈

Pod::Parser, Pod::Checker, perldoc

---

and that's the whole page, bestie 🥹💖 this was Pod::Find(3) from the User Contributed Perl Documentation, shipping with perl v5.40.0 on 2024-10-29 — go find some PODs, slay, periodt ✨🦋💅