Pod::Simple::Search(3p) Perl Programmers Reference Guide #
Pod::Simple::Search(3p) Perl Programmers Reference Guide
NNAAMMEE #
Pod::Simple::Search - find POD documents in directory trees
SSYYNNOOPPSSIISS #
use Pod::Simple::Search;
my $name2path = Pod::Simple::Search->new->limit_glob('LWP::*')->survey;
print "Looky see what I found: ",
join(' ', sort keys %$name2path), "\n";
print "LWPUA docs = ",
Pod::Simple::Search->new->find('LWP::UserAgent') || "?",
"\n";
DDEESSCCRRIIPPTTIIOONN #
PPoodd::::SSiimmppllee::::SSeeaarrcchh is a class that you use for running searches for Pod
files. An object of this class has several attributes (mostly options
for controlling search options), and some methods for searching based on
those attributes.
The way to use this class is to make a new object of this class, set any
options, and then call one of the search options (probably "survey" or
"find"). The sections below discuss the syntaxes for doing all that.
CCOONNSSTTRRUUCCTTOORR #
This class provides the one constructor, called "new". It takes no
parameters:
use Pod::Simple::Search;
my $search = Pod::Simple::Search->new;
AACCCCEESSSSOORRSS #
This class defines several methods for setting (and, occasionally,
reading) the contents of an object. With two exceptions (discussed at the
end of this section), these attributes are just for controlling the way
searches are carried out.
Note that each of these return $self when you call them as
"$self->_w_h_a_t_e_v_e_r_(_v_a_l_u_e_)". That's so that you can chain together set-
attribute calls like this:
my $name2path =
Pod::Simple::Search->new
-> inc(0) -> verbose(1) -> callback(\&blab)
->survey(@there);
...which works exactly as if you'd done this:
my $search = Pod::Simple::Search->new;
$search->inc(0);
$search->verbose(1);
$search->callback(\&blab);
my $name2path = $search->survey(@there);
$search->inc( _t_r_u_e_-_o_r_-_f_a_l_s_e );
This attribute, if set to a true value, means that searches should
implicitly add perl's _@_I_N_C paths. This automatically considers paths
specified in the "PERL5LIB" environment as this is prepended to _@_I_N_C
by the Perl interpreter itself. This attribute's default value is
TTRRUUEE. If you want to search only specific directories, set
$self->iinncc(0) before calling $inc->survey or $inc->find.
$search->verbose( _n_o_n_n_e_g_a_t_i_v_e_-_n_u_m_b_e_r );
This attribute, if set to a nonzero positive value, will make
searches output (via "warn") notes about what they're doing as they
do it. This option may be useful for debugging a pod-related module.
This attribute's default value is zero, meaning that no "warn"
messages are produced. (Setting verbose to 1 turns on some messages,
and setting it to 2 turns on even more messages, i.e., makes the
following search(es) even more verbose than 1 would make them.)
$search->limit_glob( _s_o_m_e_-_g_l_o_b_-_s_t_r_i_n_g );
This option means that you want to limit the results just to items
whose podnames match the given glob/wildcard expression. For example,
you might limit your search to just "LWP::*", to search only for
modules starting with "LWP::*" (but not including the module "LWP"
itself); or you might limit your search to "LW*" to see only modules
whose (full) names begin with "LW"; or you might search for "*Find*"
to search for all modules with "Find" somewhere in their full name.
(You can also use "?" in a glob expression; so "DB?" will match "DBI"
and "DBD".)
$search->callback( _\_&_s_o_m_e___r_o_u_t_i_n_e );
This attribute means that every time this search sees a matching Pod
file, it should call this callback routine. The routine is called
with two parameters: the current file's filespec, and its pod name.
(For example: "("/etc/perljunk/File/Crunk.pm", "File::Crunk")" would
be in @_.)
The callback routine's return value is not used for anything.
This attribute's default value is false, meaning that no callback is
called.
$search->laborious( _t_r_u_e_-_o_r_-_f_a_l_s_e );
Unless you set this attribute to a true value, Pod::Search will apply
Perl-specific heuristics to find the correct module PODs quickly.
This attribute's default value is false. You won't normally need to
set this to true.
Specifically: Turning on this option will disable the heuristics for
seeing only files with Perl-like extensions, omitting subdirectories
that are numeric but do _n_o_t match the current Perl interpreter's
version ID, suppressing _s_i_t_e___p_e_r_l as a module hierarchy name, etc.
$search->recurse( _t_r_u_e_-_o_r_-_f_a_l_s_e );
Unless you set this attribute to a false value, Pod::Search will
recurse into subdirectories of the search directories.
$search->shadows( _t_r_u_e_-_o_r_-_f_a_l_s_e );
Unless you set this attribute to a true value, Pod::Simple::Search
will consider only the first file of a given modulename as it looks
thru the specified directories; that is, with this option off, if
Pod::Simple::Search has seen a "somepathdir/Foo/Bar.pm" already in
this search, then it won't bother looking at a
"somelaterpathdir/Foo/Bar.pm" later on in that search, because that
file is merely a "shadow". But if you turn on "$self->shadows(1)",
then these "shadow" files are inspected too, and are noted in the
pathname2podname return hash.
This attribute's default value is false; and normally you won't need
to turn it on.
$search->is_case_insensitive( _t_r_u_e_-_o_r_-_f_a_l_s_e );
Pod::Simple::Search will by default internally make an assumption
based on the underlying filesystem where the class file is found
whether it is case insensitive or not.
If it is determined to be case insensitive, during ssuurrvveeyy(()) it may
skip pod files/modules that happen to be equal to names it's already
seen, ignoring case.
However, it's possible to have distinct files in different
directories that intentionally has the same name, just differing in
case, that should be reported. Hence, you may force the behavior by
setting this to true or false.
$search->limit_re( _s_o_m_e_-_r_e_g_x_p );
Setting this attribute (to a value that's a regexp) means that you
want to limit the results just to items whose podnames match the
given regexp. Normally this option is not needed, and the more
efficient "limit_glob" attribute is used instead.
$search->dir_prefix( _s_o_m_e_-_s_t_r_i_n_g_-_v_a_l_u_e );
Setting this attribute to a string value means that the searches
should begin in the specified subdirectory name (like "Pod" or
"File::Find", also expressible as "File/Find"). For example, the
search option "$search->limit_glob("File::Find::R*")" is the same as
the combination of the search options
"$search->limit_re("^File::Find::R") -> dir_prefix("File::Find")".
Normally you don't need to know about the "dir_prefix" option, but I
include it in case it might prove useful for someone somewhere.
(Implementationally, searching with limit_glob ends up setting
limit_re and usually dir_prefix.)
$search->progress( _s_o_m_e_-_p_r_o_g_r_e_s_s_-_o_b_j_e_c_t );
If you set a value for this attribute, the value is expected to be an
object (probably of a class that you define) that has a "reach"
method and a "done" method. This is meant for reporting progress
during the search, if you don't want to use a simple callback.
Normally you don't need to know about the "progress" option, but I
include it in case it might prove useful for someone somewhere.
While a search is in progress, the progress object's "reach" and
"done" methods are called like this:
# Every time a file is being scanned for pod:
$progress->reach($count, "Scanning $file"); ++$count;
# And then at the end of the search:
$progress->done("Noted $count Pod files total");
Internally, we often set this to an object of class
Pod::Simple::Progress. That class is probably undocumented, but you
may wish to look at its source.
$name2path = $self->name2path;
This attribute is not a search parameter, but is used to report the
result of "survey" method, as discussed in the next section.
$path2name = $self->path2name;
This attribute is not a search parameter, but is used to report the
result of "survey" method, as discussed in the next section.
MMAAIINN SSEEAARRCCHH MMEETTHHOODDSS #
Once you've actually set any options you want (if any), you can go ahead
and use the following methods to search for Pod files in particular ways.
“”$$sseeaarrcchh-->>ssuurrvveeyy(( @@ddiirreeccttoorriieess ))“” The method “survey” searches for POD documents in a given set of files and/or directories. This runs the search according to the various options set by the accessors above. (For example, if the “inc” attribute is on, as it is by default, then the perl @INC directories are implicitly added to the list of directories (if any) that you specify.)
The return value of "survey" is two hashes:
"name2path"
A hash that maps from each pod-name to the filespec (like
"Stuff::Thing" => "/whatever/plib/Stuff/Thing.pm")
"path2name"
A hash that maps from each Pod filespec to its pod-name (like
"/whatever/plib/Stuff/Thing.pm" => "Stuff::Thing")
Besides saving these hashes as the hashref attributes "name2path" and
"path2name", calling this function also returns these hashrefs. In list
context, the return value of "$search->survey" is the list "(\%name2path,
\%path2name)". In scalar context, the return value is "\%name2path". Or
you can just call this in void context.
Regardless of calling context, calling "survey" saves its results in its
"name2path" and "path2name" attributes.
E.g., when searching in _$_H_O_M_E_/_p_e_r_l_5_l_i_b, the file
_$_H_O_M_E_/_p_e_r_l_5_l_i_b_/_M_y_M_o_d_u_l_e_._p_m would get the POD name _M_y_M_o_d_u_l_e, whereas
_$_H_O_M_E_/_p_e_r_l_5_l_i_b_/_M_y_c_l_a_s_s_/_S_u_b_c_l_a_s_s_._p_m would be _M_y_c_l_a_s_s_:_:_S_u_b_c_l_a_s_s. The name
information can be used for POD translators.
Only text files containing at least one valid POD command are found.
In verbose mode, a warning is printed if shadows are found (i.e., more
than one POD file with the same POD name is found, e.g. _C_P_A_N_._p_m in
different directories). This usually indicates duplicate occurrences of
modules in the _@_I_N_C search path, which is occasionally inadvertent (but
is often simply a case of a user's path dir having a more recent version
than the system's general path dirs in general.)
The options to this argument is a list of either directories that are
searched recursively, or files. (Usually you wouldn't specify files, but
just dirs.) Or you can just specify an empty-list, as in $name2path;
with the "inc" option on, as it is by default.
The POD names of files are the plain basenames with any Perl-like
extension (.pm, .pl, .pod) stripped, and path separators replaced by
"::"'s.
Calling Pod::Simple::Search->search(...) is short for
Pod::Simple::Search->new->search(...). That is, a throwaway object with
default attribute values is used.
“”$$sseeaarrcchh-->>ssiimmpplliiffyy__nnaammee(( $$ssttrr ))“” The method ssiimmpplliiffyy__nnaammee is equivalent to bbaasseennaammee, but also strips Perl- like extensions (.pm, .pl, .pod) and extensions like _._b_a_t, _._c_m_d on Win32 and OS/2, or _._c_o_m on VMS, respectively.
“”$$sseeaarrcchh-->>ffiinndd(( $$ppoodd ))“” “”$$sseeaarrcchh-->>ffiinndd(( $$ppoodd,, @@sseeaarrcchh__ddiirrss ))“” Returns the location of a Pod file, given a Pod/module/script name (like “Foo::Bar” or “perlvar” or “perldoc”), and an idea of what files/directories to look in. It searches according to the various options set by the accessors above. (For example, if the “inc” attribute is on, as it is by default, then the perl @INC directories are implicitly added to the list of directories (if any) that you specify.)
This 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. Additionally, '.pm', '.pl' and '.pod' are
automatically appended to the search as required. (So, for example,
under Unix, "A::B" is converted to "somedir/A/B.pm", "somedir/A/B.pod",
or "somedir/A/B.pl", as appropriate.)
If no such Pod file is found, this method returns undef.
If any of the given search directories contains a _p_o_d_/ subdirectory, then
it is searched. (That's how we manage to find _p_e_r_l_f_u_n_c, for example,
which is usually in _p_o_d_/_p_e_r_l_f_u_n_c in most Perl dists.)
The "verbose" and "inc" attributes influence the behavior of this search;
notably, "inc", if true, adds @INC _a_n_d _a_l_s_o _$_C_o_n_f_i_g_:_:_C_o_n_f_i_g_{_'_s_c_r_i_p_t_d_i_r_'_}
to the list of directories to search.
It is common to simply say "$filename = Pod::Simple::Search-> new
->find("perlvar")" so that just the @INC (well, and scriptdir)
directories are searched. (This happens because the "inc" attribute is
true by default.)
Calling Pod::Simple::Search->find(...) is short for
Pod::Simple::Search->new->find(...). That is, a throwaway object with
default attribute values is used.
“”$$sseellff-->>ccoonnttaaiinnss__ppoodd(( $$ffiillee ))“” Returns true if the supplied filename (not POD module) contains some Pod documentation.
SSUUPPPPOORRTT #
Questions or discussion about POD and Pod::Simple should be sent to the
pod-people@perl.org mail list. Send an empty email to
pod-people-subscribe@perl.org to subscribe.
This module is managed in an open GitHub repository,
<https://github.com/perl-pod/pod-simple/>. Feel free to fork and
contribute, or to clone <git://github.com/perl-pod/pod-simple.git> and
send patches!
Patches against Pod::Simple are welcome. Please send bug reports to
<bug-pod-simple@rt.cpan.org>.
CCOOPPYYRRIIGGHHTT AANNDD DDIISSCCLLAAIIMMEERRSS #
Copyright (c) 2002 Sean M. Burke.
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
This program is distributed in the hope that it will be useful, but
without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.
AAUUTTHHOORR #
Pod::Simple was created by Sean M. Burke <sburke@cpan.org> with code
borrowed from Marek Rouchal's Pod::Find, which in turn heavily borrowed
code from Nick Ing-Simmons' "PodToHtml".
But don't bother him, he's retired.
Pod::Simple is maintained by:
• Allison Randal "allison@perl.org"
• Hans Dieter Pearcey "hdp@cpan.org"
• David E. Wheeler "dwheeler@cpan.org"
perl v5.36.3 2023-02-15 Pod::Simple::Search(3p)