diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Pod::Simple::Search.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Pod::Simple::Search.3pm | 421 |
1 files changed, 421 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Pod::Simple::Search.3pm b/upstream/mageia-cauldron/man3pm/Pod::Simple::Search.3pm new file mode 100644 index 00000000..ff338932 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Pod::Simple::Search.3pm @@ -0,0 +1,421 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Pod::Simple::Search 3pm" +.TH Pod::Simple::Search 3pm 2023-11-28 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Pod::Simple::Search \- find POD documents in directory trees +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 4 +\& use Pod::Simple::Search; +\& my $name2path = Pod::Simple::Search\->new\->limit_glob(\*(AqLWP::*\*(Aq)\->survey; +\& print "Looky see what I found: ", +\& join(\*(Aq \*(Aq, sort keys %$name2path), "\en"; +\& +\& print "LWPUA docs = ", +\& Pod::Simple::Search\->new\->find(\*(AqLWP::UserAgent\*(Aq) || "?", +\& "\en"; +.Ve +.SH DESCRIPTION +.IX Header "DESCRIPTION" +\&\fBPod::Simple::Search\fR 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. +.PP +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 \f(CW\*(C`survey\*(C'\fR or \f(CW\*(C`find\*(C'\fR). The sections below discuss the +syntaxes for doing all that. +.SH CONSTRUCTOR +.IX Header "CONSTRUCTOR" +This class provides the one constructor, called \f(CW\*(C`new\*(C'\fR. +It takes no parameters: +.PP +.Vb 2 +\& use Pod::Simple::Search; +\& my $search = Pod::Simple::Search\->new; +.Ve +.SH ACCESSORS +.IX Header "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. +.PP +Note that each of these return \f(CW$self\fR when you call them as +\&\f(CW\*(C`$self\->\fR\f(CIwhatever(value)\fR\f(CW\*(C'\fR. That's so that you can chain +together set-attribute calls like this: +.PP +.Vb 4 +\& my $name2path = +\& Pod::Simple::Search\->new +\& \-> inc(0) \-> verbose(1) \-> callback(\e&blab) +\& \->survey(@there); +.Ve +.PP +\&...which works exactly as if you'd done this: +.PP +.Vb 5 +\& my $search = Pod::Simple::Search\->new; +\& $search\->inc(0); +\& $search\->verbose(1); +\& $search\->callback(\e&blab); +\& my $name2path = $search\->survey(@there); +.Ve +.ie n .IP "$search\->inc( \fItrue-or-false\fR );" 4 +.el .IP "\f(CW$search\fR\->inc( \fItrue-or-false\fR );" 4 +.IX Item "$search->inc( true-or-false );" +This attribute, if set to a true value, means that searches should +implicitly add perl's \fR\f(CI@INC\fR\fI\fR paths. This +automatically considers paths specified in the \f(CW\*(C`PERL5LIB\*(C'\fR environment +as this is prepended to \fI\fR\f(CI@INC\fR\fI\fR by the Perl interpreter itself. +This attribute's default value is \fBTRUE\fR. If you want to search +only specific directories, set \f(CW$self\fR\->\fBinc\fR\|(0) before calling +\&\f(CW$inc\fR\->survey or \f(CW$inc\fR\->find. +.ie n .IP "$search\->verbose( \fInonnegative-number\fR );" 4 +.el .IP "\f(CW$search\fR\->verbose( \fInonnegative-number\fR );" 4 +.IX Item "$search->verbose( nonnegative-number );" +This attribute, if set to a nonzero positive value, will make searches output +(via \f(CW\*(C`warn\*(C'\fR) 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 \f(CW\*(C`warn\*(C'\fR 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.) +.ie n .IP "$search\->limit_glob( \fIsome-glob-string\fR );" 4 +.el .IP "\f(CW$search\fR\->limit_glob( \fIsome-glob-string\fR );" 4 +.IX Item "$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".) +.ie n .IP "$search\->callback( \fI\e&some_routine\fR );" 4 +.el .IP "\f(CW$search\fR\->callback( \fI\e&some_routine\fR );" 4 +.IX Item "$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: \f(CW\*(C`("/etc/perljunk/File/Crunk.pm", "File::Crunk")\*(C'\fR would +be in \f(CW@_\fR.) +.Sp +The callback routine's return value is not used for anything. +.Sp +This attribute's default value is false, meaning that no callback +is called. +.ie n .IP "$search\->laborious( \fItrue-or-false\fR );" 4 +.el .IP "\f(CW$search\fR\->laborious( \fItrue-or-false\fR );" 4 +.IX Item "$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. +.Sp +Specifically: Turning on this option will disable the heuristics for +seeing only files with Perl-like extensions, omitting subdirectories +that are numeric but do \fInot\fR match the current Perl interpreter's +version ID, suppressing \fIsite_perl\fR as a module hierarchy name, etc. +.ie n .IP "$search\->recurse( \fItrue-or-false\fR );" 4 +.el .IP "\f(CW$search\fR\->recurse( \fItrue-or-false\fR );" 4 +.IX Item "$search->recurse( true-or-false );" +Unless you set this attribute to a false value, Pod::Search will +recurse into subdirectories of the search directories. +.ie n .IP "$search\->shadows( \fItrue-or-false\fR );" 4 +.el .IP "\f(CW$search\fR\->shadows( \fItrue-or-false\fR );" 4 +.IX Item "$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 \f(CW\*(C`somepathdir/Foo/Bar.pm\*(C'\fR already in this +search, then it won't bother looking at a \f(CW\*(C`somelaterpathdir/Foo/Bar.pm\*(C'\fR +later on in that search, because that file is merely a "shadow". But if +you turn on \f(CW\*(C`$self\->shadows(1)\*(C'\fR, then these "shadow" files are +inspected too, and are noted in the pathname2podname return hash. +.Sp +This attribute's default value is false; and normally you won't +need to turn it on. +.ie n .IP "$search\->is_case_insensitive( \fItrue-or-false\fR );" 4 +.el .IP "\f(CW$search\fR\->is_case_insensitive( \fItrue-or-false\fR );" 4 +.IX Item "$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. +.Sp +If it is determined to be case insensitive, during \fBsurvey()\fR it may +skip pod files/modules that happen to be equal to names it's already +seen, ignoring case. +.Sp +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. +.ie n .IP "$search\->limit_re( \fIsome-regxp\fR );" 4 +.el .IP "\f(CW$search\fR\->limit_re( \fIsome-regxp\fR );" 4 +.IX Item "$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 +\&\f(CW\*(C`limit_glob\*(C'\fR attribute is used instead. +.ie n .IP "$search\->dir_prefix( \fIsome-string-value\fR );" 4 +.el .IP "\f(CW$search\fR\->dir_prefix( \fIsome-string-value\fR );" 4 +.IX Item "$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 +\&\f(CW\*(C`$search\->limit_glob("File::Find::R*")\*(C'\fR +is the same as the combination of the search options +\&\f(CW\*(C`$search\->limit_re("^File::Find::R") \-> dir_prefix("File::Find")\*(C'\fR. +.Sp +Normally you don't need to know about the \f(CW\*(C`dir_prefix\*(C'\fR option, but I +include it in case it might prove useful for someone somewhere. +.Sp +(Implementationally, searching with limit_glob ends up setting limit_re +and usually dir_prefix.) +.ie n .IP "$search\->progress( \fIsome-progress-object\fR );" 4 +.el .IP "\f(CW$search\fR\->progress( \fIsome-progress-object\fR );" 4 +.IX Item "$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 +\&\f(CW\*(C`reach\*(C'\fR method and a \f(CW\*(C`done\*(C'\fR method. This is meant for reporting +progress during the search, if you don't want to use a simple +callback. +.Sp +Normally you don't need to know about the \f(CW\*(C`progress\*(C'\fR option, but I +include it in case it might prove useful for someone somewhere. +.Sp +While a search is in progress, the progress object's \f(CW\*(C`reach\*(C'\fR and +\&\f(CW\*(C`done\*(C'\fR methods are called like this: +.Sp +.Vb 2 +\& # 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"); +.Ve +.Sp +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. +.ie n .IP "$name2path = $self\->name2path;" 4 +.el .IP "\f(CW$name2path\fR = \f(CW$self\fR\->name2path;" 4 +.IX Item "$name2path = $self->name2path;" +This attribute is not a search parameter, but is used to report the +result of \f(CW\*(C`survey\*(C'\fR method, as discussed in the next section. +.ie n .IP "$path2name = $self\->path2name;" 4 +.el .IP "\f(CW$path2name\fR = \f(CW$self\fR\->path2name;" 4 +.IX Item "$path2name = $self->path2name;" +This attribute is not a search parameter, but is used to report the +result of \f(CW\*(C`survey\*(C'\fR method, as discussed in the next section. +.SH "MAIN SEARCH METHODS" +.IX Header "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. +.ie n .SS """$search\->survey( @directories )""" +.el .SS "\f(CW$search\->survey( @directories )\fP" +.IX Subsection "$search->survey( @directories )" +The method \f(CW\*(C`survey\*(C'\fR 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 \f(CW\*(C`inc\*(C'\fR attribute +is on, as it is by default, then the perl \f(CW@INC\fR directories are implicitly +added to the list of directories (if any) that you specify.) +.PP +The return value of \f(CW\*(C`survey\*(C'\fR is two hashes: +.ie n .IP """name2path""" 4 +.el .IP \f(CWname2path\fR 4 +.IX Item "name2path" +A hash that maps from each pod-name to the filespec (like +"Stuff::Thing" => "/whatever/plib/Stuff/Thing.pm") +.ie n .IP """path2name""" 4 +.el .IP \f(CWpath2name\fR 4 +.IX Item "path2name" +A hash that maps from each Pod filespec to its pod-name (like +"/whatever/plib/Stuff/Thing.pm" => "Stuff::Thing") +.PP +Besides saving these hashes as the hashref attributes +\&\f(CW\*(C`name2path\*(C'\fR and \f(CW\*(C`path2name\*(C'\fR, calling this function also returns +these hashrefs. In list context, the return value of +\&\f(CW\*(C`$search\->survey\*(C'\fR is the list \f(CW\*(C`(\e%name2path, \e%path2name)\*(C'\fR. +In scalar context, the return value is \f(CW\*(C`\e%name2path\*(C'\fR. +Or you can just call this in void context. +.PP +Regardless of calling context, calling \f(CW\*(C`survey\*(C'\fR saves +its results in its \f(CW\*(C`name2path\*(C'\fR and \f(CW\*(C`path2name\*(C'\fR attributes. +.PP +E.g., when searching in \fR\f(CI$HOME\fR\fI/perl5lib\fR, the file +\&\fI\fR\f(CI$HOME\fR\fI/perl5lib/MyModule.pm\fR would get the POD name \fIMyModule\fR, +whereas \fI\fR\f(CI$HOME\fR\fI/perl5lib/Myclass/Subclass.pm\fR would be +\&\fIMyclass::Subclass\fR. The name information can be used for POD +translators. +.PP +Only text files containing at least one valid POD command are found. +.PP +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. \fICPAN.pm\fR in +different directories). This usually indicates duplicate occurrences of +modules in the \fR\f(CI@INC\fR\fI\fR 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.) +.PP +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 +\&\f(CW$name2path\fR; with the \f(CW\*(C`inc\*(C'\fR option on, as it is by default. +.PP +The POD names of files are the plain basenames with any Perl-like +extension (.pm, .pl, .pod) stripped, and path separators replaced by +\&\f(CW\*(C`::\*(C'\fR's. +.PP +Calling Pod::Simple::Search\->search(...) is short for +Pod::Simple::Search\->new\->search(...). That is, a throwaway object +with default attribute values is used. +.ie n .SS """$search\->simplify_name( $str )""" +.el .SS "\f(CW$search\->simplify_name( $str )\fP" +.IX Subsection "$search->simplify_name( $str )" +The method \fBsimplify_name\fR is equivalent to \fBbasename\fR, but also +strips Perl-like extensions (.pm, .pl, .pod) and extensions like +\&\fI.bat\fR, \fI.cmd\fR on Win32 and OS/2, or \fI.com\fR on VMS, respectively. +.ie n .SS """$search\->find( $pod )""" +.el .SS "\f(CW$search\->find( $pod )\fP" +.IX Subsection "$search->find( $pod )" +.ie n .SS """$search\->find( $pod, @search_dirs )""" +.el .SS "\f(CW$search\->find( $pod, @search_dirs )\fP" +.IX Subsection "$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 \f(CW\*(C`inc\*(C'\fR attribute is on, as it is by default, then +the perl \f(CW@INC\fR directories are implicitly added to the list of +directories (if any) that you specify.) +.PP +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.) +.PP +If no such Pod file is found, this method returns undef. +.PP +If any of the given search directories contains a \fIpod/\fR subdirectory, +then it is searched. (That's how we manage to find \fIperlfunc\fR, +for example, which is usually in \fIpod/perlfunc\fR in most Perl dists.) +.PP +The \f(CW\*(C`verbose\*(C'\fR and \f(CW\*(C`inc\*(C'\fR attributes influence the behavior of this +search; notably, \f(CW\*(C`inc\*(C'\fR, if true, adds \f(CW@INC\fR \fIand also +\&\fR\f(CI$Config::Config\fR\fI{'scriptdir'}\fR to the list of directories to search. +.PP +It is common to simply say \f(CW\*(C`$filename = Pod::Simple::Search\-> new +\&\->find("perlvar")\*(C'\fR so that just the \f(CW@INC\fR (well, and scriptdir) +directories are searched. (This happens because the \f(CW\*(C`inc\*(C'\fR +attribute is true by default.) +.PP +Calling Pod::Simple::Search\->find(...) is short for +Pod::Simple::Search\->new\->find(...). That is, a throwaway object +with default attribute values is used. +.ie n .SS """$self\->contains_pod( $file )""" +.el .SS "\f(CW$self\->contains_pod( $file )\fP" +.IX Subsection "$self->contains_pod( $file )" +Returns true if the supplied filename (not POD module) contains some Pod +documentation. +.SH SUPPORT +.IX Header "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. +.PP +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! +.PP +Patches against Pod::Simple are welcome. Please send bug reports to +<bug\-pod\-simple@rt.cpan.org>. +.SH "COPYRIGHT AND DISCLAIMERS" +.IX Header "COPYRIGHT AND DISCLAIMERS" +Copyright (c) 2002 Sean M. Burke. +.PP +This library is free software; you can redistribute it and/or modify it +under the same terms as Perl itself. +.PP +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. +.SH AUTHOR +.IX Header "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' \f(CW\*(C`PodToHtml\*(C'\fR. +.PP +But don't bother him, he's retired. +.PP +Pod::Simple is maintained by: +.IP \(bu 4 +Allison Randal \f(CW\*(C`allison@perl.org\*(C'\fR +.IP \(bu 4 +Hans Dieter Pearcey \f(CW\*(C`hdp@cpan.org\*(C'\fR +.IP \(bu 4 +David E. Wheeler \f(CW\*(C`dwheeler@cpan.org\*(C'\fR |