Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Pod::Simple::Search.3pm

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