内容

名称

Pod::Simple - 解析 Pod 的框架

概要

TODO

描述

Pod::Simple 是一个 Perl 库，用于解析 Pod（“普通文档”）标记语言中的文本，该语言通常用于编写 Perl 及其模块的文档。Pod 格式在 perlpod 中解释；最常见的格式化程序称为 perldoc。

如果您的 Pod 包含非 ASCII 字符，请务必阅读 "编码" 部分。

Pod 格式化程序可以使用 Pod::Simple 来解析 Pod 文档并将它们渲染成纯文本、HTML 或其他任何格式。通常，此类格式化程序将是 Pod::Simple 的子类，因此它们将继承其方法，例如 parse_file。但请注意，Pod::Simple 不理解也不正确地解析 Perl 本身，因此，如果您有一个包含 Perl 程序的文件，该程序包含一个多行引用的字符串，其中包含看起来像 pod 的行，Pod::Simple 会将它们视为 pod。如果文件将这些内容改为缩进的 here 文档，则可以避免这种情况。

如果您只是因为要使用 Pod 处理子类而阅读本文档，那么本文档（加上子类的文档）可能就是您需要阅读的所有内容。

如果您正在阅读本文档是因为您想编写一个格式化程序子类，请继续阅读本文档，然后阅读 Pod::Simple::Subclassing，然后可能还需要阅读 perlpodspec（其中一些是针对解析器编写者的，但大部分是针对格式化程序编写者的笔记）。

主要方法

$parser = SomeClass->new();

这将返回一个新的解析器对象，其中 SomeClass 是 Pod::Simple 的子类。

$parser->output_fh( *OUT );

这将设置 $parser 输出将写入的文件句柄。您可以传递 *STDOUT 或 *STDERR，否则您可能应该执行以下操作

my $outfile = "output.txt";
open TXTOUT, ">$outfile" or die "Can't write to $outfile: $!";
$parser->output_fh(*TXTOUT);

...在您调用 $parser->parse_whatever 方法之前。

$parser->output_string( \$somestring );

这将设置 $parser 输出将发送到的字符串，而不是任何文件句柄。

$parser->parse_file( $some_filename );
$parser->parse_file( *INPUT_FH );

这将读取您指定的文件（或文件句柄）的 Pod 内容，并使用该 $parser 对象对其进行处理，根据 $parser 类的工作方式以及您为该 $parser 对象设置的解析器选项。

$parser->parse_string_document( $all_content );

这与 parse_file 类似，只是它不是从文件读取 Pod 内容，而是从您已在内存中的字符串读取。

$parser->parse_lines( ...@lines..., undef );

这将处理 @lines 中的各行（其中每个列表项必须是已定义的值，并且必须包含正好一行内容 - 因此不允许像 "foo\nbar" 这样的项）。最后的 undef 用于指示正在解析的文档的结束。

其他 parser_whatever 方法旨在每个 $parser 对象仅调用一次；但 parse_lines 可以根据需要在每个 $parser 对象中调用多次，只要最后一个调用（并且只有最后一个调用）以 undef 值结束。

$parser->content_seen

仅当此文档已看到任何实际内容时，此方法才返回 true。如果文档包含内容，但未使用任何 Pod 标记，则返回 false。

SomeClass->filter( $filename );
SomeClass->filter( *INPUT_FH );
SomeClass->filter( \$document_content );

这是一个快捷方法，用于创建新的解析器对象，将输出句柄设置为 STDOUT，然后处理指定的文件（或文件句柄，或内存中的文档）。这对于像这样的单行代码非常方便

perl -MPod::Simple::Text -e "Pod::Simple::Text->filter('thingy.pod')"

辅助方法

这些方法中的一些可能对一般用户和格式化程序编写者都很有用。

请注意，这里的一般模式是访问器方法使用 $value = $parser->attribute 读取属性的值，并使用 $parser->attribute(newvalue) 设置属性的值。对于每个访问器，我通常只提及一种语法，根据我认为您最有可能使用的语法。

$parser->parse_characters( SOMEVALUE )

Pod 解析器通常期望读取字节，并根据 Pod 源代码中的 =encoding 声明将这些字节转换为字符。将此选项设置为 true 值以指示 Pod 源代码已经是 Perl 字符流。这告诉解析器忽略任何 =encoding 命令并跳过所有涉及解码字节的代码路径。

$parser->no_whining( SOMEVALUE )

如果将此属性设置为 true 值，您将抑制解析器对 Pod 编码中不规则性的抱怨。默认情况下，此属性的值为 false，这意味着将报告不规则性。

请注意，将此属性设置为 true 不会抑制关于很少发生的不可恢复错误的一两类抱怨。

$parser->no_errata_section( SOMEVALUE )

如果将此属性设置为 true 值，您将阻止解析器在文档末尾生成“POD ERRORS”部分。默认情况下，此属性的值为 false，这意味着将根据需要生成错误信息部分。

$parser->complain_stderr( SOMEVALUE )

如果将此属性设置为 true 值，它将向 STDERR 发送解析错误报告。默认情况下，此属性的值为 false，这意味着不会向 STDERR 发送任何输出。

设置 complain_stderr 也会设置 no_errata_section。

$parser->source_filename

此方法返回此解析器对象被设置为读取的文件名。

$parser->doc_has_started

如果 $parser 已从源读取，并且已看到其中的 Pod 内容，则此方法返回 true。

$parser->source_dead

如果 $parser 已从源读取，并且已到达该源的末尾，则此方法返回 true。

$parser->strip_verbatim_indent( SOMEVALUE )

Perlpod 规范中关于 Verbatim 段落的描述是“应完全复制...”，这意味着您用来缩进 verbatim 块的空白将保留在输出中。这对于 HTML 等输出可能很烦人，因为该空白将保留在每一行的前面。这是一个不幸的情况，语法变成了语义。

如果您正在解析的 POD 遵循一致的缩进策略，则可以从 verbatim 块的每一行的开头删除此类缩进。此方法告诉 Pod::Simple 要删除什么。对于两个空格缩进，您将使用

$parser->strip_verbatim_indent('  ');

对于制表符缩进，您将使用制表符字符

$parser->strip_verbatim_indent("\t");

如果 POD 对 verbatim 块的缩进不一致，但您已经找到了一个启发式方法来确定特定 verbatim 块的缩进程度，则可以传递一个代码引用。代码引用将使用一个参数执行，该参数是 verbatim 块中所有行的数组引用，并且应返回要从每一行中删除的值。例如，如果您决定可以使用 verbatim 块的第一行来设置其余块的缩进标准，则可以查看第一行并返回相应的值，如下所示

$new->strip_verbatim_indent(sub {
    my $lines = shift;
    (my $indent = $lines->[0]) =~ s/\S.*//;
    return $indent;
});

如果您希望单独处理每一行，也可以这样做，只需在代码引用中就地转换它们并返回 undef 即可。假设您不希望任何行缩进。您可以执行以下操作

$new->strip_verbatim_indent(sub {
    my $lines = shift;
    sub { s/^\s+// for @{ $lines },
    return undef;
});
$parser->expand_verbatim_tabs( n )

默认值：8

如果在删除 verbatim 块中的任何缩进后，仍然存在制表符，则此方法调用指示如何处理它们。0 表示将它们保留为制表符，任何其他数字都表示每个制表符都将被转换为每 n 列都有制表位。

这与其他方法无关（除了它在任何逐字输入剥离完成之后运行）。

与其他方法一样，输入参数未经过效性检查。undef 或包含非数字字符的效果与 8 相同。

三级方法

$parser->abandon_output_fh()

取消输出到文件句柄。$parser 读取的任何 POD 不会受到影响。

$parser->abandon_output_string()

取消输出到输出字符串。$parser 读取的任何 POD 不会受到影响。

$parser->accept_code( @codes )

accept_codes 的别名。

$parser->accept_codes( @codes )

允许 $parser 接受 "perlpod 中的格式化代码" 列表。这可用于实现用户定义的代码。

$parser->accept_directive_as_data( @directives )

允许 $parser 接受数据段落指令列表。指令是 "perlpod 中的命令段落" 的标签。数据段落是由 =begin/=for/=end 指令分隔的段落。这可用于实现用户定义的指令。

$parser->accept_directive_as_processed( @directives )

允许 $parser 接受已处理段落指令列表。指令是 "perlpod 中的命令段落" 的标签。已处理段落也称为 "perlpod 中的普通段落"。这可用于实现用户定义的指令。

$parser->accept_directive_as_verbatim( @directives )

允许 $parser 接受 "perlpod 中的逐字段落" 指令列表。指令是 "perlpod 中的命令段落" 的标签。这可用于实现用户定义的指令。

$parser->accept_target( @targets )

是 accept_targets 的别名。

$parser->accept_target_as_text( @targets )

是 accept_targets_as_text 的别名。

$parser->accept_targets( @targets )

接受 POD 中 =begin/=for/=end 部分的目标。

$parser->accept_targets_as_text( @targets )

接受应该被解析为 POD 的 =begin/=for/=end 部分的目标。有关详细信息，请参阅 "perlpodspec 中的关于数据段落"。

$parser->any_errata_seen()

用于检查是否看到了任何勘误。

示例

die "too many errors\n" if $parser->any_errata_seen();
$parser->errata_seen()

返回所有已看到的勘误的哈希引用，包括抱怨和尖叫。哈希引用的键是行号，值是该行错误的数组引用。

示例

if ( $parser->any_errata_seen() ) {
   $logger->log( $parser->errata_seen() );
}
$parser->detected_encoding()

返回与 =encoding 相对应的编码，但前提是编码被识别并处理。

$parser->encoding()

返回文档的编码，即使编码没有被正确处理。

$parser->parse_from_file( $source, $to )

从 $source 文件解析到 $to 文件。类似于 "Pod::Parser 中的 parse_from_file"。

$parser->scream( @error_messages )

记录无法忽略的错误。

$parser->unaccept_code( @codes )

是 unaccept_codes 的别名。

$parser->unaccept_codes( @codes )

从解析中删除 @codes 作为有效代码。

$parser->unaccept_directive( @directives )

是 unaccept_directives 的别名。

$parser->unaccept_directives( @directives )

将 @directives 从解析的有效指令中移除。

$parser->unaccept_target( @targets )

是 unaccept_targets 的别名。

$parser->unaccept_targets( @targets )

将 @targets 从解析的有效目标中移除。

$parser->version_report()

返回一个描述版本的字符串。

$parser->whine( @error_messages )

记录错误，除非 $parser->no_whining( TRUE );。

编码

Pod::Simple 解析器期望读取 **字节**。解析器将使用 POD 源代码中 =encoding 声明的值，将字节解码为 Perl 的内部字符字符串表示。

如果 POD 源代码不包含 =encoding 声明，解析器将尝试通过检查第一个非 ASCII 字节并应用 perlpodspec 中描述的启发式方法来猜测编码（选择 UTF-8 或 CP 1252 之一）。（如果 POD 源代码仅包含 ASCII 字节，则假定编码为 ASCII。）

如果将 parse_characters 选项设置为真值，解析器将期望字符而不是字节；将忽略任何 =encoding；并且不会尝试解码输入。

另请参阅

Pod::Simple::Subclassing

perlpod

perlpodspec

Pod::Escapes

perldoc

支持

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

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

请使用 https://github.com/perl-pod/pod-simple/issues/new 提交错误报告。

版权和免责声明

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

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

本程序的发布旨在提供帮助，但没有任何保证；甚至没有对适销性或特定用途适用性的暗示保证。

作者

Pod::Simple 由 Sean M. Burke <[email protected]> 创建。但不要打扰他，他已经退休了。

Pod::Simple 由以下人员维护：

文档由以下人员贡献：