1Pod::Simple::SubclassinUgs(e3r)Contributed Perl DocumentPaotdi:o:nSimple::Subclassing(3)
2
6 Pod::Simple::Subclassing -- write a formatter as a Pod::Simple subclass
7
9 package Pod::SomeFormatter;
10 use Pod::Simple;
11 @ISA = qw(Pod::Simple);
12 $VERSION = '1.01';
13 use strict;
14 sub _handle_element_start {
16 my($parser, $element_name, $attr_hash_r) = @_;
17 ...
18 }
19 sub _handle_element_end {
21 my($parser, $element_name, $attr_hash_r) = @_;
22 # NOTE: $attr_hash_r is only present when $element_name is "over" or "begin"
23 # The remaining code excerpts will mostly ignore this $attr_hash_r, as it is
24 # mostly useless. It is documented where "over-*" and "begin" events are
25 # documented.
26 ...
27 }
28 sub _handle_text {
30 my($parser, $text) = @_;
31 ...
32 }
33 1;
34
36 This document is about using Pod::Simple to write a Pod processor,
37 generally a Pod formatter. If you just want to know about using an
38 existing Pod formatter, instead see its documentation and see also the
39 docs in Pod::Simple.
40 The zeroeth step in writing a Pod formatter is to make sure that there
42 isn't already a decent one in CPAN. See <http://search.cpan.org/>, and
43 run a search on the name of the format you want to render to. Also
44 consider joining the Pod People list
45 <http://lists.perl.org/showlist.cgi?name=pod-people> and asking whether
46 anyone has a formatter for that format -- maybe someone cobbled one
47 together but just hasn't released it.
48 The first step in writing a Pod processor is to read perlpodspec, which
50 contains information on writing a Pod parser (which has been largely
51 taken care of by Pod::Simple), but also a lot of requirements and
52 recommendations for writing a formatter.
53 The second step is to actually learn the format you're planning to
55 format to -- or at least as much as you need to know to represent Pod,
56 which probably isn't much.
57 The third step is to pick which of Pod::Simple's interfaces you want to
59 use:
60 Pod::Simple
62 The basic Pod::Simple interface that uses
63 "_handle_element_start()", "_handle_element_end()" and
64 "_handle_text()".
65 Pod::Simple::Methody
67 The Pod::Simple::Methody interface is event-based, similar to that
68 of HTML::Parser or XML::Parser's "Handlers".
69 Pod::Simple::PullParser
71 Pod::Simple::PullParser provides a token-stream interface, sort of
72 like HTML::TokeParser's interface.
73 Pod::Simple::SimpleTree
75 Pod::Simple::SimpleTree provides a simple tree interface, rather
76 like XML::Parser's "Tree" interface. Users familiar with XML
77 handling will be comfortable with this interface. Users interested
78 in outputting XML, should look into the modules that produce an XML
79 representation of the Pod stream, notably
80 Pod::Simple::XMLOutStream; you can feed the output of such a class
81 to whatever XML parsing system you are most at home with.
82 The last step is to write your code based on how the events (or tokens,
84 or tree-nodes, or the XML, or however you're parsing) will map to
85 constructs in the output format. Also be sure to consider how to escape
86 text nodes containing arbitrary text, and what to do with text nodes
87 that represent preformatted text (from verbatim sections).
88
90 TODO intro... mention that events are supplied for implicits, like for
91 missing >'s
92 In the following section, we use XML to represent the event structure
94 associated with a particular construct. That is, an opening tag
95 represents the element start, the attributes of that opening tag are
96 the attributes given to the callback, and the closing tag represents
97 the end element.
98 Three callback methods must be supplied by a class extending
100 Pod::Simple to receive the corresponding event:
101 "$parser->_handle_element_start( element_name, attr_hashref )"
103 "$parser->_handle_element_end( element_name )"
104 "$parser->_handle_text( text_string )"
105 Here's the comprehensive list of values you can expect as element_name
107 in your implementation of "_handle_element_start" and
108 "_handle_element_end"::
109 events with an element_name of Document
111 Parsing a document produces this event structure:
112 <Document start_line="543">
114 ...all events...
115 </Document>
116 The value of the start_line attribute will be the line number of
118 the first Pod directive in the document.
119 If there is no Pod in the given document, then the event structure
121 will be this:
122 <Document contentless="1" start_line="543">
124 </Document>
125 In that case, the value of the start_line attribute will not be
127 meaningful; under current implementations, it will probably be the
128 line number of the last line in the file.
129 events with an element_name of Para
131 Parsing a plain (non-verbatim, non-directive, non-data) paragraph
132 in a Pod document produces this event structure:
133 <Para start_line="543">
135 ...all events in this paragraph...
136 </Para>
137 The value of the start_line attribute will be the line number of
139 the start of the paragraph.
140 For example, parsing this paragraph of Pod:
142 The value of the I<start_line> attribute will be the
144 line number of the start of the paragraph.
145 produces this event structure:
147 <Para start_line="129">
149 The value of the
150 <I>
151 start_line
152 </I>
153 attribute will be the line number of the first Pod directive
154 in the document.
155 </Para>
156 events with an element_name of B, C, F, or I.
158 Parsing a B<...> formatting code (or of course any of its
159 semantically identical syntactic variants B<< ... >>, or
160 B<<<< ... >>>>, etc.) produces this event structure:
161 <B>
163 ...stuff...
164 </B>
165 Currently, there are no attributes conveyed.
167 Parsing C, F, or I codes produce the same structure, with only a
169 different element name.
170 If your parser object has been set to accept other formatting
172 codes, then they will be presented like these B/C/F/I codes --
173 i.e., without any attributes.
174 events with an element_name of S
176 Normally, parsing an S<...> sequence produces this event structure,
177 just as if it were a B/C/F/I code:
178 <S>
180 ...stuff...
181 </S>
182 However, Pod::Simple (and presumably all derived parsers) offers
184 the "nbsp_for_S" option which, if enabled, will suppress all S
185 events, and instead change all spaces in the content to non-
186 breaking spaces. This is intended for formatters that output to a
187 format that has no code that means the same as S<...>, but which
188 has a code/character that means non-breaking space.
189 events with an element_name of X
191 Normally, parsing an X<...> sequence produces this event structure,
192 just as if it were a B/C/F/I code:
193 <X>
195 ...stuff...
196 </X>
197 However, Pod::Simple (and presumably all derived parsers) offers
199 the "nix_X_codes" option which, if enabled, will suppress all X
200 events and ignore their content. For formatters/processors that
201 don't use X events, this is presumably quite useful.
202 events with an element_name of L
204 Because the L<...> is the most complex construct in the language,
205 it should not surprise you that the events it generates are the
206 most complex in the language. Most of complexity is hidden away in
207 the attribute values, so for those of you writing a Pod formatter
208 that produces a non-hypertextual format, you can just ignore the
209 attributes and treat an L event structure like a formatting element
210 that (presumably) doesn't actually produce a change in formatting.
211 That is, the content of the L event structure (as opposed to its
212 attributes) is always what text should be displayed.
213 There are, at first glance, three kinds of L links: URL, man, and
215 pod.
216 When a L<some_url> code is parsed, it produces this event
218 structure:
219 <L content-implicit="yes" raw="that_url" to="that_url" type="url">
221 that_url
222 </L>
223 The "type="url"" attribute is always specified for this type of L
225 code.
226 For example, this Pod source:
228 L<http://www.perl.com/CPAN/authors/>
230 produces this event structure:
232 <L content-implicit="yes" raw="http://www.perl.com/CPAN/authors/" to="http://www.perl.com/CPAN/authors/" type="url">
234 http://www.perl.com/CPAN/authors/
235 </L>
236 When a L<manpage(section)> code is parsed (and these are fairly
238 rare and not terribly useful), it produces this event structure:
239 <L content-implicit="yes" raw="manpage(section)" to="manpage(section)" type="man">
241 manpage(section)
242 </L>
243 The "type="man"" attribute is always specified for this type of L
245 code.
246 For example, this Pod source:
248 L<crontab(5)>
250 produces this event structure:
252 <L content-implicit="yes" raw="crontab(5)" to="crontab(5)" type="man">
254 crontab(5)
255 </L>
256 In the rare cases where a man page link has a section specified,
258 that text appears in a section attribute. For example, this Pod
259 source:
260 L<crontab(5)/"ENVIRONMENT">
262 will produce this event structure:
264 <L content-implicit="yes" raw="crontab(5)/"ENVIRONMENT"" section="ENVIRONMENT" to="crontab(5)" type="man">
266 "ENVIRONMENT" in crontab(5)
267 </L>
268 In the rare case where the Pod document has code like
270 L<sometext|manpage(section)>, then the sometext will appear as the
271 content of the element, the manpage(section) text will appear only
272 as the value of the to attribute, and there will be no
273 "content-implicit="yes"" attribute (whose presence means that the
274 Pod parser had to infer what text should appear as the link text --
275 as opposed to cases where that attribute is absent, which means
276 that the Pod parser did not have to infer the link text, because
277 that L code explicitly specified some link text.)
278 For example, this Pod source:
280 L<hell itself!|crontab(5)>
282 will produce this event structure:
284 <L raw="hell itself!|crontab(5)" to="crontab(5)" type="man">
286 hell itself!
287 </L>
288 The last type of L structure is for links to/within Pod documents.
290 It is the most complex because it can have a to attribute, or a
291 section attribute, or both. The "type="pod"" attribute is always
292 specified for this type of L code.
293 In the most common case, the simple case of a L<podpage> code
295 produces this event structure:
296 <L content-implicit="yes" raw="podpage" to="podpage" type="pod">
298 podpage
299 </L>
300 For example, this Pod source:
302 L<Net::Ping>
304 produces this event structure:
306 <L content-implicit="yes" raw="Net::Ping" to="Net::Ping" type="pod">
308 Net::Ping
309 </L>
310 In cases where there is link-text explicitly specified, it is to be
312 found in the content of the element (and not the attributes), just
313 as with the L<sometext|manpage(section)> case discussed above. For
314 example, this Pod source:
315 L<Perl Error Messages|perldiag>
317 produces this event structure:
319 <L raw="Perl Error Messages|perldiag" to="perldiag" type="pod">
321 Perl Error Messages
322 </L>
323 In cases of links to a section in the current Pod document, there
325 is a section attribute instead of a to attribute. For example,
326 this Pod source:
327 L</"Member Data">
329 produces this event structure:
331 <L content-implicit="yes" raw="/"Member Data"" section="Member Data" type="pod">
333 "Member Data"
334 </L>
335 As another example, this Pod source:
337 L<the various attributes|/"Member Data">
339 produces this event structure:
341 <L raw="the various attributes|/"Member Data"" section="Member Data" type="pod">
343 the various attributes
344 </L>
345 In cases of links to a section in a different Pod document, there
347 are both a section attribute and a to attribute. For example, this
348 Pod source:
349 L<perlsyn/"Basic BLOCKs and Switch Statements">
351 produces this event structure:
353 <L content-implicit="yes" raw="perlsyn/"Basic BLOCKs and Switch Statements"" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
355 "Basic BLOCKs and Switch Statements" in perlsyn
356 </L>
357 As another example, this Pod source:
359 L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements">
361 produces this event structure:
363 <L raw="SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements"" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod">
365 SWITCH statements
366 </L>
367 Incidentally, note that we do not distinguish between these
369 syntaxes:
370 L</"Member Data">
372 L<"Member Data">
373 L</Member Data>
374 L<Member Data> [deprecated syntax]
375 That is, they all produce the same event structure (for the most
377 part), namely:
378 <L content-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod">
380 "Member Data"
381 </L>
382 The raw attribute depends on what the raw content of the "L<>" is,
384 so that is why the event structure is the same "for the most part".
385 If you have not guessed it yet, the raw attribute contains the raw,
387 original, unescaped content of the "L<>" formatting code. In
388 addition to the examples above, take notice of the following event
389 structure produced by the following "L<>" formatting code.
390 L<click B<here>|page/About the C<-M> switch>
392 <L raw="click B<here>|page/About the C<-M> switch" section="About the -M switch" to="page" type="pod">
394 click B<here>
395 </L>
396 Specifically, notice that the formatting codes are present and
398 unescaped in raw.
399 There is a known bug in the raw attribute where any surrounding
401 whitespace is condensed into a single ' '. For example, given L<
402 link>, raw will be " link".
403 events with an element_name of E or Z
405 While there are Pod codes E<...> and Z<>, these do not produce any
406 E or Z events -- that is, there are no such events as E or Z.
407 events with an element_name of Verbatim
409 When a Pod verbatim paragraph (AKA "codeblock") is parsed, it
410 produces this event structure:
411 <Verbatim start_line="543" xml:space="preserve">
413 ...text...
414 </Verbatim>
415 The value of the start_line attribute will be the line number of
417 the first line of this verbatim block. The xml:space attribute is
418 always present, and always has the value "preserve".
419 The text content will have tabs already expanded.
421 events with an element_name of head1 .. head4
423 When a "=head1 ..." directive is parsed, it produces this event
424 structure:
425 <head1>
427 ...stuff...
428 </head1>
429 For example, a directive consisting of this:
431 =head1 Options to C<new> et al.
433 will produce this event structure:
435 <head1 start_line="543">
437 Options to
438 <C>
439 new
440 </C>
441 et al.
442 </head1>
443 "=head2" through "=head4" directives are the same, except for the
445 element names in the event structure.
446 events with an element_name of encoding
448 In the default case, the events corresponding to "=encoding"
449 directives are not emitted. They are emitted if
450 "keep_encoding_directive" is true. In that case they produce event
451 structures like "events with an element_name of head1 .. head4"
452 above.
453 events with an element_name of over-bullet
455 When an "=over ... =back" block is parsed where the items are a
456 bulleted list, it will produce this event structure:
457 <over-bullet indent="4" start_line="543">
459 <item-bullet start_line="545">
460 ...Stuff...
461 </item-bullet>
462 ...more item-bullets...
463 </over-bullet fake-closer="1">
464 The attribute fake-closer is only present if it is a true value; it
466 is not present if it is a false value. It is shown in the above
467 example to illustrate where the attribute is (in the closing tag).
468 It signifies that the "=over" did not have a matching "=back", and
469 thus Pod::Simple had to create a fake closer.
470 For example, this Pod source:
472 =over
474 =item *
476 Something
478 =back
480 Would produce an event structure that does not have the fake-closer
482 attribute, whereas this Pod source:
483 =over
485 =item *
487 Gasp! An unclosed =over block!
489 would. The rest of the over-* examples will not demonstrate this
491 attribute, but they all can have it. See Pod::Checker's source for
492 an example of this attribute being used.
493 The value of the indent attribute is whatever value is after the
495 "=over" directive, as in "=over 8". If no such value is specified
496 in the directive, then the indent attribute has the value "4".
497 For example, this Pod source:
499 =over
501 =item *
503 Stuff
505 =item *
507 Bar I<baz>!
509 =back
511 produces this event structure:
513 <over-bullet indent="4" start_line="10">
515 <item-bullet start_line="12">
516 Stuff
517 </item-bullet>
518 <item-bullet start_line="14">
519 Bar <I>baz</I>!
520 </item-bullet>
521 </over-bullet>
522 events with an element_name of over-number
524 When an "=over ... =back" block is parsed where the items are a
525 numbered list, it will produce this event structure:
526 <over-number indent="4" start_line="543">
528 <item-number number="1" start_line="545">
529 ...Stuff...
530 </item-number>
531 ...more item-number...
532 </over-bullet>
533 This is like the "over-bullet" event structure; but note that the
535 contents are "item-number" instead of "item-bullet", and note that
536 they will have a "number" attribute, which some
537 formatters/processors may ignore (since, for example, there's no
538 need for it in HTML when producing an "<UL><LI>...</LI>...</UL>"
539 structure), but which any processor may use.
540 Note that the values for the number attributes of "item-number"
542 elements in a given "over-number" area will start at 1 and go up by
543 one each time. If the Pod source doesn't follow that order (even
544 though it really should!), whatever numbers it has will be ignored
545 (with the correct values being put in the number attributes), and
546 an error message might be issued to the user.
547 events with an element_name of over-text
549 These events are somewhat unlike the other over-* structures, as
550 far as what their contents are. When an "=over ... =back" block is
551 parsed where the items are a list of text "subheadings", it will
552 produce this event structure:
553 <over-text indent="4" start_line="543">
555 <item-text>
556 ...stuff...
557 </item-text>
558 ...stuff (generally Para or Verbatim elements)...
559 <item-text>
560 ...more item-text and/or stuff...
561 </over-text>
562 The indent and fake-closer attributes are as with the other over-*
564 events.
565 For example, this Pod source:
567 =over
569 =item Foo
571 Stuff
573 =item Bar I<baz>!
575 Quux
577 =back
579 produces this event structure:
581 <over-text indent="4" start_line="20">
583 <item-text start_line="22">
584 Foo
585 </item-text>
586 <Para start_line="24">
587 Stuff
588 </Para>
589 <item-text start_line="26">
590 Bar
591 <I>
592 baz
593 </I>
594 !
595 </item-text>
596 <Para start_line="28">
597 Quux
598 </Para>
599 </over-text>
600 events with an element_name of over-block
602 These events are somewhat unlike the other over-* structures, as
603 far as what their contents are. When an "=over ... =back" block is
604 parsed where there are no items, it will produce this event
605 structure:
606 <over-block indent="4" start_line="543">
608 ...stuff (generally Para or Verbatim elements)...
609 </over-block>
610 The indent and fake-closer attributes are as with the other over-*
612 events.
613 For example, this Pod source:
615 =over
617 For cutting off our trade with all parts of the world
619 For transporting us beyond seas to be tried for pretended offenses
621 He is at this time transporting large armies of foreign mercenaries to
623 complete the works of death, desolation and tyranny, already begun with
624 circumstances of cruelty and perfidy scarcely paralleled in the most
625 barbarous ages, and totally unworthy the head of a civilized nation.
626 =back
628 will produce this event structure:
630 <over-block indent="4" start_line="2">
632 <Para start_line="4">
633 For cutting off our trade with all parts of the world
634 </Para>
635 <Para start_line="6">
636 For transporting us beyond seas to be tried for pretended offenses
637 </Para>
638 <Para start_line="8">
639 He is at this time transporting large armies of [...more text...]
640 </Para>
641 </over-block>
642 events with an element_name of over-empty
644 Note: These events are only triggered if "parse_empty_lists()" is
645 set to a true value.
646 These events are somewhat unlike the other over-* structures, as
648 far as what their contents are. When an "=over ... =back" block is
649 parsed where there is no content, it will produce this event
650 structure:
651 <over-empty indent="4" start_line="543">
653 </over-empty>
654 The indent and fake-closer attributes are as with the other over-*
656 events.
657 For example, this Pod source:
659 =over
661 =over
663 =back
665 =back
667 will produce this event structure:
669 <over-block indent="4" start_line="1">
671 <over-empty indent="4" start_line="3">
672 </over-empty>
673 </over-block>
674 Note that the outer "=over" is a block because it has no "=item"s
676 but still has content: the inner "=over". The inner "=over", in
677 turn, is completely empty, and is treated as such.
678 events with an element_name of item-bullet
680 See "events with an element_name of over-bullet", above.
681 events with an element_name of item-number
683 See "events with an element_name of over-number", above.
684 events with an element_name of item-text
686 See "events with an element_name of over-text", above.
687 events with an element_name of for
689 TODO...
690 events with an element_name of Data
692 TODO...
693
695 Pod::Simple provides a lot of methods that aren't generally interesting
696 to the end user of an existing Pod formatter, but some of which you
697 might find useful in writing a Pod formatter. They are listed below.
698 The first several methods (the accept_* methods) are for declaring the
699 capabilities of your parser, notably what "=for targetname" sections
700 it's interested in, what extra N<...> codes it accepts beyond the ones
701 described in the perlpod.
702 "$parser->accept_targets( SOMEVALUE )"
704 As the parser sees sections like:
705 =for html <img src="fig1.jpg">
707 or
709 =begin html
711 <img src="fig1.jpg">
713 =end html
715 ...the parser will ignore these sections unless your subclass has
717 specified that it wants to see sections targeted to "html" (or
718 whatever the formatter name is).
719 If you want to process all sections, even if they're not targeted
721 for you, call this before you start parsing:
722 $parser->accept_targets('*');
724 "$parser->accept_targets_as_text( SOMEVALUE )"
726 This is like accept_targets, except that it specifies also that the
727 content of sections for this target should be treated as Pod text
728 even if the target name in "=for targetname" doesn't start with a
729 ":".
730 At time of writing, I don't think you'll need to use this.
732 "$parser->accept_codes( Codename, Codename... )"
734 This tells the parser that you accept additional formatting codes,
735 beyond just the standard ones (I B C L F S X, plus the two weird
736 ones you don't actually see in the parse tree, Z and E). For
737 example, to also accept codes "N", "R", and "W":
738 $parser->accept_codes( qw( N R W ) );
740 TODO: document how this interacts with =extend, and long element
742 names
743 "$parser->accept_directive_as_data( directive_name )"
745 "$parser->accept_directive_as_verbatim( directive_name )"
746 "$parser->accept_directive_as_processed( directive_name )"
747 In the unlikely situation that you need to tell the parser that you
748 will accept additional directives ("=foo" things), you need to
749 first set the parser to treat its content as data (i.e., not really
750 processed at all), or as verbatim (mostly just expanding tabs), or
751 as processed text (parsing formatting codes like B<...>).
752 For example, to accept a new directive "=method", you'd presumably
754 use:
755 $parser->accept_directive_as_processed("method");
757 so that you could have Pod lines like:
759 =method I<$whatever> thing B<um>
761 Making up your own directives breaks compatibility with other Pod
763 formatters, in a way that using "=for target ..." lines doesn't;
764 however, you may find this useful if you're making a Pod superset
765 format where you don't need to worry about compatibility.
766 "$parser->nbsp_for_S( BOOLEAN );"
768 Setting this attribute to a true value (and by default it is false)
769 will turn "S<...>" sequences into sequences of words separated by
770 "\xA0" (non-breaking space) characters. For example, it will take
771 this:
772 I like S<Dutch apple pie>, don't you?
774 and treat it as if it were:
776 I like DutchE<nbsp>appleE<nbsp>pie, don't you?
778 This is handy for output formats that don't have anything quite
780 like an "S<...>" code, but which do have a code for non-breaking
781 space.
782 There is currently no method for going the other way; but I can
784 probably provide one upon request.
785 "$parser->version_report()"
787 This returns a string reporting the $VERSION value from your module
788 (and its classname) as well as the $VERSION value of Pod::Simple.
789 Note that perlpodspec requires output formats (wherever possible)
790 to note this detail in a comment in the output format. For
791 example, for some kind of SGML output format:
792 print OUT "<!-- \n", $parser->version_report, "\n -->";
794 "$parser->pod_para_count()"
796 This returns the count of Pod paragraphs seen so far.
797 "$parser->line_count()"
799 This is the current line number being parsed. But you might find
800 the "line_number" event attribute more accurate, when it is
801 present.
802 "$parser->nix_X_codes( SOMEVALUE )"
804 This attribute, when set to a true value (and it is false by
805 default) ignores any "X<...>" sequences in the document being
806 parsed. Many formats don't actually use the content of these
807 codes, so have no reason to process them.
808 "$parser->keep_encoding_directive( SOMEVALUE )"
810 This attribute, when set to a true value (it is false by default)
811 will keep "=encoding" and its content in the event structure. Most
812 formats don't actually need to process the content of an
813 "=encoding" directive, even when this directive sets the encoding
814 and the processor makes use of the encoding information. Indeed, it
815 is possible to know the encoding without processing the directive
816 content.
817 "$parser->merge_text( SOMEVALUE )"
819 This attribute, when set to a true value (and it is false by
820 default) makes sure that only one event (or token, or node) will be
821 created for any single contiguous sequence of text. For example,
822 consider this somewhat contrived example:
823 I just LOVE Z<>hotE<32>apple pie!
825 When that is parsed and events are about to be called on it, it may
827 actually seem to be four different text events, one right after
828 another: one event for "I just LOVE ", one for "hot", one for " ",
829 and one for "apple pie!". But if you have merge_text on, then
830 you're guaranteed that it will be fired as one text event: "I just
831 LOVE hot apple pie!".
832 "$parser->code_handler( CODE_REF )"
834 This specifies code that should be called when a code line is seen
835 (i.e., a line outside of the Pod). Normally this is undef, meaning
836 that no code should be called. If you provide a routine, it should
837 start out like this:
838 sub get_code_line { # or whatever you'll call it
840 my($line, $line_number, $parser) = @_;
841 ...
842 }
843 Note, however, that sometimes the Pod events aren't processed in
845 exactly the same order as the code lines are -- i.e., if you have a
846 file with Pod, then code, then more Pod, sometimes the code will be
847 processed (via whatever you have code_handler call) before the all
848 of the preceding Pod has been processed.
849 "$parser->cut_handler( CODE_REF )"
851 This is just like the code_handler attribute, except that it's for
852 "=cut" lines, not code lines. The same caveats apply. "=cut" lines
853 are unlikely to be interesting, but this is included for
854 completeness.
855 "$parser->pod_handler( CODE_REF )"
857 This is just like the code_handler attribute, except that it's for
858 "=pod" lines, not code lines. The same caveats apply. "=pod" lines
859 are unlikely to be interesting, but this is included for
860 completeness.
861 "$parser->whiteline_handler( CODE_REF )"
863 This is just like the code_handler attribute, except that it's for
864 lines that are seemingly blank but have whitespace (" " and/or
865 "\t") on them, not code lines. The same caveats apply. These lines
866 are unlikely to be interesting, but this is included for
867 completeness.
868 "$parser->whine( linenumber, complaint string )"
870 This notes a problem in the Pod, which will be reported in the "Pod
871 Errors" section of the document and/or sent to STDERR, depending on
872 the values of the attributes "no_whining", "no_errata_section", and
873 "complain_stderr".
874 "$parser->scream( linenumber, complaint string )"
876 This notes an error like "whine" does, except that it is not
877 suppressible with "no_whining". This should be used only for very
878 serious errors.
879 "$parser->source_dead(1)"
881 This aborts parsing of the current document, by switching on the
882 flag that indicates that EOF has been seen. In particularly
883 drastic cases, you might want to do this. It's rather nicer than
884 just calling "die"!
885 "$parser->hide_line_numbers( SOMEVALUE )"
887 Some subclasses that indiscriminately dump event attributes (well,
888 except for ones beginning with "~") can use this object attribute
889 for refraining to dump the "start_line" attribute.
890 "$parser->no_whining( SOMEVALUE )"
892 This attribute, if set to true, will suppress reports of non-fatal
893 error messages. The default value is false, meaning that
894 complaints are reported. How they get reported depends on the
895 values of the attributes "no_errata_section" and "complain_stderr".
896 "$parser->no_errata_section( SOMEVALUE )"
898 This attribute, if set to true, will suppress generation of an
899 errata section. The default value is false -- i.e., an errata
900 section will be generated.
901 "$parser->complain_stderr( SOMEVALUE )"
903 This attribute, if set to true will send complaints to STDERR. The
904 default value is false -- i.e., complaints do not go to STDERR.
905 "$parser->bare_output( SOMEVALUE )"
907 Some formatter subclasses use this as a flag for whether output
908 should have prologue and epilogue code omitted. For example,
909 setting this to true for an HTML formatter class should omit the
910 "<html><head><title>...</title><body>..." prologue and the
911 "</body></html>" epilogue.
912 If you want to set this to true, you should probably also set
914 "no_whining" or at least "no_errata_section" to true.
915 "$parser->preserve_whitespace( SOMEVALUE )"
917 If you set this attribute to a true value, the parser will try to
918 preserve whitespace in the output. This means that such formatting
919 conventions as two spaces after periods will be preserved by the
920 parser. This is primarily useful for output formats that treat
921 whitespace as significant (such as text or *roff, but not HTML).
922 "$parser->parse_empty_lists( SOMEVALUE )"
924 If this attribute is set to true, the parser will not ignore empty
925 "=over"/"=back" blocks. The type of "=over" will be empty,
926 documented above, "events with an element_name of over-empty".
927
929 Pod::Simple -- event-based Pod-parsing framework
930 Pod::Simple::Methody -- like Pod::Simple, but each sort of event calls
932 its own method (like "start_head3")
933 Pod::Simple::PullParser -- a Pod-parsing framework like Pod::Simple,
935 but with a token-stream interface
936 Pod::Simple::SimpleTree -- a Pod-parsing framework like Pod::Simple,
938 but with a tree interface
939 Pod::Simple::Checker -- a simple Pod::Simple subclass that reads
941 documents, and then makes a plaintext report of any errors found in the
942 document
943 Pod::Simple::DumpAsXML -- for dumping Pod documents as tidily indented
945 XML, showing each event on its own line
946 Pod::Simple::XMLOutStream -- dumps a Pod document as XML (without
948 introducing extra whitespace as Pod::Simple::DumpAsXML does).
949 Pod::Simple::DumpAsText -- for dumping Pod documents as tidily indented
951 text, showing each event on its own line
952 Pod::Simple::LinkSection -- class for objects representing the values
954 of the TODO and TODO attributes of L<...> elements
955 Pod::Escapes -- the module that Pod::Simple uses for evaluating E<...>
957 content
958 Pod::Simple::Text -- a simple plaintext formatter for Pod
960 Pod::Simple::TextContent -- like Pod::Simple::Text, but makes no effort
962 for indent or wrap the text being formatted
963 Pod::Simple::HTML -- a simple HTML formatter for Pod
965 perlpod
967 perlpodspec
969 perldoc
971
973 Questions or discussion about POD and Pod::Simple should be sent to the
974 pod-people@perl.org mail list. Send an empty email to
975 pod-people-subscribe@perl.org to subscribe.
976 This module is managed in an open GitHub repository,
978 <https://github.com/perl-pod/pod-simple/>. Feel free to fork and
979 contribute, or to clone <git://github.com/perl-pod/pod-simple.git> and
980 send patches!
981 Patches against Pod::Simple are welcome. Please send bug reports to
983 <bug-pod-simple@rt.cpan.org>.
984
986 Copyright (c) 2002 Sean M. Burke.
987 This library is free software; you can redistribute it and/or modify it
989 under the same terms as Perl itself.
990 This program is distributed in the hope that it will be useful, but
992 without any warranty; without even the implied warranty of
993 merchantability or fitness for a particular purpose.
994
996 Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. But don't
997 bother him, he's retired.
998 Pod::Simple is maintained by:
1000 · Allison Randal "allison@perl.org"
1002 · Hans Dieter Pearcey "hdp@cpan.org"
1004 · David E. Wheeler "dwheeler@cpan.org"
1006perl v5.30.1 2020-01-30 Pod::Simple::Subclassing(3)