内容

名称

Pod::Simple::Search - 在目录树中查找 POD 文档

语法

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

说明

Pod::Simple::Search 是一个用于运行 Pod 文件搜索的类。此类的对象具有多个属性（主要用于控制搜索选项），以及一些用于根据这些属性进行搜索的方法。

使用此类的方法是创建一个此类的新对象，设置任何选项，然后调用其中一个搜索选项（可能是 survey 或 find）。以下各节讨论了执行所有这些操作的语法。

构造函数

此类提供一个名为 new 的构造函数。它不接受任何参数

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

访问器

此类定义了多个方法，用于设置（以及偶尔读取）对象的内容。除了本节末尾讨论的两个例外情况外，这些属性仅用于控制搜索执行方式。

请注意，当您将它们调用为 $self->whatever(value) 时，每个方法都会返回 $self。这样，您可以将设置属性的调用链接在一起，如下所示

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

...其工作方式与您执行以下操作完全相同

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

如果将此属性设置为真值，则意味着搜索应隐式添加 perl 的 @INC 路径。这会自动考虑 PERL5LIB 环境中指定的路径，因为 Perl 解释器本身会将其预置到 @INC。此属性的默认值为 TRUE。如果您只想搜索特定目录，请在调用 $inc->survey 或 $inc->find 之前设置 $self->inc(0)。

$search->verbose( nonnegative-number );

如果将此属性设置为非零正值，则搜索将输出（通过 warn）有关其执行操作的说明。此选项可能有助于调试与 pod 相关的模块。此属性的默认值为零，这意味着不会生成 warn 消息。（将 verbose 设置为 1 会打开一些消息，而将其设置为 2 会打开更多消息，即，使以下搜索比 1 更详细。）

$search->limit_glob( some-glob-string );

此选项意味着您只想将结果限制为其 pod 名称与给定的 glob/通配符表达式匹配的项。例如，您可以将搜索限制为仅“LWP::*”，以仅搜索以“LWP::*”开头的模块（但不包括模块“LWP”本身）；或者您可以将搜索限制为“LW*”，以仅查看以“LW”开头的（完整）名称的模块；或者您可以搜索“*Find*”，以搜索其完整名称中某个位置带有“Find”的所有模块。（您还可以在 glob 表达式中使用“?”；因此“DB?”将匹配“DBI”和“DBD”。）

$search->callback( \&some_routine );

此属性意味着，每当此搜索看到匹配的 Pod 文件时，它都应调用此回调例程。该例程使用两个参数调用：当前文件的规范和其 pod 名称。（例如：("/etc/perljunk/File/Crunk.pm", "File::Crunk") 将在 @_ 中。）

回调例程的返回值不会用于任何用途。

此属性的默认值为 false，表示不调用回调。

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

除非将此属性设置为 true 值，否则 Pod::Search 将应用特定于 Perl 的启发式方法来快速查找正确的模块 POD。此属性的默认值为 false。通常不需要将其设置为 true。

具体来说：启用此选项将禁用仅查看具有类 Perl 扩展名的文件、忽略数字子目录（但与当前 Perl 解释器的版本 ID 不匹配）、禁止 site_perl 作为模块层次结构名称等的启发式方法。

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

除非将此属性设置为 false 值，否则 Pod::Search 将递归进入搜索目录的子目录。

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

除非将此属性设置为 true 值，否则 Pod::Simple::Search 在查看指定目录时，只会考虑给定模块名的第一个文件；也就是说，如果禁用了此选项，则如果 Pod::Simple::Search 已在此搜索中看到 somepathdir/Foo/Bar.pm，那么它将不会在稍后的搜索中查看 somelaterpathdir/Foo/Bar.pm，因为该文件只是一个“影子”。但如果启用 $self->shadows(1)，则也会检查这些“影子”文件，并在 pathname2podname 返回哈希中记录它们。

此属性的默认值为 false；通常不需要启用它。

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

默认情况下，Pod::Simple::Search 将根据找到类文件的基础文件系统来内部做出假设，即文件系统是否区分大小写。

如果确定文件系统区分大小写，则在 survey() 期间，它可能会跳过与已看到的名称相等的 pod 文件/模块，而忽略大小写。

然而，不同的目录中可能存在名称相同但大小写不同的不同文件，应对此类情况进行报告。因此，您可以通过将此项设为 true 或 false 来强制执行此行为。

$search->limit_re( some-regxp );

设置此属性（为正则表达式值）表示您希望将结果仅限制为 pod 名称与给定正则表达式匹配的项。通常不需要此选项，而是使用效率更高的 limit_glob 属性。

$search->dir_prefix( some-string-value );

将此属性设置为字符串值表示搜索应从指定的子目录名称（如“Pod”或“File::Find”，也可表示为“File/Find”）开始。例如，搜索选项 $search->limit_glob("File::Find::R*") 与搜索选项 $search->limit_re("^File::Find::R") -> dir_prefix("File::Find") 的组合相同。

通常您不需要了解 dir_prefix 选项，但我将其包含在内，以防它对某人有帮助。

（在实现上，使用 limit_glob 进行搜索最终会设置 limit_re，通常还会设置 dir_prefix。）

$search->progress( some-progress-object );

如果您为此属性设置了一个值，则该值应为一个对象（可能属于您定义的类），该对象具有 reach 方法和 done 方法。如果不想使用简单的回调，则此方法用于报告搜索期间的进度。

通常您不需要了解 progress 选项，但我将其包含在内，以防它对某人有帮助。

在搜索进行期间，会像这样调用进度对象的 reach 和 done 方法

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

在内部，我们通常将此项设置为 Pod::Simple::Progress 类的对象。该类可能未记录，但您可能希望查看其源代码。

$name2path = $self->name2path;

此属性不是搜索参数，但用于报告 survey 方法的结果，如下一节所述。

$path2name = $self->path2name;

此属性不是搜索参数，但用于报告 survey 方法的结果，如下一节所述。

主要搜索方法

一旦你设置了任何你想要的选项（如果有的话），你可以继续使用以下方法以特定方式搜索 Pod 文件。

$search->survey( @directories )

方法 survey 在给定的一组文件和/或目录中搜索 POD 文档。这会根据上面访问器设置的各种选项运行搜索。（例如，如果 inc 属性已开启（默认情况下已开启），那么 perl @INC 目录会隐式添加到你指定的目录（如果有的话）列表中。）

survey 的返回值是两个哈希表

name2path

一个哈希表，它将每个 pod 名称映射到文件规范（例如“Stuff::Thing” => “/whatever/plib/Stuff/Thing.pm”）

path2name

一个哈希表，它将每个 Pod 文件规范映射到它的 pod 名称（例如“/whatever/plib/Stuff/Thing.pm” => “Stuff::Thing”）

除了将这些哈希表保存为哈希引用属性 name2path 和 path2name 之外，调用此函数还会返回这些哈希引用。在列表上下文中，$search->survey 的返回值是列表 (\%name2path, \%path2name)。在标量上下文中，返回值是 \%name2path。或者你也可以在无上下文中调用它。

无论调用上下文如何，调用 survey 都会将它的结果保存在它的 name2path 和 path2name 属性中。

例如，在 $HOME/perl5lib 中搜索时，文件 $HOME/perl5lib/MyModule.pm 将获得 POD 名称 MyModule，而 $HOME/perl5lib/Myclass/Subclass.pm 将是 Myclass::Subclass。名称信息可用于 POD 翻译器。

只会找到包含至少一个有效 POD 命令的文本文件。

在详细模式下，如果找到阴影（即找到具有相同 POD 名称的多个 POD 文件，例如不同目录中的 CPAN.pm），则会打印警告。这通常表示 @INC 搜索路径中模块的重复出现，这偶尔是无意的（但通常只是用户路径目录比系统的一般路径目录具有较新版本的情况）。

此参数的选项是递归搜索的目录或文件的列表。（通常你不会指定文件，而只是目录。）或者你可以指定一个空列表，就像 $name2path 中那样；默认情况下，inc 选项已启用。

文件的 POD 名称是剥离了任何 Perl 扩展（.pm、.pl、.pod）的普通基本名称，并且路径分隔符替换为 ::。

调用 Pod::Simple::Search->search(...) 等同于 Pod::Simple::Search->new->search(...)。也就是说，使用具有默认属性值的临时对象。

$search->simplify_name( $str )

方法 simplify_name 等同于 basename，但也会剥离 Perl 扩展（.pm、.pl、.pod）以及 Win32 和 OS/2 上的 .bat、.cmd 等扩展，或 VMS 上的 .com 扩展。

$search->find( $pod )

$search->find( $pod, @search_dirs )

给定一个 Pod/模块/脚本名称（如 "Foo::Bar" 或 "perlvar" 或 "perldoc"），以及要查找的文件/目录的思路，返回 Pod 文件的位置。它根据上述访问器设置的各种选项进行搜索。（例如，如果 inc 属性已启用（默认情况下已启用），那么 perl @INC 目录将隐式添加到你指定的目录（如果有）列表中。）

这将返回文件第一次出现的完整路径。包名称（例如“A::B”）会自动转换为选定目录中的目录名称。此外，'.pm'、'.pl' 和 '.pod' 会根据需要自动追加到搜索中。（因此，例如，在 Unix 下，“A::B” 会根据需要转换为 “somedir/A/B.pm”、“somedir/A/B.pod” 或 “somedir/A/B.pl”。）

如果未找到此类 Pod 文件，此方法将返回未定义。

如果给定的任何搜索目录包含 pod/ 子目录，那么将对其进行搜索。（例如，这就是我们设法找到 perlfunc 的方式，它通常位于大多数 Perl dist 中的 pod/perlfunc 中。）

verbose 和 inc 属性会影响此搜索的行为；值得注意的是，如果 inc 为 true，则会将 @INC 和 $Config::Config{'scriptdir'} 添加到要搜索的目录列表中。

通常只需说 $filename = Pod::Simple::Search-> new ->find("perlvar")，这样只会搜索 @INC（当然还有 scriptdir）目录。（之所以会这样，是因为 inc 属性默认情况下为 true。）

调用 Pod::Simple::Search->find(...) 等同于 Pod::Simple::Search->new->find(...)。也就是说，使用具有默认属性值的临时对象。

$self->contains_pod( $file )

如果提供的文件名（非 POD 模块）包含一些 Pod 文档，则返回 true。

支持

有关 POD 和 Pod::Simple 的问题或讨论应发送到 [email protected] 邮件列表。发送一封空邮件到 [email protected] 以订阅。

此模块在开放的 GitHub 存储库中进行管理，https://github.com/perl-pod/pod-simple/。随时进行分叉和贡献，或克隆 git://github.com/perl-pod/pod-simple.git 并发送补丁！

欢迎针对 Pod::Simple 的补丁。请将错误报告发送至 <[email protected]>。

版权和免责声明

版权所有 (c) 2002 Sean M. Burke。

此库是免费软件；您可以在与 Perl 本身相同的条款下重新分发和/或修改它。

本程序的发布基于它将是有用的希望，但没有任何保证；甚至没有对适销性或针对特定用途的适用性的默示保证。

作者

Pod::Simple 由 Sean M. Burke <[email protected]> 创建，其代码借鉴了 Marek Rouchal 的 Pod::Find，而后者又大量借鉴了 Nick Ing-Simmons 的 PodToHtml。

不过别烦他，他已经退休了。

Pod::Simple 由以下人员维护