1Pod::Simple::Search(3)User Contributed Perl DocumentationPod::Simple::Search(3)
2
3
4

NAME

6       Pod::Simple::Search - find POD documents in directory trees
7

SYNOPSIS

9         use Pod::Simple::Search;
10         my $name2path = Pod::Simple::Search->new->limit_glob('LWP::*')->survey;
11         print "Looky see what I found: ",
12           join(' ', sort keys %$name2path), "\n";
13
14         print "LWPUA docs = ",
15           Pod::Simple::Search->new->find('LWP::UserAgent') || "?",
16           "\n";
17

DESCRIPTION

19       Pod::Simple::Search is a class that you use for running searches for
20       Pod files.  An object of this class has several attributes (mostly
21       options for controlling search options), and some methods for searching
22       based on those attributes.
23
24       The way to use this class is to make a new object of this class, set
25       any options, and then call one of the search options (probably "survey"
26       or "find").  The sections below discuss the syntaxes for doing all
27       that.
28

CONSTRUCTOR

30       This class provides the one constructor, called "new".  It takes no
31       parameters:
32
33         use Pod::Simple::Search;
34         my $search = Pod::Simple::Search->new;
35

ACCESSORS

37       This class defines several methods for setting (and, occasionally,
38       reading) the contents of an object. With two exceptions (discussed at
39       the end of this section), these attributes are just for controlling the
40       way searches are carried out.
41
42       Note that each of these return $self when you call them as
43       "$self->whatever(value)".  That's so that you can chain together set-
44       attribute calls like this:
45
46         my $name2path =
47           Pod::Simple::Search->new
48           -> inc(0) -> verbose(1) -> callback(\&blab)
49           ->survey(@there);
50
51       ...which works exactly as if you'd done this:
52
53         my $search = Pod::Simple::Search->new;
54         $search->inc(0);
55         $search->verbose(1);
56         $search->callback(\&blab);
57         my $name2path = $search->survey(@there);
58
59       $search->inc( true-or-false );
60           This attribute, if set to a true value, means that searches should
61           implicitly add perl's @INC paths. This automatically considers
62           paths specified in the "PERL5LIB" environment as this is prepended
63           to @INC by the Perl interpreter itself.  This attribute's default
64           value is TRUE.  If you want to search only specific directories,
65           set $self->inc(0) before calling $inc->survey or $inc->find.
66
67       $search->verbose( nonnegative-number );
68           This attribute, if set to a nonzero positive value, will make
69           searches output (via "warn") notes about what they're doing as they
70           do it.  This option may be useful for debugging a pod-related
71           module.  This attribute's default value is zero, meaning that no
72           "warn" messages are produced.  (Setting verbose to 1 turns on some
73           messages, and setting it to 2 turns on even more messages, i.e.,
74           makes the following search(es) even more verbose than 1 would make
75           them.)
76
77       $search->limit_glob( some-glob-string );
78           This option means that you want to limit the results just to items
79           whose podnames match the given glob/wildcard expression. For
80           example, you might limit your search to just "LWP::*", to search
81           only for modules starting with "LWP::*" (but not including the
82           module "LWP" itself); or you might limit your search to "LW*" to
83           see only modules whose (full) names begin with "LW"; or you might
84           search for "*Find*" to search for all modules with "Find" somewhere
85           in their full name. (You can also use "?" in a glob expression; so
86           "DB?" will match "DBI" and "DBD".)
87
88       $search->callback( \&some_routine );
89           This attribute means that every time this search sees a matching
90           Pod file, it should call this callback routine.  The routine is
91           called with two parameters: the current file's filespec, and its
92           pod name.  (For example: "("/etc/perljunk/File/Crunk.pm",
93           "File::Crunk")" would be in @_.)
94
95           The callback routine's return value is not used for anything.
96
97           This attribute's default value is false, meaning that no callback
98           is called.
99
100       $search->laborious( true-or-false );
101           Unless you set this attribute to a true value, Pod::Search will
102           apply Perl-specific heuristics to find the correct module PODs
103           quickly.  This attribute's default value is false.  You won't
104           normally need to set this to true.
105
106           Specifically: Turning on this option will disable the heuristics
107           for seeing only files with Perl-like extensions, omitting
108           subdirectories that are numeric but do not match the current Perl
109           interpreter's version ID, suppressing site_perl as a module
110           hierarchy name, etc.
111
112       $search->recurse( true-or-false );
113           Unless you set this attribute to a false value, Pod::Search will
114           recurse into subdirectories of the search directories.
115
116       $search->shadows( true-or-false );
117           Unless you set this attribute to a true value, Pod::Simple::Search
118           will consider only the first file of a given modulename as it looks
119           thru the specified directories; that is, with this option off, if
120           Pod::Simple::Search has seen a "somepathdir/Foo/Bar.pm" already in
121           this search, then it won't bother looking at a
122           "somelaterpathdir/Foo/Bar.pm" later on in that search, because that
123           file is merely a "shadow". But if you turn on "$self->shadows(1)",
124           then these "shadow" files are inspected too, and are noted in the
125           pathname2podname return hash.
126
127           This attribute's default value is false; and normally you won't
128           need to turn it on.
129
130       $search->is_case_insensitive( true-or-false );
131           Pod::Simple::Search will by default internally make an assumption
132           based on the underlying filesystem where the class file is found
133           whether it is case insensitive or not.
134
135           If it is determined to be case insensitive, during survey() it may
136           skip pod files/modules that happen to be equal to names it's
137           already seen, ignoring case.
138
139           However, it's possible to have distinct files in different
140           directories that intentionally has the same name, just differing in
141           case, that should be reported. Hence, you may force the behavior by
142           setting this to true or false.
143
144       $search->limit_re( some-regxp );
145           Setting this attribute (to a value that's a regexp) means that you
146           want to limit the results just to items whose podnames match the
147           given regexp. Normally this option is not needed, and the more
148           efficient "limit_glob" attribute is used instead.
149
150       $search->dir_prefix( some-string-value );
151           Setting this attribute to a string value means that the searches
152           should begin in the specified subdirectory name (like "Pod" or
153           "File::Find", also expressible as "File/Find"). For example, the
154           search option "$search->limit_glob("File::Find::R*")" is the same
155           as the combination of the search options
156           "$search->limit_re("^File::Find::R") -> dir_prefix("File::Find")".
157
158           Normally you don't need to know about the "dir_prefix" option, but
159           I include it in case it might prove useful for someone somewhere.
160
161           (Implementationally, searching with limit_glob ends up setting
162           limit_re and usually dir_prefix.)
163
164       $search->progress( some-progress-object );
165           If you set a value for this attribute, the value is expected to be
166           an object (probably of a class that you define) that has a "reach"
167           method and a "done" method.  This is meant for reporting progress
168           during the search, if you don't want to use a simple callback.
169
170           Normally you don't need to know about the "progress" option, but I
171           include it in case it might prove useful for someone somewhere.
172
173           While a search is in progress, the progress object's "reach" and
174           "done" methods are called like this:
175
176             # Every time a file is being scanned for pod:
177             $progress->reach($count, "Scanning $file");   ++$count;
178
179             # And then at the end of the search:
180             $progress->done("Noted $count Pod files total");
181
182           Internally, we often set this to an object of class
183           Pod::Simple::Progress.  That class is probably undocumented, but
184           you may wish to look at its source.
185
186       $name2path = $self->name2path;
187           This attribute is not a search parameter, but is used to report the
188           result of "survey" method, as discussed in the next section.
189
190       $path2name = $self->path2name;
191           This attribute is not a search parameter, but is used to report the
192           result of "survey" method, as discussed in the next section.
193

MAIN SEARCH METHODS

195       Once you've actually set any options you want (if any), you can go
196       ahead and use the following methods to search for Pod files in
197       particular ways.
198
199   "$search->survey( @directories )"
200       The method "survey" searches for POD documents in a given set of files
201       and/or directories.  This runs the search according to the various
202       options set by the accessors above.  (For example, if the "inc"
203       attribute is on, as it is by default, then the perl @INC directories
204       are implicitly added to the list of directories (if any) that you
205       specify.)
206
207       The return value of "survey" is two hashes:
208
209       "name2path"
210           A hash that maps from each pod-name to the filespec (like
211           "Stuff::Thing" => "/whatever/plib/Stuff/Thing.pm")
212
213       "path2name"
214           A hash that maps from each Pod filespec to its pod-name (like
215           "/whatever/plib/Stuff/Thing.pm" => "Stuff::Thing")
216
217       Besides saving these hashes as the hashref attributes "name2path" and
218       "path2name", calling this function also returns these hashrefs.  In
219       list context, the return value of "$search->survey" is the list
220       "(\%name2path, \%path2name)".  In scalar context, the return value is
221       "\%name2path".  Or you can just call this in void context.
222
223       Regardless of calling context, calling "survey" saves its results in
224       its "name2path" and "path2name" attributes.
225
226       E.g., when searching in $HOME/perl5lib, the file
227       $HOME/perl5lib/MyModule.pm would get the POD name MyModule, whereas
228       $HOME/perl5lib/Myclass/Subclass.pm would be Myclass::Subclass. The name
229       information can be used for POD translators.
230
231       Only text files containing at least one valid POD command are found.
232
233       In verbose mode, a warning is printed if shadows are found (i.e., more
234       than one POD file with the same POD name is found, e.g. CPAN.pm in
235       different directories).  This usually indicates duplicate occurrences
236       of modules in the @INC search path, which is occasionally inadvertent
237       (but is often simply a case of a user's path dir having a more recent
238       version than the system's general path dirs in general.)
239
240       The options to this argument is a list of either directories that are
241       searched recursively, or files.  (Usually you wouldn't specify files,
242       but just dirs.)  Or you can just specify an empty-list, as in
243       $name2path; with the "inc" option on, as it is by default.
244
245       The POD names of files are the plain basenames with any Perl-like
246       extension (.pm, .pl, .pod) stripped, and path separators replaced by
247       "::"'s.
248
249       Calling Pod::Simple::Search->search(...) is short for
250       Pod::Simple::Search->new->search(...).  That is, a throwaway object
251       with default attribute values is used.
252
253   "$search->simplify_name( $str )"
254       The method simplify_name is equivalent to basename, but also strips
255       Perl-like extensions (.pm, .pl, .pod) and extensions like .bat, .cmd on
256       Win32 and OS/2, or .com on VMS, respectively.
257
258   "$search->find( $pod )"
259   "$search->find( $pod, @search_dirs )"
260       Returns the location of a Pod file, given a Pod/module/script name
261       (like "Foo::Bar" or "perlvar" or "perldoc"), and an idea of what
262       files/directories to look in.  It searches according to the various
263       options set by the accessors above.  (For example, if the "inc"
264       attribute is on, as it is by default, then the perl @INC directories
265       are implicitly added to the list of directories (if any) that you
266       specify.)
267
268       This returns the full path of the first occurrence to the file.
269       Package names (eg 'A::B') are automatically converted to directory
270       names in the selected directory.  Additionally, '.pm', '.pl' and '.pod'
271       are automatically appended to the search as required.  (So, for
272       example, under Unix, "A::B" is converted to "somedir/A/B.pm",
273       "somedir/A/B.pod", or "somedir/A/B.pl", as appropriate.)
274
275       If no such Pod file is found, this method returns undef.
276
277       If any of the given search directories contains a pod/ subdirectory,
278       then it is searched.  (That's how we manage to find perlfunc, for
279       example, which is usually in pod/perlfunc in most Perl dists.)
280
281       The "verbose" and "inc" attributes influence the behavior of this
282       search; notably, "inc", if true, adds @INC and also
283       $Config::Config{'scriptdir'} to the list of directories to search.
284
285       It is common to simply say "$filename = Pod::Simple::Search-> new
286       ->find("perlvar")" so that just the @INC (well, and scriptdir)
287       directories are searched.  (This happens because the "inc" attribute is
288       true by default.)
289
290       Calling Pod::Simple::Search->find(...) is short for
291       Pod::Simple::Search->new->find(...).  That is, a throwaway object with
292       default attribute values is used.
293
294   "$self->contains_pod( $file )"
295       Returns true if the supplied filename (not POD module) contains some
296       Pod documentation.
297

SUPPORT

299       Questions or discussion about POD and Pod::Simple should be sent to the
300       pod-people@perl.org mail list. Send an empty email to
301       pod-people-subscribe@perl.org to subscribe.
302
303       This module is managed in an open GitHub repository,
304       <https://github.com/perl-pod/pod-simple/>. Feel free to fork and
305       contribute, or to clone <https://github.com/perl-pod/pod-simple.git>
306       and send patches!
307
308       Patches against Pod::Simple are welcome. Please send bug reports to
309       <bug-pod-simple@rt.cpan.org>.
310
312       Copyright (c) 2002 Sean M. Burke.
313
314       This library is free software; you can redistribute it and/or modify it
315       under the same terms as Perl itself.
316
317       This program is distributed in the hope that it will be useful, but
318       without any warranty; without even the implied warranty of
319       merchantability or fitness for a particular purpose.
320

AUTHOR

322       Pod::Simple was created by Sean M. Burke <sburke@cpan.org> with code
323       borrowed from Marek Rouchal's Pod::Find, which in turn heavily borrowed
324       code from Nick Ing-Simmons' "PodToHtml".
325
326       But don't bother him, he's retired.
327
328       Pod::Simple is maintained by:
329
330       •   Allison Randal "allison@perl.org"
331
332       •   Hans Dieter Pearcey "hdp@cpan.org"
333
334       •   David E. Wheeler "dwheeler@cpan.org"
335
336
337
338perl v5.38.0                      2023-07-21            Pod::Simple::Search(3)
Impressum