1Pod::Simple::Search(3)User Contributed Perl DocumentationPod::Simple::Search(3)
2
6 Pod::Simple::Search - find POD documents in directory trees
7
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 print "LWPUA docs = ",
15 Pod::Simple::Search->new->find('LWP::UserAgent') ⎪⎪ "?",
16 "\n";
17
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 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
30 This class provides the one constructor, called "new". It takes no
31 parameters:
32 use Pod::Simple::Search;
34 my $search = Pod::Simple::Search->new;
35
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 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 my $name2path =
47 Pod::Simple::Search->new
48 -> inc(0) -> verbose(1) -> callback(\&blab)
49 ->survey(@there);
50 ...which works exactly as if you'd done this:
52 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 $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 $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 mod‐
71 ule. 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 $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 exam‐
80 ple, you might limit your search to just "LWP::*", to search only
81 for modules starting with "LWP::*" (but not including the module
82 "LWP" itself); or you might limit your search to "LW*" to see only
83 modules whose (full) names begin with "LW"; or you might search for
84 "*Find*" to search for all modules with "Find" somewhere in their
85 full name. (You can also use "?" in a glob expression; so "DB?"
86 will match "DBI" and "DBD".)
87 $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 The callback routine's return value is not used for anything.
96 This attribute's default value is false, meaning that no callback
98 is called.
99 $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 true. You won't nor‐
104 mally need to set this to false.
105 Specifically: Turning on this option will disable the heuristics
107 for seeing only files with Perl-like extensions, omitting subdirec‐
108 tories that are numeric but do not match the current Perl inter‐
109 preter's version ID, suppressing site_perl as a module hierarchy
110 name, etc.
111 $search->shadows( true-or-false );
113 Unless you set this attribute to a true value, Pod::Simple::Search
114 will consider only the first file of a given modulename as it looks
115 thru the specified directories; that is, with this option off, if
116 Pod::Simple::Search has seen a "somepathdir/Foo/Bar.pm" already in
117 this search, then it won't bother looking at a "somelater‐
118 pathdir/Foo/Bar.pm" later on in that search, because that file is
119 merely a "shadow". But if you turn on "$self->shadows(1)", then
120 these "shadow" files are inspected too, and are noted in the path‐
121 name2podname return hash.
122 This attribute's default value is false; and normally you won't
124 need to turn it on.
125 $search->limit_re( some-regxp );
127 Setting this attribute (to a value that's a regexp) means that you
128 want to limit the results just to items whose podnames match the
129 given regexp. Normally this option is not needed, and the more
130 efficient "limit_glob" attribute is used instead.
131 $search->dir_prefix( some-string-value );
133 Setting this attribute to a string value means that the searches
134 should begin in the specified subdirectory name (like "Pod" or
135 "File::Find", also expressable as "File/Find"). For example, the
136 search option "$search->limit_glob("File::Find::R*")" is the same
137 as the combination of the search options
138 "$search->limit_re("^File::Find::R") -> dir_prefix("File::Find")".
139 Normally you don't need to know about the "dir_prefix" option, but
141 I include it in case it might prove useful for someone somewhere.
142 (Implementationally, searching with limit_glob ends up setting
144 limit_re and usually dir_prefix.)
145 $search->progress( some-progress-object );
147 If you set a value for this attribute, the value is expected to be
148 an object (probably of a class that you define) that has a "reach"
149 method and a "done" method. This is meant for reporting progress
150 during the search, if you don't want to use a simple callback.
151 Normally you don't need to know about the "progress" option, but I
153 include it in case it might prove useful for someone somewhere.
154 While a search is in progress, the progress object's "reach" and
156 "done" methods are called like this:
157 # Every time a file is being scanned for pod:
159 $progress->reach($count, "Scanning $file"); ++$count;
160 # And then at the end of the search:
162 $progress->done("Noted $count Pod files total");
163 Internally, we often set this to an object of class Pod::Sim‐
165 ple::Progress. That class is probably undocumented, but you may
166 wish to look at its source.
167 $name2path = $self->name2path;
169 This attribute is not a search parameter, but is used to report the
170 result of "survey" method, as discussed in the next section.
171 $path2name = $self->path2name;
173 This attribute is not a search parameter, but is used to report the
174 result of "survey" method, as discussed in the next section.
175
177 Once you've actually set any options you want (if any), you can go
178 ahead and use the following methods to search for Pod files in particu‐
179 lar ways.
180 "$search->survey( @directories )"
182 The method "survey" searches for POD documents in a given set of files
184 and/or directories. This runs the search according to the various
185 options set by the accessors above. (For example, if the "inc"
186 attribute is on, as it is by default, then the perl @INC directories
187 are implicitly added to the list of directories (if any) that you spec‐
188 ify.)
189 The return value of "survey" is two hashes:
191 "name2path"
193 A hash that maps from each pod-name to the filespec (like
194 "Stuff::Thing" => "/whatever/plib/Stuff/Thing.pm")
195 "path2name"
197 A hash that maps from each Pod filespec to its pod-name (like
198 "/whatever/plib/Stuff/Thing.pm" => "Stuff::Thing")
199 Besides saving these hashes as the hashref attributes "name2path" and
201 "path2name", calling this function also returns these hashrefs. In
202 list context, the return value of "$search->survey" is the list
203 "(\%name2path, \%path2name)". In scalar context, the return value is
204 "\%name2path". Or you can just call this in void context.
205 Regardless of calling context, calling "survey" saves its results in
207 its "name2path" and "path2name" attributes.
208 E.g., when searching in $HOME/perl5lib, the file $HOME/perl5lib/MyMod‐
210 ule.pm would get the POD name MyModule, whereas
211 $HOME/perl5lib/Myclass/Subclass.pm would be Myclass::Subclass. The name
212 information can be used for POD translators.
213 Only text files containing at least one valid POD command are found.
215 In verbose mode, a warning is printed if shadows are found (i.e., more
217 than one POD file with the same POD name is found, e.g. CPAN.pm in dif‐
218 ferent directories). This usually indicates duplicate occurrences of
219 modules in the @INC search path, which is occasionally inadvertent (but
220 is often simply a case of a user's path dir having a more recent ver‐
221 sion than the system's general path dirs in general.)
222 The options to this argument is a list of either directories that are
224 searched recursively, or files. (Usually you wouldn't specify files,
225 but just dirs.) Or you can just specify an empty-list, as in
226 $name2path; with the "inc" option on, as it is by default, teh
227 The POD names of files are the plain basenames with any Perl-like
229 extension (.pm, .pl, .pod) stripped, and path separators replaced by
230 "::"'s.
231 Calling Pod::Simple::Search->search(...) is short for Pod::Sim‐
233 ple::Search->new->search(...). That is, a throwaway object with
234 default attribute values is used.
235 "$search->simplify_name( $str )"
237 The method simplify_name is equivalent to basename, but also strips
239 Perl-like extensions (.pm, .pl, .pod) and extensions like .bat, .cmd on
240 Win32 and OS/2, or .com on VMS, respectively.
241 "$search->find( $pod )"
243 "$search->find( $pod, @search_dirs )"
245 Returns the location of a Pod file, given a Pod/module/script name
247 (like "Foo::Bar" or "perlvar" or "perldoc"), and an idea of what
248 files/directories to look in. It searches according to the various
249 options set by the accessors above. (For example, if the "inc"
250 attribute is on, as it is by default, then the perl @INC directories
251 are implicitly added to the list of directories (if any) that you spec‐
252 ify.)
253 This returns the full path of the first occurrence to the file. Pack‐
255 age names (eg 'A::B') are automatically converted to directory names in
256 the selected directory. Additionally, '.pm', '.pl' and '.pod' are
257 automatically appended to the search as required. (So, for example,
258 under Unix, "A::B" is converted to "somedir/A/B.pm", "somedir/A/B.pod",
259 or "somedir/A/B.pl", as appropriate.)
260 If no such Pod file is found, this method returns undef.
262 If any of the given search directories contains a pod/ subdirectory,
264 then it is searched. (That's how we manage to find perlfunc, for exam‐
265 ple, which is usually in pod/perlfunc in most Perl dists.)
266 The "verbose" and "inc" attributes influence the behavior of this
268 search; notably, "inc", if true, adds @INC and also $Config::Con‐
269 fig{'scriptdir'} to the list of directories to search.
270 It is common to simply say "$filename = Pod::Simple::Search-> new
272 ->find("perlvar")" so that just the @INC (well, and scriptdir) directo‐
273 ries are searched. (This happens because the "inc" attribute is true
274 by default.)
275 Calling Pod::Simple::Search->find(...) is short for Pod::Sim‐
277 ple::Search->new->find(...). That is, a throwaway object with default
278 attribute values is used.
279 "$self->contains_pod( $file )"
281 Returns true if the supplied filename (not POD module) contains some
283 Pod documentation.
284
286 Sean M. Burke <sburke@cpan.org> borrowed code from Marek Rouchal's
287 Pod::Find, which in turn heavily borrowed code from Nick Ing-Simmons'
288 PodToHtml.
289 Tim Jenness <t.jenness@jach.hawaii.edu> provided "find" and "con‐
291 tains_pod" to Pod::Find.
292
294 Pod::Simple, Pod::Perldoc
295perl v5.8.8 2003-11-02 Pod::Simple::Search(3)