|$search->inc( true-or-false );||This attribute, if set to a true value, means that searches should implicitly add perls @INC paths. This automatically considers paths specified in the PERL5LIB environment as this is prepended to @INC by the Perl interpreter itself. This attributes default value is <B>TRUEB>. If you want to search only specific directories, set $self->inc(0) before calling $inc->survey or $inc->find.|
|$search->verbose( nonnegative-number );||This attribute, if set to a nonzero positive value, will make searches output (via warn) notes about what theyre doing as they do it. This option may be useful for debugging a pod-related module. This attributes 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( some-glob-string );||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( \&some_routine );||
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 files filespec, and its pod name.
(For example: ("/etc/perljunk/File/Crunk.pm", "File::Crunk") would
be in @_.)
The callback routines return value is not used for anything.
This attributes default value is false, meaning that no callback is called.
|$search->laborious( true-or-false );||
Unless you set this attribute to a true value, Pod::Search will
apply Perl-specific heuristics to find the correct module PODs quickly.
This attributes default value is false. You wont 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 not match the current Perl interpreters version ID, suppressing site_perl as a module hierarchy name, etc.
|$search->recurse( true-or-false );||Unless you set this attribute to a false value, Pod::Search will recurse into subdirectories of the search directories.|
|$search->shadows( true-or-false );||
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 wont 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 attributes default value is false; and normally you wont need to turn it on.
|$search->limit_re( some-regxp );||Setting this attribute (to a value thats 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( some-string-value );||
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
is the same as the combination of the search options
$search->limit_re("^File::Find::R") -> dir_prefix("File::Find").
Normally you dont 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( some-progress-object );||
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 dont want to use a simple
Normally you dont 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 objects reach and done methods are called like this:
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.|
Once youve 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.
CW$search->survey( @directories )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:
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.
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)
Regardless of calling context, calling survey saves its results in its name2path and path2name attributes.
E.g., when searching in $HOME/perl5lib, the file $HOME/perl5lib/MyModule.pm would get the POD name MyModule, whereas $HOME/perl5lib/Myclass/Subclass.pm would be Myclass::Subclass. 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. CPAN.pm in different directories). This usually indicates duplicate occurrences of modules in the @INC search path, which is occasionally inadvertent (but is often simply a case of a users path dir having a more recent version than the systems general path dirs in general.)
The options to this argument is a list of either directories that are searched recursively, or files. (Usually you wouldnt 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.
CW$search->simplify_name( $str )The method <B>simplify_nameB> is equivalent to <B>basenameB>, but also strips Perl-like extensions (.pm, .pl, .pod) and extensions like .bat, .cmd on Win32 and OS/2, or .com on VMS, respectively.
CW$search->find( $pod )
CW$search->find( $pod, @search_dirs )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.
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.
CW$self->contains_pod( $file )Returns true if the supplied filename (not POD module) contains some Pod documentation.
Questions or discussion about POD and Pod::Simple should be sent to the email@example.com mail list. Send an empty email to firstname.lastname@example.org to subscribe.
This module is managed in an open GitHub repository, <https://github.com/theory/pod-simple/>. Feel free to fork and contribute, or to clone <git://github.com/theory/pod-simple.git> and send patches!
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.
Pod::Simple was created by Sean M. Burke <email@example.com> with code borrowed from Marek Rouchals Pod::Find, which in turn heavily borrowed code from Nick Ing-Simmons PodToHtml.
But dont bother him, hes retired.
Pod::Simple is maintained by:
o Allison Randal firstname.lastname@example.org o Hans Dieter Pearcey email@example.com o David E. Wheeler firstname.lastname@example.org
|perl v5.20.3||POD::SIMPLE::SEARCH (3)||2015-02-23|