Pod::Simple::Search man page on Archlinux

Man page or keyword search:  
man Server   11224 pages
apropos Keyword Search (all sections)
Output format
Archlinux logo
[printable version]

Pod::Simple::Search(3pePerl Programmers Reference GuPod::Simple::Search(3perl)

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->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->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 expressable 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.

   "$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:

       "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")

       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.

       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 user's path dir having a more recent
       version than the system's general path dirs in general.)

       The options to this argument is a list of either directories that are
       searched recursively, or files.	(Usually you wouldn't 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, teh

       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.

   "$search->simplify_name( $str )"
       The method simplify_name is equivalent to basename, but also strips
       Perl-like extensions (.pm, .pl, .pod) and extensions like .bat, .cmd on
       Win32 and OS/2, or .com on VMS, respectively.

   "$search->find( $pod )"
   "$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.

       If any of the given search directories contains a pod/ subdirectory,
       then it is searched.  (That's how we manage to find perlfunc, for
       example, which is usually in pod/perlfunc in most Perl dists.)

       The "verbose" and "inc" attributes influence the behavior of this
       search; notably, "inc", if true, adds @INC and also
       $Config::Config{'scriptdir'} to the list of directories to search.

       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.

   "$self->contains_pod( $file )"
       Returns true if the supplied filename (not POD module) contains some
       Pod documentation.  =head1 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/theory/pod-simple/>. Feel free to fork and
       contribute, or to clone <git://github.com/theory/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"

perl v5.18.2			  2013-11-14	    Pod::Simple::Search(3perl)
[top]

List of man pages available for Archlinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net