目錄

名稱

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 的格式化程式範例。

方法

my $token = $parser->get_token

這會傳回下一個 token 物件（將會是 Pod::Simple::PullParserToken 的子類別），或在剖析串流已到達文件結尾時傳回未定義。

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

這會將 token 物件復原到剖析串流的最前面。

在剖析任何內容之前，必須先設定來源。最低層級的方法是呼叫 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 子類別都這麼做。請參閱上面的 Synopsis，或 Pod::Simple::RTF 的來源。

格式化程式子類別的作者可能會發現這些方法對於呼叫您尚未開始從中擷取 token 的剖析器物件很有用

my $title_string = $parser->get_title

這會嘗試從 $parser 取得標題字串，方法是取得一些 token，並掃描它們以尋找標題，然後再將它們取消取得，以便您可以從頭開始處理 token 串流。

例如，假設您有一個文件開頭是

=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 選項才能辨識「Name」

$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 選項才能辨識「Name」

$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 的問題或討論應寄送至 pod-people@perl.org 郵件清單。寄送一封空白電子郵件至 pod-people-subscribe@perl.org 以訂閱。

此模組在開放的 GitHub 儲存庫中管理，https://github.com/perl-pod/pod-simple/。歡迎分叉和貢獻，或複製 git://github.com/perl-pod/pod-simple.git 並傳送修補程式！

歡迎針對 Pod::Simple 的修補程式。請將錯誤報告寄送至 <bug-pod-simple@rt.cpan.org>。

版權和免責聲明

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

此函式庫是免費軟體；您可以在與 Perl 本身相同的條款下重新散布或修改它。

散布此程式是希望它會對您有幫助，但沒有任何擔保；甚至沒有對特定目的的適售性或適用性的默示擔保。

作者

Pod::Simple 由 Sean M. Burke <sburke@cpan.org> 所建立。但不要打擾他，他已經退休了。

Pod::Simple 由下列人員維護