Debian Codegraph @

upstream/debian-unstable/man3/Pod::Simple::Search.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "Pod::Simple::Search 3perl"
58 .TH Pod::Simple::Search 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 Pod::Simple::Search \- find POD documents in directory trees
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 4
68 \& use Pod::Simple::Search;
69 \& my $name2path = Pod::Simple::Search\->new\->limit_glob(\*(AqLWP::*\*(Aq)\->survey;
70 \& print "Looky see what I found: ",
71 \& join(\*(Aq \*(Aq, sort keys %$name2path), "\en";
72 \&
73 \& print "LWPUA docs = ",
74 \& Pod::Simple::Search\->new\->find(\*(AqLWP::UserAgent\*(Aq) || "?",
75 \& "\en";
76 .Ve
77 .SH DESCRIPTION
78 .IX Header "DESCRIPTION"
79 \&\fBPod::Simple::Search\fR is a class that you use for running searches
80 for Pod files. An object of this class has several attributes
81 (mostly options for controlling search options), and some methods
82 for searching based on those attributes.
83 .PP
84 The way to use this class is to make a new object of this class,
85 set any options, and then call one of the search options
86 (probably \f(CW\*(C`survey\*(C'\fR or \f(CW\*(C`find\*(C'\fR). The sections below discuss the
87 syntaxes for doing all that.
88 .SH CONSTRUCTOR
89 .IX Header "CONSTRUCTOR"
90 This class provides the one constructor, called \f(CW\*(C`new\*(C'\fR.
91 It takes no parameters:
92 .PP
93 .Vb 2
94 \& use Pod::Simple::Search;
95 \& my $search = Pod::Simple::Search\->new;
96 .Ve
97 .SH ACCESSORS
98 .IX Header "ACCESSORS"
99 This class defines several methods for setting (and, occasionally,
100 reading) the contents of an object. With two exceptions (discussed at
101 the end of this section), these attributes are just for controlling the
102 way searches are carried out.
103 .PP
104 Note that each of these return \f(CW$self\fR when you call them as
105 \&\f(CW\*(C`$self\->\fR\f(CIwhatever(value)\fR\f(CW\*(C'\fR. That's so that you can chain
106 together set-attribute calls like this:
107 .PP
108 .Vb 4
109 \& my $name2path =
110 \& Pod::Simple::Search\->new
111 \& \-> inc(0) \-> verbose(1) \-> callback(\e&blab)
112 \& \->survey(@there);
113 .Ve
114 .PP
115 \&...which works exactly as if you'd done this:
116 .PP
117 .Vb 5
118 \& my $search = Pod::Simple::Search\->new;
119 \& $search\->inc(0);
120 \& $search\->verbose(1);
121 \& $search\->callback(\e&blab);
122 \& my $name2path = $search\->survey(@there);
123 .Ve
124 .ie n .IP "$search\->inc( \fItrue-or-false\fR );" 4
125 .el .IP "\f(CW$search\fR\->inc( \fItrue-or-false\fR );" 4
126 .IX Item "$search->inc( true-or-false );"
127 This attribute, if set to a true value, means that searches should
128 implicitly add perl's \fR\f(CI@INC\fR\fI\fR paths. This
129 automatically considers paths specified in the \f(CW\*(C`PERL5LIB\*(C'\fR environment
130 as this is prepended to \fI\fR\f(CI@INC\fR\fI\fR by the Perl interpreter itself.
131 This attribute's default value is \fBTRUE\fR. If you want to search
132 only specific directories, set \f(CW$self\fR\->\fBinc\fR\|(0) before calling
133 \&\f(CW$inc\fR\->survey or \f(CW$inc\fR\->find.
134 .ie n .IP "$search\->verbose( \fInonnegative-number\fR );" 4
135 .el .IP "\f(CW$search\fR\->verbose( \fInonnegative-number\fR );" 4
136 .IX Item "$search->verbose( nonnegative-number );"
137 This attribute, if set to a nonzero positive value, will make searches output
138 (via \f(CW\*(C`warn\*(C'\fR) notes about what they're doing as they do it.
139 This option may be useful for debugging a pod-related module.
140 This attribute's default value is zero, meaning that no \f(CW\*(C`warn\*(C'\fR messages
141 are produced. (Setting verbose to 1 turns on some messages, and setting
142 it to 2 turns on even more messages, i.e., makes the following search(es)
143 even more verbose than 1 would make them.)
144 .ie n .IP "$search\->limit_glob( \fIsome-glob-string\fR );" 4
145 .el .IP "\f(CW$search\fR\->limit_glob( \fIsome-glob-string\fR );" 4
146 .IX Item "$search->limit_glob( some-glob-string );"
147 This option means that you want to limit the results just to items whose
148 podnames match the given glob/wildcard expression. For example, you
149 might limit your search to just "LWP::*", to search only for modules
150 starting with "LWP::*" (but not including the module "LWP" itself); or
151 you might limit your search to "LW*" to see only modules whose (full)
152 names begin with "LW"; or you might search for "*Find*" to search for
153 all modules with "Find" somewhere in their full name. (You can also use
154 "?" in a glob expression; so "DB?" will match "DBI" and "DBD".)
155 .ie n .IP "$search\->callback( \fI\e&some_routine\fR );" 4
156 .el .IP "\f(CW$search\fR\->callback( \fI\e&some_routine\fR );" 4
157 .IX Item "$search->callback( &some_routine );"
158 This attribute means that every time this search sees a matching
159 Pod file, it should call this callback routine. The routine is called
160 with two parameters: the current file's filespec, and its pod name.
161 (For example: \f(CW\*(C`("/etc/perljunk/File/Crunk.pm", "File::Crunk")\*(C'\fR would
162 be in \f(CW@_\fR.)
163 .Sp
164 The callback routine's return value is not used for anything.
165 .Sp
166 This attribute's default value is false, meaning that no callback
167 is called.
168 .ie n .IP "$search\->laborious( \fItrue-or-false\fR );" 4
169 .el .IP "\f(CW$search\fR\->laborious( \fItrue-or-false\fR );" 4
170 .IX Item "$search->laborious( true-or-false );"
171 Unless you set this attribute to a true value, Pod::Search will
172 apply Perl-specific heuristics to find the correct module PODs quickly.
173 This attribute's default value is false. You won't normally need
174 to set this to true.
175 .Sp
176 Specifically: Turning on this option will disable the heuristics for
177 seeing only files with Perl-like extensions, omitting subdirectories
178 that are numeric but do \fInot\fR match the current Perl interpreter's
179 version ID, suppressing \fIsite_perl\fR as a module hierarchy name, etc.
180 .ie n .IP "$search\->recurse( \fItrue-or-false\fR );" 4
181 .el .IP "\f(CW$search\fR\->recurse( \fItrue-or-false\fR );" 4
182 .IX Item "$search->recurse( true-or-false );"
183 Unless you set this attribute to a false value, Pod::Search will
184 recurse into subdirectories of the search directories.
185 .ie n .IP "$search\->shadows( \fItrue-or-false\fR );" 4
186 .el .IP "\f(CW$search\fR\->shadows( \fItrue-or-false\fR );" 4
187 .IX Item "$search->shadows( true-or-false );"
188 Unless you set this attribute to a true value, Pod::Simple::Search will
189 consider only the first file of a given modulename as it looks thru the
190 specified directories; that is, with this option off, if
191 Pod::Simple::Search has seen a \f(CW\*(C`somepathdir/Foo/Bar.pm\*(C'\fR already in this
192 search, then it won't bother looking at a \f(CW\*(C`somelaterpathdir/Foo/Bar.pm\*(C'\fR
193 later on in that search, because that file is merely a "shadow". But if
194 you turn on \f(CW\*(C`$self\->shadows(1)\*(C'\fR, then these "shadow" files are
195 inspected too, and are noted in the pathname2podname return hash.
196 .Sp
197 This attribute's default value is false; and normally you won't
198 need to turn it on.
199 .ie n .IP "$search\->is_case_insensitive( \fItrue-or-false\fR );" 4
200 .el .IP "\f(CW$search\fR\->is_case_insensitive( \fItrue-or-false\fR );" 4
201 .IX Item "$search->is_case_insensitive( true-or-false );"
202 Pod::Simple::Search will by default internally make an assumption
203 based on the underlying filesystem where the class file is found
204 whether it is case insensitive or not.
205 .Sp
206 If it is determined to be case insensitive, during \fBsurvey()\fR it may
207 skip pod files/modules that happen to be equal to names it's already
208 seen, ignoring case.
209 .Sp
210 However, it's possible to have distinct files in different directories
211 that intentionally has the same name, just differing in case, that should
212 be reported. Hence, you may force the behavior by setting this to true
213 or false.
214 .ie n .IP "$search\->limit_re( \fIsome-regxp\fR );" 4
215 .el .IP "\f(CW$search\fR\->limit_re( \fIsome-regxp\fR );" 4
216 .IX Item "$search->limit_re( some-regxp );"
217 Setting this attribute (to a value that's a regexp) means that you want
218 to limit the results just to items whose podnames match the given
219 regexp. Normally this option is not needed, and the more efficient
220 \&\f(CW\*(C`limit_glob\*(C'\fR attribute is used instead.
221 .ie n .IP "$search\->dir_prefix( \fIsome-string-value\fR );" 4
222 .el .IP "\f(CW$search\fR\->dir_prefix( \fIsome-string-value\fR );" 4
223 .IX Item "$search->dir_prefix( some-string-value );"
224 Setting this attribute to a string value means that the searches should
225 begin in the specified subdirectory name (like "Pod" or "File::Find",
226 also expressible as "File/Find"). For example, the search option
227 \&\f(CW\*(C`$search\->limit_glob("File::Find::R*")\*(C'\fR
228 is the same as the combination of the search options
229 \&\f(CW\*(C`$search\->limit_re("^File::Find::R") \-> dir_prefix("File::Find")\*(C'\fR.
230 .Sp
231 Normally you don't need to know about the \f(CW\*(C`dir_prefix\*(C'\fR option, but I
232 include it in case it might prove useful for someone somewhere.
233 .Sp
234 (Implementationally, searching with limit_glob ends up setting limit_re
235 and usually dir_prefix.)
236 .ie n .IP "$search\->progress( \fIsome-progress-object\fR );" 4
237 .el .IP "\f(CW$search\fR\->progress( \fIsome-progress-object\fR );" 4
238 .IX Item "$search->progress( some-progress-object );"
239 If you set a value for this attribute, the value is expected
240 to be an object (probably of a class that you define) that has a
241 \&\f(CW\*(C`reach\*(C'\fR method and a \f(CW\*(C`done\*(C'\fR method. This is meant for reporting
242 progress during the search, if you don't want to use a simple
243 callback.
244 .Sp
245 Normally you don't need to know about the \f(CW\*(C`progress\*(C'\fR option, but I
246 include it in case it might prove useful for someone somewhere.
247 .Sp
248 While a search is in progress, the progress object's \f(CW\*(C`reach\*(C'\fR and
249 \&\f(CW\*(C`done\*(C'\fR methods are called like this:
250 .Sp
251 .Vb 2
252 \& # Every time a file is being scanned for pod:
253 \& $progress\->reach($count, "Scanning $file"); ++$count;
254 \&
255 \& # And then at the end of the search:
256 \& $progress\->done("Noted $count Pod files total");
257 .Ve
258 .Sp
259 Internally, we often set this to an object of class
260 Pod::Simple::Progress. That class is probably undocumented,
261 but you may wish to look at its source.
262 .ie n .IP "$name2path = $self\->name2path;" 4
263 .el .IP "\f(CW$name2path\fR = \f(CW$self\fR\->name2path;" 4
264 .IX Item "$name2path = $self->name2path;"
265 This attribute is not a search parameter, but is used to report the
266 result of \f(CW\*(C`survey\*(C'\fR method, as discussed in the next section.
267 .ie n .IP "$path2name = $self\->path2name;" 4
268 .el .IP "\f(CW$path2name\fR = \f(CW$self\fR\->path2name;" 4
269 .IX Item "$path2name = $self->path2name;"
270 This attribute is not a search parameter, but is used to report the
271 result of \f(CW\*(C`survey\*(C'\fR method, as discussed in the next section.
272 .SH "MAIN SEARCH METHODS"
273 .IX Header "MAIN SEARCH METHODS"
274 Once you've actually set any options you want (if any), you can go
275 ahead and use the following methods to search for Pod files
276 in particular ways.
277 .ie n .SS """$search\->survey( @directories )"""
278 .el .SS "\f(CW$search\->survey( @directories )\fP"
279 .IX Subsection "$search->survey( @directories )"
280 The method \f(CW\*(C`survey\*(C'\fR searches for POD documents in a given set of
281 files and/or directories. This runs the search according to the various
282 options set by the accessors above. (For example, if the \f(CW\*(C`inc\*(C'\fR attribute
283 is on, as it is by default, then the perl \f(CW@INC\fR directories are implicitly
284 added to the list of directories (if any) that you specify.)
285 .PP
286 The return value of \f(CW\*(C`survey\*(C'\fR is two hashes:
287 .ie n .IP """name2path""" 4
288 .el .IP \f(CWname2path\fR 4
289 .IX Item "name2path"
290 A hash that maps from each pod-name to the filespec (like
291 "Stuff::Thing" => "/whatever/plib/Stuff/Thing.pm")
292 .ie n .IP """path2name""" 4
293 .el .IP \f(CWpath2name\fR 4
294 .IX Item "path2name"
295 A hash that maps from each Pod filespec to its pod-name (like
296 "/whatever/plib/Stuff/Thing.pm" => "Stuff::Thing")
297 .PP
298 Besides saving these hashes as the hashref attributes
299 \&\f(CW\*(C`name2path\*(C'\fR and \f(CW\*(C`path2name\*(C'\fR, calling this function also returns
300 these hashrefs. In list context, the return value of
301 \&\f(CW\*(C`$search\->survey\*(C'\fR is the list \f(CW\*(C`(\e%name2path, \e%path2name)\*(C'\fR.
302 In scalar context, the return value is \f(CW\*(C`\e%name2path\*(C'\fR.
303 Or you can just call this in void context.
304 .PP
305 Regardless of calling context, calling \f(CW\*(C`survey\*(C'\fR saves
306 its results in its \f(CW\*(C`name2path\*(C'\fR and \f(CW\*(C`path2name\*(C'\fR attributes.
307 .PP
308 E.g., when searching in \fR\f(CI$HOME\fR\fI/perl5lib\fR, the file
309 \&\fI\fR\f(CI$HOME\fR\fI/perl5lib/MyModule.pm\fR would get the POD name \fIMyModule\fR,
310 whereas \fI\fR\f(CI$HOME\fR\fI/perl5lib/Myclass/Subclass.pm\fR would be
311 \&\fIMyclass::Subclass\fR. The name information can be used for POD
312 translators.
313 .PP
314 Only text files containing at least one valid POD command are found.
315 .PP
316 In verbose mode, a warning is printed if shadows are found (i.e., more
317 than one POD file with the same POD name is found, e.g. \fICPAN.pm\fR in
318 different directories). This usually indicates duplicate occurrences of
319 modules in the \fR\f(CI@INC\fR\fI\fR search path, which is occasionally inadvertent
320 (but is often simply a case of a user's path dir having a more recent
321 version than the system's general path dirs in general.)
322 .PP
323 The options to this argument is a list of either directories that are
324 searched recursively, or files. (Usually you wouldn't specify files,
325 but just dirs.) Or you can just specify an empty-list, as in
326 \&\f(CW$name2path\fR; with the \f(CW\*(C`inc\*(C'\fR option on, as it is by default.
327 .PP
328 The POD names of files are the plain basenames with any Perl-like
329 extension (.pm, .pl, .pod) stripped, and path separators replaced by
330 \&\f(CW\*(C`::\*(C'\fR's.
331 .PP
332 Calling Pod::Simple::Search\->search(...) is short for
333 Pod::Simple::Search\->new\->search(...). That is, a throwaway object
334 with default attribute values is used.
335 .ie n .SS """$search\->simplify_name( $str )"""
336 .el .SS "\f(CW$search\->simplify_name( $str )\fP"
337 .IX Subsection "$search->simplify_name( $str )"
338 The method \fBsimplify_name\fR is equivalent to \fBbasename\fR, but also
339 strips Perl-like extensions (.pm, .pl, .pod) and extensions like
340 \&\fI.bat\fR, \fI.cmd\fR on Win32 and OS/2, or \fI.com\fR on VMS, respectively.
341 .ie n .SS """$search\->find( $pod )"""
342 .el .SS "\f(CW$search\->find( $pod )\fP"
343 .IX Subsection "$search->find( $pod )"
344 .ie n .SS """$search\->find( $pod, @search_dirs )"""
345 .el .SS "\f(CW$search\->find( $pod, @search_dirs )\fP"
346 .IX Subsection "$search->find( $pod, @search_dirs )"
347 Returns the location of a Pod file, given a Pod/module/script name
348 (like "Foo::Bar" or "perlvar" or "perldoc"), and an idea of
349 what files/directories to look in.
350 It searches according to the various options set by the accessors above.
351 (For example, if the \f(CW\*(C`inc\*(C'\fR attribute is on, as it is by default, then
352 the perl \f(CW@INC\fR directories are implicitly added to the list of
353 directories (if any) that you specify.)
354 .PP
355 This returns the full path of the first occurrence to the file.
356 Package names (eg 'A::B') are automatically converted to directory
357 names in the selected directory. Additionally, '.pm', '.pl' and '.pod'
358 are automatically appended to the search as required.
359 (So, for example, under Unix, "A::B" is converted to "somedir/A/B.pm",
360 "somedir/A/B.pod", or "somedir/A/B.pl", as appropriate.)
361 .PP
362 If no such Pod file is found, this method returns undef.
363 .PP
364 If any of the given search directories contains a \fIpod/\fR subdirectory,
365 then it is searched. (That's how we manage to find \fIperlfunc\fR,
366 for example, which is usually in \fIpod/perlfunc\fR in most Perl dists.)
367 .PP
368 The \f(CW\*(C`verbose\*(C'\fR and \f(CW\*(C`inc\*(C'\fR attributes influence the behavior of this
369 search; notably, \f(CW\*(C`inc\*(C'\fR, if true, adds \f(CW@INC\fR \fIand also
370 \&\fR\f(CI$Config::Config\fR\fI{'scriptdir'}\fR to the list of directories to search.
371 .PP
372 It is common to simply say \f(CW\*(C`$filename = Pod::Simple::Search\-> new
373 \&\->find("perlvar")\*(C'\fR so that just the \f(CW@INC\fR (well, and scriptdir)
374 directories are searched. (This happens because the \f(CW\*(C`inc\*(C'\fR
375 attribute is true by default.)
376 .PP
377 Calling Pod::Simple::Search\->find(...) is short for
378 Pod::Simple::Search\->new\->find(...). That is, a throwaway object
379 with default attribute values is used.
380 .ie n .SS """$self\->contains_pod( $file )"""
381 .el .SS "\f(CW$self\->contains_pod( $file )\fP"
382 .IX Subsection "$self->contains_pod( $file )"
383 Returns true if the supplied filename (not POD module) contains some Pod
384 documentation.
385 .SH SUPPORT
386 .IX Header "SUPPORT"
387 Questions or discussion about POD and Pod::Simple should be sent to the
388 pod\[email protected] mail list. Send an empty email to
389 pod\-people\[email protected] to subscribe.
390 .PP
391 This module is managed in an open GitHub repository,
392 <https://github.com/perl\-pod/pod\-simple/>. Feel free to fork and contribute, or
393 to clone <https://github.com/perl\-pod/pod\-simple.git> and send patches!
394 .PP
395 Patches against Pod::Simple are welcome. Please send bug reports to
396 <bug\-pod\[email protected]>.
397 .SH "COPYRIGHT AND DISCLAIMERS"
398 .IX Header "COPYRIGHT AND DISCLAIMERS"
399 Copyright (c) 2002 Sean M. Burke.
400 .PP
401 This library is free software; you can redistribute it and/or modify it
402 under the same terms as Perl itself.
403 .PP
404 This program is distributed in the hope that it will be useful, but
405 without any warranty; without even the implied warranty of
406 merchantability or fitness for a particular purpose.
407 .SH AUTHOR
408 .IX Header "AUTHOR"
409 Pod::Simple was created by Sean M. Burke <[email protected]> with code borrowed
410 from Marek Rouchal's Pod::Find, which in turn heavily borrowed code from
411 Nick Ing\-Simmons' \f(CW\*(C`PodToHtml\*(C'\fR.
412 .PP
413 But don't bother him, he's retired.
414 .PP
415 Pod::Simple is maintained by:
416 .IP \(bu 4
417 Allison Randal \f(CW\*(C`[email protected]\*(C'\fR
418 .IP \(bu 4
419 Hans Dieter Pearcey \f(CW\*(C`[email protected]\*(C'\fR
420 .IP \(bu 4
421 David E. Wheeler \f(CW\*(C`[email protected]\*(C'\fR