Pod::Simple::Subclassing

(原始碼, CPAN)

#名稱

Pod::Simple::Subclassing -- 以 Pod::Simple 子類別撰寫格式化程式

#語法

  package Pod::SomeFormatter;
  use Pod::Simple;
  @ISA = qw(Pod::Simple);
  $VERSION = '1.01';
  use strict;

  sub _handle_element_start {
	my($parser, $element_name, $attr_hash_r) = @_;
	...
  }

  sub _handle_element_end {
	my($parser, $element_name, $attr_hash_r) = @_;
	# NOTE: $attr_hash_r is only present when $element_name is "over" or "begin"
	# The remaining code excerpts will mostly ignore this $attr_hash_r, as it is
	# mostly useless. It is documented where "over-*" and "begin" events are
	# documented.
	...
  }

  sub _handle_text {
	my($parser, $text) = @_;
	...
  }
  1;

#說明

本文檔說明如何使用 Pod::Simple 撰寫 Pod 處理器，通常是 Pod 格式化程式。如果您只想了解如何使用現有的 Pod 格式化程式，請參閱其文件，並參閱 Pod::Simple 中的文件。

撰寫 Pod 格式化程式的第零步是確保 CPAN 中沒有更好的格式化程式。請參閱 http://search.cpan.org/，並針對您要轉換成的格式名稱執行搜尋。另外，請考慮加入 Pod People 清單 http://lists.perl.org/showlist.cgi?name=pod-people，並詢問是否有任何人擁有該格式的格式化程式 -- 也許有人拼湊了一個，但尚未發布。

撰寫 Pod 處理器的第一步是閱讀 perlpodspec，其中包含撰寫 Pod 剖析器（Pod::Simple 已處理大部分）的資訊，但也有許多撰寫格式化程式的需求和建議。

第二步是實際了解您計畫轉換成的格式 -- 或至少了解您需要知道多少來表示 Pod，這可能不需要太多。

第三步是選擇您要使用的 Pod::Simple 介面

#Pod::Simple: 使用 _handle_element_start()、_handle_element_end() 和 _handle_text() 的基本 Pod::Simple 介面。
#Pod::Simple::Methody: 介面 Pod::Simple::Methody 是基於事件的，類似於 HTML::Parser 或 XML::Parser 的「處理常式」。
#Pod::Simple::PullParser: Pod::Simple::PullParser 提供一個類似於 HTML::TokeParser 介面的符號串流介面。
#Pod::Simple::SimpleTree: Pod::Simple::SimpleTree 提供一個簡單的樹狀結構介面，類似於 XML::Parser 的「樹狀結構」介面。熟悉 XML 處理的使用者會對這個介面感到很上手。有興趣輸出 XML 的使用者，應該深入了解產生 Pod 串流 XML 表示形式的模組，特別是 Pod::Simple::XMLOutStream；你可以將此類別的輸出提供給最熟悉的 XML 解析系統。

最後一個步驟是根據事件（或符號、樹狀節點、XML 或任何解析方式）如何對應到輸出格式中的結構，撰寫你的程式碼。另外，務必考慮如何跳脫包含任意文字的文字節點，以及如何處理表示預先格式化文字（來自逐字節錄區段）的文字節點。

#事件

待辦事項簡介... 提及事件是提供給隱含的，例如缺少 >。

在以下區段中，我們使用 XML 來表示與特定結構相關聯的事件結構。也就是說，開啟標籤表示元素開始，開啟標籤的屬性是提供給回呼的屬性，而關閉標籤表示結束元素。

延伸 Pod::Simple 的類別必須提供三個回呼方法才能接收對應的事件

#$parser->_handle_element_start( element_name, attr_hashref )
#$parser->_handle_element_end( element_name )
#$parser->_handle_text( text_string )

以下是你可以在 _handle_element_start 和 _handle_element_end 實作中預期的 element_name 值的完整清單：

#element_name 為 Document 的事件

解析文件會產生這個事件結構

  <Document start_line="543">
	...all events...
  </Document>

start_line 屬性的值會是文件中的第一個 Pod 指令的行號。

如果給定的文件中沒有 Pod，則事件結構會是這樣

<Document contentless="1" start_line="543">
</Document>

在這種情況下，start_line 屬性的值沒有意義；在目前的實作中，它可能是檔案中最後一行的行號。

#element_name 為 Para 的事件

在 Pod 文件中分析一個純文字（非逐字、非指令、非資料）段落會產生這個事件結構

<Para start_line="543">
  ...all events in this paragraph...
</Para>

start_line 屬性的值會是段落開頭的行號。

例如，分析這個 Pod 段落

The value of the I<start_line> attribute will be the
line number of the start of the paragraph.

會產生這個事件結構

<Para start_line="129">
  The value of the
  <I>
	start_line
  </I>
   attribute will be the line number of the first Pod directive
  in the document.
</Para>

#element_name 為 B、C、F 或 I 的事件

分析一個 B<...> 格式化程式碼（當然也包括任何語意相同的語法變體 B<< ... >> 或 B<<<< ... >>>> 等）會產生這個事件結構

  <B>
	...stuff...
  </B>

目前沒有傳遞任何屬性。

分析 C、F 或 I 程式碼會產生相同的結構，只有一個不同的元素名稱。

如果你的分析器物件已設定為接受其他格式化程式碼，則它們會像這些 B/C/F/I 程式碼一樣呈現，也就是沒有任何屬性。

#element_name 為 S 的事件

一般來說，分析一個 S<...> 序列會產生這個事件結構，就像它是一個 B/C/F/I 程式碼一樣

  <S>
	...stuff...
  </S>

不過，Pod::Simple（以及推測所有衍生的分析器）提供 nbsp_for_S 選項，如果啟用，會抑制所有 S 事件，並將內容中的所有空格改為不換行空格。這是針對輸出到沒有與 S<...> 相同意義的程式碼，但有表示不換行空格的程式碼/字元的格式化器。

#element_name 為 X 的事件

一般來說，分析一個 X<...> 序列會產生這個事件結構，就像它是一個 B/C/F/I 程式碼一樣

  <X>
	...stuff...
  </X>

不過，Pod::Simple（以及推測所有衍生的分析器）提供 nix_X_codes 選項，如果啟用，會抑制所有 X 事件並忽略其內容。對於不使用 X 事件的格式化器/處理器來說，這應該很有用。

#element_name 為 L 的事件

由於 L<...> 是語言中最複雜的建構，因此它產生的事件是語言中最複雜的，這一點並不令人意外。大部分的複雜性都隱藏在屬性值中，因此對於撰寫產生非超文本格式的 Pod 格式化程式的人來說，您可以忽略屬性，並將 L 事件結構視為一個格式化元素，它（可能）不會實際產生格式化的變更。也就是說，L 事件結構的內容（與其屬性相反）永遠是應該顯示的文字。

乍看之下，有 3 種 L 連結：URL、手冊頁和 Pod。

當 L<some_url> 程式碼被解析時，它會產生這個事件結構

  <L content-implicit="yes" raw="that_url" to="that_url" type="url">
	that_url
  </L>

對於這種類型的 L 程式碼，type="url" 屬性總是會被指定。

例如，這個 Pod 來源

L<http://www.perl.com/CPAN/authors/>

會產生這個事件結構

  <L content-implicit="yes" raw="http://www.perl.com/CPAN/authors/" to="http://www.perl.com/CPAN/authors/" type="url">
	http://www.perl.com/CPAN/authors/
  </L>

當 L<manpage(section)> 程式碼被解析時（這些相當罕見且不太有用），它會產生這個事件結構

  <L content-implicit="yes" raw="manpage(section)" to="manpage(section)" type="man">
	manpage(section)
  </L>

對於這種類型的 L 程式碼，type="man" 屬性總是會被指定。

例如，這個 Pod 來源

L<crontab(5)>

會產生這個事件結構

  <L content-implicit="yes" raw="crontab(5)" to="crontab(5)" type="man">
	crontab(5)
  </L>

在罕見的情況下，當手冊頁連結指定了章節時，該文字會出現在 section 屬性中。例如，這個 Pod 來源

L<crontab(5)/"ENVIRONMENT">

將會產生這個事件結構

  <L content-implicit="yes" raw="crontab(5)/&quot;ENVIRONMENT&quot;" section="ENVIRONMENT" to="crontab(5)" type="man">
	"ENVIRONMENT" in crontab(5)
  </L>

在罕見的情況下，當 Pod 文件有類似 L<sometext|manpage(section)> 的程式碼時，sometext 將會顯示為元素的內容，manpage(section) 文字只會顯示為 to 屬性的值，而且不會有 content-implicit="yes" 屬性（其存在表示 Pod 解析器必須推論應該顯示為連結文字的文字，與沒有該屬性的情況相反，表示 Pod 解析器不需要推論連結文字，因為該 L 程式碼明確指定了某些連結文字）。

例如，這個 Pod 來源

L<hell itself!|crontab(5)>

將會產生這個事件結構

  <L raw="hell itself!|crontab(5)" to="crontab(5)" type="man">
	hell itself!
  </L>

最後一種 L 結構是連結到 Pod 文件或 Pod 文件內的連結。這是最複雜的，因為它可以有 to 屬性、section 屬性，或兩者兼具。對於這種類型的 L 程式碼，type="pod" 屬性總是會被指定。

在最常見的情況下，L<podpage> 程式碼的簡單情況會產生這個事件結構

  <L content-implicit="yes" raw="podpage" to="podpage" type="pod">
	podpage
  </L>

例如，這個 Pod 來源

L<Net::Ping>

會產生這個事件結構

  <L content-implicit="yes" raw="Net::Ping" to="Net::Ping" type="pod">
	Net::Ping
  </L>

在明確指定連結文字的情況下，它會出現在元素的內容中（而不是屬性中），就像上面討論的 L<sometext|manpage(section)> 情況一樣。例如，這個 Pod 來源

L<Perl Error Messages|perldiag>

會產生這個事件結構

  <L raw="Perl Error Messages|perldiag" to="perldiag" type="pod">
	Perl Error Messages
  </L>

在連結到目前 Pod 文件中的章節的情況下，會有 section 屬性，而不是 to 屬性。例如，這個 Pod 來源

L</"Member Data">

會產生這個事件結構

  <L content-implicit="yes" raw="/&quot;Member Data&quot;" section="Member Data" type="pod">
	"Member Data"
  </L>

另一個例子，這個 Pod 來源

L<the various attributes|/"Member Data">

會產生這個事件結構

  <L raw="the various attributes|/&quot;Member Data&quot;" section="Member Data" type="pod">
	the various attributes
  </L>

在連結到不同 Pod 文件中的章節的情況下，會有 section 屬性和 to 屬性。例如，這個 Pod 來源

L<perlsyn/"Basic BLOCKs and Switch Statements">

會產生這個事件結構

  <L content-implicit="yes" raw="perlsyn/&quot;Basic BLOCKs and Switch Statements&quot;" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
	"Basic BLOCKs and Switch Statements" in perlsyn
  </L>

另一個例子，這個 Pod 來源

L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements">

會產生這個事件結構

  <L raw="SWITCH statements|perlsyn/&quot;Basic BLOCKs and Switch Statements&quot;" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
	SWITCH statements
  </L>

順帶一提，請注意我們不會區分這些語法

L</"Member Data">
L<"Member Data">
L</Member Data>
L<Member Data>    [deprecated syntax]

也就是說，它們（大部分）都會產生相同的事件結構，即

  <L content-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod">
	&#34;Member Data&#34;
  </L>

raw 屬性取決於 L<> 的原始內容，因此事件結構「大部分」都是相同的。

如果您還沒猜到，raw 屬性包含 L<> 格式化代碼的原始、未修改、未跳脫的內容。除了上述範例之外，請注意以下 L<> 格式化代碼產生的事件結構。

  L<click B<here>|page/About the C<-M> switch>

  <L raw="click B<here>|page/About the C<-M> switch" section="About the -M switch" to="page" type="pod">
	click B<here>
  </L>

特別注意格式化代碼會出現在 raw 中，且未跳脫。

raw 屬性有一個已知錯誤，其中任何周圍的空白都會濃縮成單一空白。例如，給定 L< link>，raw 會是「 link」。

#element_name 為 E 或 Z 的事件

雖然有 Pod 代碼 E<...> 和 Z<>，但這些不會產生任何 E 或 Z 事件，也就是說，沒有 E 或 Z 這類事件。

#element_name 為 Verbatim 的事件

當剖析 Pod verbatim 段落（又稱「程式碼區塊」）時，會產生這個事件結構

  <Verbatim start_line="543" xml:space="preserve">
	...text...
  </Verbatim>

start_line 屬性的值會是這個 verbatim 區塊的第一行的行號。xml:space 屬性總是存在，且值總是「preserve」。

文字內容的 tab 已展開。

#element_name 為 head1 .. head4 的事件

當剖析「=head1 ...」指令時，會產生這個事件結構

  <head1>
	...stuff...
  </head1>

例如，由這個組成的指令

=head1 Options to C<new> et al.

將會產生這個事件結構

  <head1 start_line="543">
	Options to
	<C>
	  new
	</C>
	 et al.
  </head1>

「=head2」到「=head4」指令是一樣的，除了事件結構中的元素名稱。

#element_name 為 encoding 的事件

在預設情況下，不會發出對應於 =encoding 指令的事件。如果 keep_encoding_directive 為 true，則會發出事件。在這種情況下，它們會產生如上所述的「element_name 為 head1 .. head4 的事件」這樣的事件結構。

#element_name 為 over-bullet 的事件

當剖析「=over ... =back」區塊，其中項目是項目符號清單時，會產生這個事件結構

  <over-bullet indent="4" start_line="543">
	<item-bullet start_line="545">
	  ...Stuff...
	</item-bullet>
	...more item-bullets...
  </over-bullet fake-closer="1">

fake-closer 屬性僅在為 true 值時才會存在；如果為 false 值，則不存在。它顯示在上述範例中，用於說明屬性在哪裡（在結束標籤中）。它表示 =over 沒有匹配的 =back，因此 Pod::Simple 必須建立一個假的結束標籤。

例如，這個 Pod 來源

=over

=item *

Something

=back

會產生一個沒有fake-closer 屬性的事件結構，而這個 Pod 來源

=over

=item *

Gasp! An unclosed =over block!

會產生。其餘的 over-* 範例不會示範這個屬性，但它們都可以有這個屬性。請參閱 Pod::Checker 的來源，以取得使用這個屬性的範例。

indent 屬性的值是「=over」指令之後的任何值，例如「=over 8」。如果指令中未指定此類值，則 indent 屬性具有值「4」。

例如，這個 Pod 來源

=over

=item *

Stuff

=item *

Bar I<baz>!

=back

會產生這個事件結構

  <over-bullet indent="4" start_line="10">
	<item-bullet start_line="12">
	  Stuff
	</item-bullet>
	<item-bullet start_line="14">
	  Bar <I>baz</I>!
	</item-bullet>
  </over-bullet>

#具有 over-number element_name 的事件

當解析「=over ... =back」區塊，其中項目為編號清單時，將產生此事件結構

  <over-number indent="4" start_line="543">
	<item-number number="1" start_line="545">
	  ...Stuff...
	</item-number>
	...more item-number...
  </over-bullet>

這類似於「over-bullet」事件結構；但請注意，內容為「item-number」，而非「item-bullet」，且請注意，它們將具有「number」屬性，某些格式化程式/處理器可能會忽略此屬性（例如，在產生「<UL><LI>...</LI>...</UL>」結構時，HTML 中不需要此屬性），但任何處理器都可以使用此屬性。

請注意，在特定「over-number」區域中，「item-number」元素的 number 屬性值將從 1 開始，每次遞增 1。如果 Pod 來源未遵循該順序（儘管它真的應該遵循！），將會忽略它具有的任何數字（將正確的值放入 number 屬性中），並可能會向使用者發出錯誤訊息。

#具有 over-text element_name 的事件

這些事件與其他 over-* 結構有些不同，就其內容而言。當解析「=over ... =back」區塊，其中項目為文字「子標題」清單時，將產生此事件結構

  <over-text indent="4" start_line="543">
	<item-text>
	  ...stuff...
	</item-text>
	...stuff (generally Para or Verbatim elements)...
	<item-text>
	...more item-text and/or stuff...
  </over-text>

indent 和 fake-closer 屬性與其他 over-* 事件相同。

例如，這個 Pod 來源

=over

=item Foo

Stuff

=item Bar I<baz>!

Quux

=back

會產生這個事件結構

  <over-text indent="4" start_line="20">
	<item-text start_line="22">
	  Foo
	</item-text>
	<Para start_line="24">
	  Stuff
	</Para>
	<item-text start_line="26">
	  Bar
		<I>
		  baz
		</I>
	  !
	</item-text>
	<Para start_line="28">
	  Quux
	</Para>
  </over-text>

#具有 over-block element_name 的事件

這些事件與其他 over-* 結構有些不同，就其內容而言。當解析「=over ... =back」區塊，其中沒有項目時，將產生此事件結構

  <over-block indent="4" start_line="543">
	...stuff (generally Para or Verbatim elements)...
  </over-block>

indent 和 fake-closer 屬性與其他 over-* 事件相同。

例如，這個 Pod 來源

=over

For cutting off our trade with all parts of the world

For transporting us beyond seas to be tried for pretended offenses

He is at this time transporting large armies of foreign mercenaries to
complete the works of death, desolation and tyranny, already begun with
circumstances of cruelty and perfidy scarcely paralleled in the most
barbarous ages, and totally unworthy the head of a civilized nation.

=back

將會產生這個事件結構

  <over-block indent="4" start_line="2">
	<Para start_line="4">
	  For cutting off our trade with all parts of the world
	</Para>
	<Para start_line="6">
	  For transporting us beyond seas to be tried for pretended offenses
	</Para>
	<Para start_line="8">
	  He is at this time transporting large armies of [...more text...]
	</Para>
  </over-block>

#具有 over-empty element_name 的事件

注意：僅當 parse_empty_lists() 設為 true 值時，才會觸發這些事件。

這些事件與其他 over-* 結構有些不同，就其內容而言。當解析「=over ... =back」區塊，其中沒有內容時，將產生此事件結構

<over-empty indent="4" start_line="543">
</over-empty>

indent 和 fake-closer 屬性與其他 over-* 事件相同。

例如，這個 Pod 來源

=over

=over

=back

=back

將會產生這個事件結構

  <over-block indent="4" start_line="1">
	<over-empty indent="4" start_line="3">
	</over-empty>
  </over-block>

請注意，外層的 =over 是區塊，因為它沒有 =item，但仍有內容：內層的 =over。內層的 =over 完全是空的，因此被視為如此。

#element_name 為 item-bullet 的事件

請參閱上方的 "element_name 為 over-bullet 的事件"。

#element_name 為 item-number 的事件

請參閱上方的 "element_name 為 over-number 的事件"。

#element_name 為 item-text 的事件

請參閱上方的 "element_name 為 over-text 的事件"。

#element_name 為 for 的事件

待辦事項...

#element_name 為 Data 的事件

待辦事項...

#更多 Pod::Simple 方法

Pod::Simple 提供許多方法，對於現有 Pod 格式化程式的最終使用者來說通常不感興趣，但其中一些方法在撰寫 Pod 格式化程式時可能會對您有所幫助。它們列在下方。前幾個方法 (accept_* 方法) 用於宣告解析器的功能，特別是它感興趣的 =for targetname 區段，以及它接受的額外 N<...> 程式碼，這些程式碼超出 perlpod 中所述的程式碼。

#$parser->accept_targets( SOMEVALUE )

當解析器看到類似以下的區段時

=for html  <img src="fig1.jpg">

或

=begin html

  <img src="fig1.jpg">

=end html

...解析器會忽略這些區段，除非您的子類別已指定它想要看到目標為「html」(或任何格式化程式名稱) 的區段。

如果您想處理所有區段，即使它們不是針對您，請在開始解析前呼叫此方法

$parser->accept_targets('*');

#$parser->accept_targets_as_text( SOMEVALUE )

這類似於 accept_targets，但它也指定這個目標的區段內容應視為 Pod 文字，即使「=for targetname」中的目標名稱未以「:」開頭。

在撰寫本文時，我不認為您需要使用此方法。

#$parser->accept_codes( Codename, Codename... )

這會告訴解析器您接受額外的格式化程式碼，而不仅仅是標準程式碼 (I B C L F S X，加上您實際上不會在解析樹中看到的兩個奇怪程式碼 Z 和 E)。例如，若要也接受程式碼「N」、「R」和「W」

$parser->accept_codes( qw( N R W ) );

待辦事項：記錄這如何與 =extend 和長元素名稱互動

#$parser->accept_directive_as_data( directive_name )

#$parser->accept_directive_as_verbatim( directive_name )

#$parser->accept_directive_as_processed( directive_name )

在您需要告訴解析器您會接受額外指令 (「=foo」事項) 的不太可能的情況下，您需要先設定解析器將其內容視為資料 (亦即，完全不處理)，或視為逐字內容 (主要只是展開標籤)，或視為已處理文字 (解析格式化程式碼，例如 B<...>)。

例如，若要接受新的指令「=method」，您可能會使用

$parser->accept_directive_as_processed("method");

這樣就能有下列 Pod 行

=method I<$whatever> thing B<um>

自訂指令會破壞與其他 Pod 格式器的相容性，而使用「=for target ...」行則不會；不過，如果您製作的是 Pod 超集格式，而且不需擔心相容性，這可能會對您有所幫助。

#$parser->nbsp_for_S( BOOLEAN );

將此屬性設定為 true 值（預設為 false）會將「S<...>」序列轉換成由 \xA0（不換行空白）字元分隔的字詞序列。例如，它會將下列內容

I like S<Dutch apple pie>, don't you?

視為

I like DutchE<nbsp>appleE<nbsp>pie, don't you?

這對於沒有類似「S<...>」程式碼，但有「不換行空白」程式碼的輸出格式非常實用。

目前沒有反向的方法；但如果需要，我可能會提供一個。

#$parser->version_report()

這會傳回一個字串，報告您模組的 $VERSION 值（及其類別名稱），以及 Pod::Simple 的 $VERSION 值。請注意，perlpodspec 要求輸出格式（在可能的情況下）在輸出格式的註解中記錄此詳細資料。例如，對於某種 SGML 輸出格式

print OUT "<!-- \n", $parser->version_report, "\n -->";

#$parser->pod_para_count()

這會傳回到目前為止已看到的 Pod 段落數目。

#$parser->line_count()

這是目前正在解析的行數。不過，當「line_number」事件屬性存在時，您可能會發現它更精確。

#$parser->nix_X_codes( SOMEVALUE )

此屬性在設定為 true 值時（預設為 false），會忽略正在解析的文件中的任何「X<...>」序列。許多格式實際上並未使用這些程式碼的內容，因此沒有理由處理它們。

#$parser->keep_encoding_directive( SOMEVALUE )

此屬性設定為 true 值（預設為 false）時，會在事件結構中保留 =encoding 及其內容。大多數格式實際上不需要處理 =encoding 指令的內容，即使此指令設定編碼且處理器使用編碼資訊也是如此。事實上，可以在不處理指令內容的情況下得知編碼。

#$parser->merge_text( SOMEVALUE )

此屬性設定為 true 值（預設為 false）時，可確保只會為任何單一連續文字序列建立一個事件（或標記，或節點）。例如，考慮這個有點牽強的範例

I just LOVE Z<>hotE<32>apple pie!

當它被剖析且事件即將被呼叫時，它實際上可能看起來像四個不同的文字事件，一個接著一個：一個「I just LOVE 」事件，一個「hot」事件，一個「」事件，以及一個「apple pie!」事件。但是如果你開啟 merge_text，那麼可以保證它會作為一個文字事件觸發：「I just LOVE hot apple pie!」

#$parser->code_handler( CODE_REF )

此處指定在看到程式碼列（即 Pod 之外的列）時應呼叫的程式碼。通常這是未定義的，表示不應呼叫任何程式碼。如果你提供常式，它應從以下開始

sub get_code_line {  # or whatever you'll call it
  my($line, $line_number, $parser) = @_;
  ...
}

不過請注意，有時 Pod 事件並非完全按照程式碼列的順序處理——即如果你有一個包含 Pod、程式碼，然後是更多 Pod 的檔案，有時程式碼會在處理完所有前置 Pod 之前處理（透過任何你呼叫 code_handler 的方式）。

#$parser->cut_handler( CODE_REF )

這就像 code_handler 屬性，只不過它是針對「=cut」列，而非程式碼列。套用相同的警告。「=cut」列不太可能有趣，但這包含在內以求完整性。

#$parser->pod_handler( CODE_REF )

這就像 code_handler 屬性，只不過它是針對「=pod」列，而非程式碼列。套用相同的警告。「=pod」列不太可能有趣，但這包含在內以求完整性。

#$parser->whiteline_handler( CODE_REF )

這就像 code_handler 屬性，只不過它是針對看似空白，但有空白字元（「」和/或「\t」）的列，而非程式碼列。套用相同的警告。這些列不太可能有趣，但這包含在內以求完整性。

#$parser->whine( linenumber, complaint string )

這會在 Pod 中標示一個問題，該問題會在文件的「Pod 錯誤」區段中回報，或根據屬性 no_whining、no_errata_section 和 complain_stderr 的值傳送至 STDERR。

#$parser->scream( linenumber, complaint string )

這會標示一個錯誤，就像 whine 所做的一樣，但它無法使用 no_whining 抑制。這應該只用於非常嚴重的錯誤。

#$parser->source_dead(1)

這會中斷目前文件的剖析，方法是開啟表示已看到 EOF 的旗標。在特別嚴重的案例中，你可能會想要這麼做。這比只呼叫 die 好多了！

#$parser->hide_line_numbers( SOMEVALUE )

有些隨意傾印事件屬性的子類別（除了以「~」開頭的屬性）可以使用這個物件屬性來避免傾印「start_line」屬性。

#$parser->no_whining( SOMEVALUE )

如果將這個屬性設定為 true，它會抑制非致命錯誤訊息的報告。預設值為 false，表示會回報抱怨。回報方式取決於屬性 no_errata_section 和 complain_stderr 的值。

#$parser->no_errata_section( SOMEVALUE )

如果將這個屬性設定為 true，它會抑制產生 errata 區段。預設值為 false，也就是會產生 errata 區段。

#$parser->complain_stderr( SOMEVALUE )

如果將這個屬性設定為 true，它會將抱怨傳送至 STDERR。預設值為 false，也就是抱怨不會傳送至 STDERR。

#$parser->bare_output( SOMEVALUE )

某些格式器子類別會將此作為一個標記，用於表示輸出是否應省略序言和尾聲程式碼。例如，對 HTML 格式器類別設定此值為 true 應省略序言「<html><head><title>...</title><body>...」和尾聲「</body></html>」。

如果您想將此值設定為 true，您可能還應該將 no_whining 或至少 no_errata_section 設定為 true。

#$parser->preserve_whitespace( SOMEVALUE )

如果您將此屬性設定為 true 值，解析器將嘗試保留輸出中的空白。這表示解析器將保留句點後兩個空白等格式化慣例。這主要適用於將空白視為重要的輸出格式（例如文字或 *roff，但不適用於 HTML）。

#$parser->parse_empty_lists( SOMEVALUE )

如果此屬性設定為 true，解析器將不會忽略空的 =over/=back 區塊。=over 的類型將為上述文件中說明的 empty，「element_name 為 over-empty 的事件」。

#另請參閱

Pod::Simple -- 基於事件的 Pod 解析架構

Pod::Simple::Methody -- 類似於 Pod::Simple，但每種事件類型都會呼叫自己的方法（例如 start_head3）

Pod::Simple::PullParser -- 類似於 Pod::Simple 的 Pod 解析架構，但具有代幣串流介面

Pod::Simple::SimpleTree -- 類似於 Pod::Simple 的 Pod 解析架構，但具有樹狀介面

Pod::Simple::Checker -- 簡單的 Pod::Simple 子類別，用於讀取文件，然後針對文件中找到的任何錯誤製作純文字報告

Pod::Simple::DumpAsXML -- 用於將 Pod 文件轉儲為整齊縮排的 XML，在自己的行上顯示每個事件

Pod::Simple::XMLOutStream -- 將 Pod 文件轉儲為 XML（不會像 Pod::Simple::DumpAsXML 一樣引入額外空白）

Pod::Simple::DumpAsText -- 用於將 Pod 文件轉儲為整齊縮排的文字，並在每一行顯示每個事件

Pod::Simple::LinkSection -- 用於表示 L<...> 元素的 TODO 和 TODO 屬性值的物件類別

Pod::Escapes -- Pod::Simple 用於評估 E<...> 內容的模組

Pod::Simple::Text -- Pod 的簡單純文字格式化程式

Pod::Simple::TextContent -- 類似 Pod::Simple::Text，但不會對要格式化的文字進行縮排或換行

Pod::Simple::HTML -- Pod 的簡單 HTML 格式化程式

perlpod

perlpodspec

perldoc

#支援

有關 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>。

#著作權和免責聲明

此函式庫是免費軟體；您可以在與 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

目錄

#名稱

#語法

#說明

#事件

#更多 Pod::Simple 方法

#另請參閱

#支援

#著作權和免責聲明

#作者