pod::simple::search.3

视频监控网络部分的协议ddns,的模块的实现代码,请大家大胆指正.

names begin with \*(L"\s-1LW\s0\*(R"; or you might search for \*(L"*Find*\*(R" to search for
all modules with \*(L"Find\*(R" somewhere in their full name. (You can also use
\&\*(L"?\*(R" in a glob expression; so \*(L"\s-1DB\s0?\*(R" will match \*(L"\s-1DBI\s0\*(R" and \*(L"\s-1DBD\s0\*(R".)
.ie n .IP "$search\fR\->callback( \fI\e&some_routine );" 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\fR\->laborious( \fItrue-or-false );" 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 \s-1ID\s0, suppressing \fIsite_perl\fR as a module hierarchy name, etc.
.ie n .IP "$search\fR\->shadows( \fItrue-or-false );" 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 \*(L"shadow\*(R". But if
you turn on \f(CW\*(C`$self\->shadows(1)\*(C'\fR, then these \*(L"shadow\*(R" 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\fR\->limit_re( \fIsome-regxp );" 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\fR\->dir_prefix( \fIsome-string-value );" 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 \*(L"Pod\*(R" or \*(L"File::Find\*(R",
also expressable as \*(L"File/Find\*(R"). 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\fR\->progress( \fIsome-progress-object );" 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\fR = \f(CW$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\fR = \f(CW$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 .Sh """$search\->survey( @directories )"""
.el .Sh "\f(CW$search\->survey( @directories )\fP"
.IX Subsection "$search->survey( @directories )"
The method \f(CW\*(C`survey\*(C'\fR searches for \s-1POD\s0 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
\&\*(L"Stuff::Thing\*(R" => \*(L"/whatever/plib/Stuff/Thing.pm\*(R")
.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
\&\*(L"/whatever/plib/Stuff/Thing.pm\*(R" => \*(L"Stuff::Thing\*(R")
.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 \fI\f(CI$HOME\fI/perl5lib\fR, the file
\&\fI\f(CI$HOME\fI/perl5lib/MyModule.pm\fR would get the \s-1POD\s0 name \fIMyModule\fR,
whereas \fI\f(CI$HOME\fI/perl5lib/Myclass/Subclass.pm\fR would be
\&\fIMyclass::Subclass\fR. The name information can be used for \s-1POD\s0
translators.
.PP
Only text files containing at least one valid \s-1POD\s0 command are found.
.PP
In verbose mode, a warning is printed if shadows are found (i.e., more
than one \s-1POD\s0 file with the same \s-1POD\s0 name is found, e.g. \fI\s-1CPAN\s0.pm\fR in
different directories).  This usually indicates duplicate occurrences of
modules in the \fI\f(CI@INC\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, teh
.PP
The \s-1POD\s0 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 .Sh """$search\->simplify_name( $str )"""
.el .Sh "\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 \s-1OS/2\s0, or \fI.com\fR on \s-1VMS\s0, respectively.
.ie n .Sh """$search\->find( $pod )"""
.el .Sh "\f(CW$search\->find( $pod )\fP"
.IX Subsection "$search->find( $pod )"
.ie n .Sh """$search\->find( $pod, @search_dirs )"""
.el .Sh "\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 \*(L"Foo::Bar\*(R" or \*(L"perlvar\*(R" or \*(L"perldoc\*(R"), 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, \*(L"A::B\*(R" is converted to \*(L"somedir/A/B.pm\*(R",
\&\*(L"somedir/A/B.pod\*(R", or \*(L"somedir/A/B.pl\*(R", 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
\&\f(CI$Config::Config\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 .Sh """$self\->contains_pod( $file )"""
.el .Sh "\f(CW$self\->contains_pod( $file )\fP"
.IX Subsection "$self->contains_pod( $file )"
Returns true if the supplied filename (not \s-1POD\s0 module) contains some Pod
documentation.
.SH "AUTHOR"
.IX Header "AUTHOR"
Sean M. Burke <[e-mail]>
borrowed code from
Marek Rouchal's Pod::Find, which in turn
heavily borrowed code from Nick Ing\-Simmons' PodToHtml.
.PP
Tim Jenness <[e-mail]> provided
\&\f(CW\*(C`find\*(C'\fR and \f(CW\*(C`contains_pod\*(C'\fR to Pod::Find.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Pod::Simple, Pod::Perldoc