内容

名称

Pod::Simple::PullParser -- Pod 解析的拉取解析器接口

语法

my $parser = SomePodProcessor->new;
$parser->set_source( "whatever.pod" );
$parser->run;

或者

my $parser = SomePodProcessor->new;
$parser->set_source( $some_filehandle_object );
$parser->run;

或者

my $parser = SomePodProcessor->new;
$parser->set_source( \$document_source );
$parser->run;

或者

my $parser = SomePodProcessor->new;
$parser->set_source( \@document_lines );
$parser->run;

以及其他地方

require 5;
package SomePodProcessor;
use strict;
use base qw(Pod::Simple::PullParser);

sub run {
  my $self = shift;
 Token:
  while(my $token = $self->get_token) {
    ...process each token...
  }
}

说明

此类用于使用 Pod::Simple 构建 Pod 处理器 -- 但它使用基于标记对象流的接口，而不是基于事件的接口。

这是 Pod::Simple 的子类，并继承了它的所有方法。

Pod::Simple::PullParser 的子类应定义一个 run 方法，该方法调用 $token = $parser->get_token 来拉取标记。

请参阅 Pod::Simple::RTF 的源代码，了解使用 Pod::Simple::PullParser 的格式化程序示例。

方法

我的 $token = $parser->get_token

这将返回下一个标记对象（它将是 Pod::Simple::PullParserToken 的子类），如果解析器流已达到文档末尾，则返回未定义。

$parser->unget_token( $token )
$parser->unget_token( $token1, $token2, ... )

这将把标记对象还原到解析器流的前面。

在解析任何内容之前，必须设置源。最低级别的方法是调用 set_source

$parser->set_source( $filename )
$parser->set_source( $filehandle_object )
$parser->set_source( \$document_source )
$parser->set_source( \@document_lines )

或者，你可以调用这些方法，Pod::Simple::PullParser 已定义这些方法以使其与 Pod::Simple 的同名方法一样工作

$parser->parse_file(...)
$parser->parse_string_document(...)
$parser->filter(...)
$parser->parse_from_file(...)

要使这些方法起作用，Pod::Simple::PullParser 的 Pod 处理子类必须定义一个 $parser->run 方法——因此建议所有 Pod::Simple::PullParser 子类都这样做。请参阅上面的概要或 Pod::Simple::RTF 的源代码。

格式化子类的作者可能会发现这些方法对于调用尚未开始从中提取标记的解析器对象很有用

我的 $title_string = $parser->get_title

这尝试通过获取一些标记并扫描它们以查找标题，然后取消获取它们以便你可以从头开始处理标记流，从而从 $parser 中获取标题字符串。

例如，假设你有一个从以下内容开始的文档

=head1 NAME

Hoo::Boy::Wowza -- Stuff B<wow> yeah!

该文档上的 $parser->get_title 将返回“Hoo::Boy::Wowza -- Stuff wow yeah!”。如果文档以以下内容开头

=head1 Name

Hoo::Boy::W00t -- Stuff B<w00t> yeah!

然后你需要传递 nocase 选项来识别“名称”

$parser->get_title(nocase => 1);

在 get_title 无法找到标题的情况下，它将返回空字符串 ("").

my $title_string = $parser->get_short_title

这就像 get_title，除了它只返回模块名称，如果标题似乎是“SomeModuleName -- description”的形式。

例如，假设你有一个从以下内容开始的文档

=head1 NAME

Hoo::Boy::Wowza -- Stuff B<wow> yeah!

那么该文档上的 $parser->get_short_title 将返回“Hoo::Boy::Wowza”。

但如果文档以开头

=head1 NAME

Hooboy, stuff B<wow> yeah!

那么该文档上的 $parser->get_short_title 将返回“Hooboy, stuff wow yeah!”。如果文档以开头

=head1 Name

Hoo::Boy::W00t -- Stuff B<w00t> yeah!

然后你需要传递 nocase 选项来识别“名称”

$parser->get_short_title(nocase => 1);

如果找不到标题，那么 get_short_title 将返回空字符串 ("").

$author_name = $parser->get_author

这类似于 get_title，除了它返回“=head1 AUTHOR\n\nParagraph...\n”部分的内容，假设该部分不太长。要识别“=head1 Author\n\nParagraph\n”部分，请传递 nocase 选项

$parser->get_author(nocase => 1);

（此方法也允许使用“AUTHORS”代替“AUTHOR”。）

$description_name = $parser->get_description

这类似于 get_title，除了它返回“=head1 DESCRIPTION\n\nParagraph...\n”部分的内容，假设该部分不太长。要识别“=head1 Description\n\nParagraph\n”部分，请传递 nocase 选项

$parser->get_description(nocase => 1);
$version_block = $parser->get_version

这类似于 get_title，除了它返回“=head1 VERSION\n\n[BIG BLOCK]\n”块的内容。请注意，这不会返回模块的 $VERSION！要识别“=head1 Version\n\n[BIG BLOCK]\n”部分，请传递 nocase 选项

$parser->get_version(nocase => 1);

注意

你实际上不必定义 run 方法。如果你正在编写 Pod 格式化程序类，你应该定义一个 run，以便用户可以调用 parse_file 等，但你不必这样做。

如果你没有编写格式化程序类，而只是编写了一个使用 Pod::PullParser 对象（而不是子类的对象）执行简单操作的程序，那么就没有理由费心进行子类化来添加 run 方法。

另请参阅

Pod::Simple

Pod::Simple::PullParserToken——及其子类 Pod::Simple::PullParserStartToken、Pod::Simple::PullParserTextToken 和 Pod::Simple::PullParserEndToken。

HTML::TokeParser，是它的灵感来源。

支持

有关 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]> 创建。但不要打扰他，他已经退休了。

Pod::Simple 由以下人员维护