NAME¶

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

SYNOPSIS¶

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

DESCRIPTION¶

Pod::Simple::Search is a class that you use for running searches for Pod files. An object of this class has several attributes (mostly options for controlling search options), and some methods for searching based on those attributes.

The way to use this class is to make a new object of this class, set any options, and then call one of the search options (probably "survey" or "find"). The sections below discuss the syntaxes for doing all that.

CONSTRUCTOR¶

This class provides the one constructor, called "new". It takes no parameters:

  use Pod::Simple::Search;
  my $search = Pod::Simple::Search->new;

ACCESSORS¶

This class defines several methods for setting (and, occasionally, reading) the contents of an object. With two exceptions (discussed at the end of this section), these attributes are just for controlling the way searches are carried out.

Note that each of these return $self when you call them as "$self->whatever(value)". That's so that you can chain together set-attribute calls like this:

  my $name2path =
    Pod::Simple::Search->new
    -> inc(0) -> verbose(1) -> callback(\&blab)
    ->survey(@there);

...which works exactly as if you'd done this:

  my $search = Pod::Simple::Search->new;
  $search->inc(0);
  $search->verbose(1);
  $search->callback(\&blab);
  my $name2path = $search->survey(@there);

$search->inc( true-or-false );

This attribute, if set to a true value, means that searches should implicitly add perl's @INC paths. This automatically considers paths specified in the "PERL5LIB" environment as this is prepended to @INC by the Perl interpreter itself. This attribute's default value is TRUE. 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 they're doing as they do it. This option may be useful for debugging a pod-related module. This attribute's 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 file's filespec, and its pod name. (For example: "("/etc/perljunk/File/Crunk.pm", "File::Crunk")" would be in @_.)

The callback routine's return value is not used for anything.

This attribute's 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 attribute's default value is false. You won't 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 interpreter's 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 won't 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 attribute's default value is false; and normally you won't need to turn it on.

$search->is_case_insensitive( true-or-false );

Pod::Simple::Search will by default internally make an assumption based on the underlying filesystem where the class file is found whether it is case insensitive or not.

If it is determined to be case insensitive, during survey() it may skip pod files/modules that happen to be equal to names it's already seen, ignoring case.

However, it's possible to have distinct files in different directories that intentionally has the same name, just differing in case, that should be reported. Hence, you may force the behavior by setting this to true or false.

$search->limit_re( some-regxp );

Setting this attribute (to a value that's 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 "$search->limit_glob("File::Find::R*")" is the same as the combination of the search options "$search->limit_re("^File::Find::R") -> dir_prefix("File::Find")".

Normally you don't 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 don't want to use a simple callback.

Normally you don't 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 object's "reach" and "done" methods are called like this:

  # Every time a file is being scanned for pod:
  $progress->reach($count, "Scanning $file");   ++$count;
  # And then at the end of the search:
  $progress->done("Noted $count Pod files total");
    

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.

MAIN SEARCH METHODS¶

Once you've 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.

SUPPORT¶

Questions or discussion about POD and Pod::Simple should be sent to the pod-people@perl.org mail list. Send an empty email to pod-people-subscribe@perl.org to subscribe.

This module is managed in an open GitHub repository, <https://github.com/perl-pod/pod-simple/>. Feel free to fork and contribute, or to clone <git://github.com/perl-pod/pod-simple.git> and send patches!

Patches against Pod::Simple are welcome. Please send bug reports to <bug-pod-simple@rt.cpan.org>.

COPYRIGHT AND DISCLAIMERS¶

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.

AUTHOR¶

Pod::Simple was created by Sean M. Burke <sburke@cpan.org> with code borrowed from Marek Rouchal's Pod::Find, which in turn heavily borrowed code from Nick Ing-Simmons' "PodToHtml".

But don't bother him, he's retired.

Pod::Simple is maintained by:

• Allison Randal "allison@perl.org"
• Hans Dieter Pearcey "hdp@cpan.org"
• David E. Wheeler "dwheeler@cpan.org"