{
"mode": "perldoc",
"parameter": "Pod::Simple::Search",
"section": "",
"url": "https://www.chedong.com/phpMan.php/perldoc/Pod%3A%3ASimple%3A%3ASearch/json",
"generated": "2026-06-03T02:35:34Z",
"synopsis": "use Pod::Simple::Search;\nmy $name2path = Pod::Simple::Search->new->limitglob('LWP::*')->survey;\nprint \"Looky see what I found: \",\njoin(' ', sort keys %$name2path), \"\\n\";\nprint \"LWPUA docs = \",\nPod::Simple::Search->new->find('LWP::UserAgent') || \"?\",\n\"\\n\";",
"sections": {
"NAME": {
"content": "Pod::Simple::Search - find POD documents in directory trees\n",
"subsections": []
},
"SYNOPSIS": {
"content": "use Pod::Simple::Search;\nmy $name2path = Pod::Simple::Search->new->limitglob('LWP::*')->survey;\nprint \"Looky see what I found: \",\njoin(' ', sort keys %$name2path), \"\\n\";\n\nprint \"LWPUA docs = \",\nPod::Simple::Search->new->find('LWP::UserAgent') || \"?\",\n\"\\n\";\n",
"subsections": []
},
"DESCRIPTION": {
"content": "Pod::Simple::Search is a class that you use for running searches for Pod files. An object of\nthis class has several attributes (mostly options for controlling search options), and some\nmethods for searching based on those attributes.\n\nThe way to use this class is to make a new object of this class, set any options, and then call\none of the search options (probably \"survey\" or \"find\"). The sections below discuss the syntaxes\nfor doing all that.\n",
"subsections": []
},
"CONSTRUCTOR": {
"content": "This class provides the one constructor, called \"new\". It takes no parameters:\n\nuse Pod::Simple::Search;\nmy $search = Pod::Simple::Search->new;\n",
"subsections": []
},
"ACCESSORS": {
"content": "This class defines several methods for setting (and, occasionally, reading) the contents of an\nobject. With two exceptions (discussed at the end of this section), these attributes are just\nfor controlling the way searches are carried out.\n\nNote that each of these return $self when you call them as \"$self->*whatever(value)*\". That's so\nthat you can chain together set-attribute calls like this:\n\nmy $name2path =\nPod::Simple::Search->new\n-> inc(0) -> verbose(1) -> callback(\\&blab)\n->survey(@there);\n\n...which works exactly as if you'd done this:\n\nmy $search = Pod::Simple::Search->new;\n$search->inc(0);\n$search->verbose(1);\n$search->callback(\\&blab);\nmy $name2path = $search->survey(@there);\n\n$search->inc( *true-or-false* );\nThis attribute, if set to a true value, means that searches should implicitly add perl's\n*@INC* paths. This automatically considers paths specified in the \"PERL5LIB\" environment as\nthis is prepended to *@INC* by the Perl interpreter itself. This attribute's default value\nis TRUE. If you want to search only specific directories, set $self->inc(0) before calling\n$inc->survey or $inc->find.\n\n$search->verbose( *nonnegative-number* );\nThis attribute, if set to a nonzero positive value, will make searches output (via \"warn\")\nnotes about what they're doing as they do it. This option may be useful for debugging a\npod-related module. This attribute's default value is zero, meaning that no \"warn\" messages\nare produced. (Setting verbose to 1 turns on some messages, and setting it to 2 turns on\neven more messages, i.e., makes the following search(es) even more verbose than 1 would make\nthem.)\n\n$search->limitglob( *some-glob-string* );\nThis option means that you want to limit the results just to items whose podnames match the\ngiven glob/wildcard expression. For example, you might limit your search to just \"LWP::*\",\nto search only for modules starting with \"LWP::*\" (but not including the module \"LWP\"\nitself); or you might limit your search to \"LW*\" to see only modules whose (full) names\nbegin with \"LW\"; or you might search for \"*Find*\" to search for all modules with \"Find\"\nsomewhere in their full name. (You can also use \"?\" in a glob expression; so \"DB?\" will\nmatch \"DBI\" and \"DBD\".)\n\n$search->callback( *\\&someroutine* );\nThis attribute means that every time this search sees a matching Pod file, it should call\nthis callback routine. The routine is called with two parameters: the current file's\nfilespec, and its pod name. (For example: \"(\"/etc/perljunk/File/Crunk.pm\", \"File::Crunk\")\"\nwould be in @.)\n\nThe callback routine's return value is not used for anything.\n\nThis attribute's default value is false, meaning that no callback is called.\n\n$search->laborious( *true-or-false* );\nUnless you set this attribute to a true value, Pod::Search will apply Perl-specific\nheuristics to find the correct module PODs quickly. This attribute's default value is false.\nYou won't normally need to set this to true.\n\nSpecifically: Turning on this option will disable the heuristics for seeing only files with\nPerl-like extensions, omitting subdirectories that are numeric but do *not* match the\ncurrent Perl interpreter's version ID, suppressing siteperl as a module hierarchy name,\netc.\n\n$search->recurse( *true-or-false* );\nUnless you set this attribute to a false value, Pod::Search will recurse into subdirectories\nof the search directories.\n\n$search->shadows( *true-or-false* );\nUnless you set this attribute to a true value, Pod::Simple::Search will consider only the\nfirst file of a given modulename as it looks thru the specified directories; that is, with\nthis option off, if Pod::Simple::Search has seen a \"somepathdir/Foo/Bar.pm\" already in this\nsearch, then it won't bother looking at a \"somelaterpathdir/Foo/Bar.pm\" later on in that\nsearch, because that file is merely a \"shadow\". But if you turn on \"$self->shadows(1)\", then\nthese \"shadow\" files are inspected too, and are noted in the pathname2podname return hash.\n\nThis attribute's default value is false; and normally you won't need to turn it on.\n\n$search->iscaseinsensitive( *true-or-false* );\nPod::Simple::Search will by default internally make an assumption based on the underlying\nfilesystem where the class file is found whether it is case insensitive or not.\n\nIf it is determined to be case insensitive, during survey() it may skip pod files/modules\nthat happen to be equal to names it's already seen, ignoring case.\n\nHowever, it's possible to have distinct files in different directories that intentionally\nhas the same name, just differing in case, that should be reported. Hence, you may force the\nbehavior by setting this to true or false.\n\n$search->limitre( *some-regxp* );\nSetting this attribute (to a value that's a regexp) means that you want to limit the results\njust to items whose podnames match the given regexp. Normally this option is not needed, and\nthe more efficient \"limitglob\" attribute is used instead.\n\n$search->dirprefix( *some-string-value* );\nSetting this attribute to a string value means that the searches should begin in the\nspecified subdirectory name (like \"Pod\" or \"File::Find\", also expressible as \"File/Find\").\nFor example, the search option \"$search->limitglob(\"File::Find::R*\")\" is the same as the\ncombination of the search options \"$search->limitre(\"^File::Find::R\") ->\ndirprefix(\"File::Find\")\".\n\nNormally you don't need to know about the \"dirprefix\" option, but I include it in case it\nmight prove useful for someone somewhere.\n\n(Implementationally, searching with limitglob ends up setting limitre and usually\ndirprefix.)\n\n$search->progress( *some-progress-object* );\nIf you set a value for this attribute, the value is expected to be an object (probably of a\nclass that you define) that has a \"reach\" method and a \"done\" method. This is meant for\nreporting progress during the search, if you don't want to use a simple callback.\n\nNormally you don't need to know about the \"progress\" option, but I include it in case it\nmight prove useful for someone somewhere.\n\nWhile a search is in progress, the progress object's \"reach\" and \"done\" methods are called\nlike this:\n\n# Every time a file is being scanned for pod:\n$progress->reach($count, \"Scanning $file\"); ++$count;\n\n# And then at the end of the search:\n$progress->done(\"Noted $count Pod files total\");\n\nInternally, we often set this to an object of class Pod::Simple::Progress. That class is\nprobably undocumented, but you may wish to look at its source.\n\n$name2path = $self->name2path;\nThis attribute is not a search parameter, but is used to report the result of \"survey\"\nmethod, as discussed in the next section.\n\n$path2name = $self->path2name;\nThis attribute is not a search parameter, but is used to report the result of \"survey\"\nmethod, as discussed in the next section.\n",
"subsections": []
},
"MAIN SEARCH METHODS": {
"content": "Once you've actually set any options you want (if any), you can go ahead and use the following\nmethods to search for Pod files in particular ways.\n\n\"$search->survey( @directories )\"\nThe method \"survey\" searches for POD documents in a given set of files and/or directories. This\nruns the search according to the various options set by the accessors above. (For example, if\nthe \"inc\" attribute is on, as it is by default, then the perl @INC directories are implicitly\nadded to the list of directories (if any) that you specify.)\n\nThe return value of \"survey\" is two hashes:\n\n\"name2path\"\nA hash that maps from each pod-name to the filespec (like \"Stuff::Thing\" =>\n\"/whatever/plib/Stuff/Thing.pm\")\n\n\"path2name\"\nA hash that maps from each Pod filespec to its pod-name (like\n\"/whatever/plib/Stuff/Thing.pm\" => \"Stuff::Thing\")\n\nBesides saving these hashes as the hashref attributes \"name2path\" and \"path2name\", calling this\nfunction also returns these hashrefs. In list context, the return value of \"$search->survey\" is\nthe list \"(\\%name2path, \\%path2name)\". In scalar context, the return value is \"\\%name2path\". Or\nyou can just call this in void context.\n\nRegardless of calling context, calling \"survey\" saves its results in its \"name2path\" and\n\"path2name\" attributes.\n\nE.g., when searching in $HOME/perl5lib, the file $HOME/perl5lib/MyModule.pm would get the POD\nname *MyModule*, whereas $HOME/perl5lib/Myclass/Subclass.pm would be *Myclass::Subclass*. The\nname information can be used for POD translators.\n\nOnly text files containing at least one valid POD command are found.\n\nIn verbose mode, a warning is printed if shadows are found (i.e., more than one POD file with\nthe same POD name is found, e.g. CPAN.pm in different directories). This usually indicates\nduplicate occurrences of modules in the *@INC* search path, which is occasionally inadvertent\n(but is often simply a case of a user's path dir having a more recent version than the system's\ngeneral path dirs in general.)\n\nThe options to this argument is a list of either directories that are searched recursively, or\nfiles. (Usually you wouldn't specify files, but just dirs.) Or you can just specify an\nempty-list, as in $name2path; with the \"inc\" option on, as it is by default.\n\nThe POD names of files are the plain basenames with any Perl-like extension (.pm, .pl, .pod)\nstripped, and path separators replaced by \"::\"'s.\n\nCalling Pod::Simple::Search->search(...) is short for Pod::Simple::Search->new->search(...).\nThat is, a throwaway object with default attribute values is used.\n\n\"$search->simplifyname( $str )\"\nThe method simplifyname is equivalent to basename, but also strips Perl-like extensions (.pm,\n.pl, .pod) and extensions like .bat, .cmd on Win32 and OS/2, or .com on VMS, respectively.\n\n\"$search->find( $pod )\"\n\"$search->find( $pod, @searchdirs )\"\nReturns the location of a Pod file, given a Pod/module/script name (like \"Foo::Bar\" or \"perlvar\"\nor \"perldoc\"), and an idea of what files/directories to look in. It searches according to the\nvarious options set by the accessors above. (For example, if the \"inc\" attribute is on, as it is\nby default, then the perl @INC directories are implicitly added to the list of directories (if\nany) that you specify.)\n\nThis returns the full path of the first occurrence to the file. Package names (eg 'A::B') are\nautomatically converted to directory names in the selected directory. Additionally, '.pm', '.pl'\nand '.pod' are automatically appended to the search as required. (So, for example, under Unix,\n\"A::B\" is converted to \"somedir/A/B.pm\", \"somedir/A/B.pod\", or \"somedir/A/B.pl\", as\nappropriate.)\n\nIf no such Pod file is found, this method returns undef.\n\nIf any of the given search directories contains a pod/ subdirectory, then it is searched.\n(That's how we manage to find perlfunc, for example, which is usually in pod/perlfunc in most\nPerl dists.)\n\nThe \"verbose\" and \"inc\" attributes influence the behavior of this search; notably, \"inc\", if\ntrue, adds @INC *and also $Config::Config{'scriptdir'}* to the list of directories to search.\n\nIt is common to simply say \"$filename = Pod::Simple::Search-> new ->find(\"perlvar\")\" so that\njust the @INC (well, and scriptdir) directories are searched. (This happens because the \"inc\"\nattribute is true by default.)\n\nCalling Pod::Simple::Search->find(...) is short for Pod::Simple::Search->new->find(...). That\nis, a throwaway object with default attribute values is used.\n\n\"$self->containspod( $file )\"\nReturns true if the supplied filename (not POD module) contains some Pod documentation.\n",
"subsections": []
},
"SUPPORT": {
"content": "Questions or discussion about POD and Pod::Simple should be sent to the pod-people@perl.org mail\nlist. Send an empty email to pod-people-subscribe@perl.org to subscribe.\n\nThis module is managed in an open GitHub repository, .\nFeel free to fork and contribute, or to clone and\nsend patches!\n\nPatches against Pod::Simple are welcome. Please send bug reports to\n.\n",
"subsections": []
},
"COPYRIGHT AND DISCLAIMERS": {
"content": "Copyright (c) 2002 Sean M. Burke.\n\nThis library is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\nThis program is distributed in the hope that it will be useful, but without any warranty;\nwithout even the implied warranty of merchantability or fitness for a particular purpose.\n",
"subsections": []
},
"AUTHOR": {
"content": "Pod::Simple was created by Sean M. Burke with code borrowed from Marek\nRouchal's Pod::Find, which in turn heavily borrowed code from Nick Ing-Simmons' \"PodToHtml\".\n\nBut don't bother him, he's retired.\n\nPod::Simple is maintained by:\n\n* Allison Randal \"allison@perl.org\"\n\n* Hans Dieter Pearcey \"hdp@cpan.org\"\n\n* David E. Wheeler \"dwheeler@cpan.org\"\n",
"subsections": []
}
},
"summary": "Pod::Simple::Search - find POD documents in directory trees",
"flags": [],
"examples": [],
"see_also": []
}