Pod::Simple

(原始碼, CPAN)

版本 3.43

#名稱

Pod::Simple - Pod 剖析架構

#語法

TODO

#說明

Pod::Simple 是 Perl 程式庫，用於剖析 Pod（「純文字文件」）標記語言中的文字，Pod 標記語言通常用於撰寫 Perl 和 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 );

這是建立新 parser 物件、將輸出控制碼設為 STDOUT，然後處理指定檔案（或檔案控制碼，或記憶體文件）的捷徑方法。這對於像這樣的單行指令非常方便

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

#次要方法

其中一些方法可能對一般使用者和格式化程式撰寫者都很有用。

請注意，這裡的一般模式是存取器方法使用 $value = $parser->attribute 讀取屬性的值，並使用 $parser->attribute(newvalue) 設定屬性的值。對於每個存取器，我通常只會提到一種語法，依據我認為您實際上最有可能使用的語法而定。

#$parser->parse_characters( SOMEVALUE )

Pod parser 通常預期讀取八位元組，並根據 Pod 來源中的 =encoding 宣告將這些八位元組轉換為字元。將此選項設為 true 值，以指出 Pod 來源已經是 Perl 字元串流。這會指示 parser 忽略任何 =encoding 指令，並略過所有涉及八位元組解碼的程式碼路徑。

#$parser->no_whining( SOMEVALUE )

如果您將此屬性設為 true 值，您將會抑制 parser 針對 Pod 編碼中的不規則性提出的抱怨。預設情況下，此屬性的值為 false，表示將會報告不規則性。

請注意，將此屬性設為 true 並不會抑制一或兩種關於罕見發生無法復原錯誤的抱怨。

#$parser->no_errata_section( SOMEVALUE )

如果您將此屬性設為 true 值，您將停止解析器在文件結尾產生「POD ERRORS」區段。預設情況下，此屬性的值為 false，表示將根據需要產生 errata 區段。

#$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 )

Verbatim 段落的 perlpod 規格為「它應該被精確複製...」，這表示您用於縮排 verbatim 區塊的空白會保留在輸出中。這對於像是 HTML 的輸出而言可能會很惱人，因為該空白會保留在每行的前面。這是一個不幸的案例，其中語法變成了語意。

如果您正在分析的 POD 遵循一致的縮排政策，您可以讓此類縮排從文字區塊的每一行開頭移除。此方法會告訴 Pod::Simple 要移除什麼。對於兩個空格的縮排，您會使用

$parser->strip_verbatim_indent('  ');

對於標籤縮排，您會使用一個標籤字元

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

如果 POD 在文字區塊的縮排上不一致，但您已找出一個啟發法來確定特定文字區塊縮排的程度，您可以改為傳遞一個程式碼參考。程式碼參考會以一個引數執行，也就是文字區塊中所有行的陣列參考，並應傳回要從每一行移除的值。例如，如果您決定使用文字區塊的第一行來設定區塊其他部分的縮排標準，您可以查看第一行並傳回適當的值，如下所示

$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

如果在文字區塊中移除任何縮排後，仍有標籤，此方法呼叫會指出如何處理它們。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 宣告，解析器會嘗試猜測編碼（從 UTF-8 或 CP 1252 中選擇一個）透過檢查第一個非 ASCII 位元組，並套用 perlpodspec 中所述的啟發法。（如果 POD 來源只包含 ASCII 位元組，則假設編碼為 ASCII。）

如果您將 parse_characters 選項設定為 true 值，則解析器會預期字元而不是八位元組；會忽略任何 =encoding；且不會嘗試解碼輸入。

#另請參閱

Pod::Simple::Subclassing

#支援

關於 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 並寄送修補程式！

請使用 https://github.com/perl-pod/pod-simple/issues/new 來提交錯誤報告。

#版權和免責聲明

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

此程式散布的用意是希望它有用，但沒有任何擔保；甚至沒有對適銷性或特定用途的適用性提供默示擔保。

#作者

Pod::Simple 由 Sean M. Burke <sburke@cpan.org> 建立。但別去煩他，他已經退休了。

Pod::Simple 由下列人員維護

Allison Randal allison@perl.org
Hans Dieter Pearcey hdp@cpan.org
David E. Wheeler dwheeler@cpan.org
Karl Williamson khw@cpan.org

文件由下列人員提供

Gabor Szabo szabgab@gmail.com
Shawn H Corey SHCOREY at cpan.org

目錄

#名稱

#語法

#說明

#主要方法

#次要方法

#三級方法

#編碼

#另請參閱

#支援

#版權和免責聲明

#作者