table of contents
other versions
- wheezy 5.14.2-21+deb7u3
- jessie 5.20.2-3+deb8u6
- testing 5.24.1-3
- unstable 5.24.1-3
- experimental 5.26.0-1
other sections
Pod::Simple::Subclassing(3perl) | Perl Programmers Reference Guide | Pod::Simple::Subclassing(3perl) |
NAME¶
Pod::Simple::Subclassing -- write a formatter as a Pod::Simple subclassSYNOPSIS¶
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) = @_; ... } sub _handle_text { my($parser, $text) = @_; ... } 1;
DESCRIPTION¶
This document is about using Pod::Simple to write a Pod processor, generally a Pod formatter. If you just want to know about using an existing Pod formatter, instead see its documentation and see also the docs in Pod::Simple. The zeroeth step in writing a Pod formatter is to make sure that there isn't already a decent one in CPAN. See <http://search.cpan.org/>, and run a search on the name of the format you want to render to. Also consider joining the Pod People list http://lists.perl.org/showlist.cgi?name=pod-people <http://lists.perl.org/showlist.cgi?name=pod-people> and asking whether anyone has a formatter for that format -- maybe someone cobbled one together but just hasn't released it. The first step in writing a Pod processor is to read perlpodspec, which contains notes information on writing a Pod parser (which has been largely taken care of by Pod::Simple), but also a lot of requirements and recommendations for writing a formatter. The second step is to actually learn the format you're planning to format to -- or at least as much as you need to know to represent Pod, which probably isn't much. The third step is to pick which of Pod::Simple's interfaces you want to use -- the basic interface via Pod::Simple or Pod::Simple::Methody is event-based, sort of like HTML::Parser's interface, or sort of like XML::Parser's "Handlers" interface), but Pod::Simple::PullParser provides a token-stream interface, sort of like HTML::TokeParser's interface; Pod::Simple::SimpleTree provides a simple tree interface, rather like XML::Parser's "Tree" interface. Users familiar with XML-handling will find one of these styles relatively familiar; but if you would be even more at home with XML, there are classes that produce an XML representation of the Pod stream, notably Pod::Simple::XMLOutStream; you can feed the output of such a class to whatever XML parsing system you are most at home with. The last step is to write your code based on how the events (or tokens, or tree-nodes, or the XML, or however you're parsing) will map to constructs in the output format. Also sure to consider how to escape text nodes containing arbitrary text, and also what to do with text nodes that represent preformatted text (from verbatim sections).Events¶
TODO intro... mention that events are supplied for implicits, like for missing >'s In the following section, we use XML to represent the event structure associated with a particular construct. That is, TODO- "$parser->_handle_element_start( element_name, attr_hashref )"
- "$parser->_handle_element_end( element_name )"
- "$parser->_handle_text( text_string )"
- events with an element_name of Document
- Parsing a document produces this event structure:
<Document start_line="543"> ...all events... </Document>
<Document contentless="1" start_line="543"> </Document>
- events with an element_name of Para
- Parsing a plain (non-verbatim, non-directive, non-data)
paragraph in a Pod document produces this event structure:
<Para start_line="543"> ...all events in this paragraph... </Para>
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>
- events with an element_name of B, C, F, or I.
- Parsing a B<...> formatting code (or of course any of
its semantically identical syntactic variants
B<< ... >>, or
B<<<< ... >>>>, etc.) produces this
event structure:
<B> ...stuff... </B>
- events with an element_name of S
- Normally, parsing an S<...> sequence produces this
event structure, just as if it were a B/C/F/I code:
<S> ...stuff... </S>
- events with an element_name of X
- Normally, parsing an X<...> sequence produces this
event structure, just as if it were a B/C/F/I code:
<X> ...stuff... </X>
- events with an element_name of L
- Because the L<...> is the most complex construct in
the language, it should not surprise you that the events it generates are
the most complex in the language. Most of complexity is hidden away in the
attribute values, so for those of you writing a Pod formatter that
produces a non-hypertextual format, you can just ignore the attributes and
treat an L event structure like a formatting element that (presumably)
doesn't actually produce a change in formatting. That is, the content of
the L event structure (as opposed to its attributes) is always what text
should be displayed.
<L content-implicit="yes" to="that_url" type="url"> that_url </L>
L<http://www.perl.com/CPAN/authors/>
<L content-implicit="yes" to="http://www.perl.com/CPAN/authors/" type="url"> http://www.perl.com/CPAN/authors/ </L>
<L content-implicit="yes" to="manpage(section)" type="man"> manpage(section) </L>
L<crontab(5)>
<L content-implicit="yes" to="crontab(5)" type="man"> crontab(5) </L>
L<crontab(5)/"ENVIRONMENT">
<L content-implicit="yes" section="ENVIRONMENT" to="crontab(5)" type="man"> "ENVIRONMENT" in crontab(5) </L>
L<hell itself!|crontab(5)>
<L to="crontab(5)" type="man"> hell itself! </L>
<L content-implicit="yes" to="Net::Ping" type="pod"> podpage </L>
L<Net::Ping>
<L content-implicit="yes" to="Net::Ping" type="pod"> Net::Ping </L>
L<Perl Error Messages|perldiag>
<L to="perldiag" type="pod"> Perl Error Messages </L>
L</"Member Data">
<L content-implicit="yes" section="Member Data" type="pod"> "Member Data" </L>
L<the various attributes|/"Member Data">
<L section="Member Data" type="pod"> the various attributes </L>
L<perlsyn/"Basic BLOCKs and Switch Statements">
<L content-implicit="yes" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod"> "Basic BLOCKs and Switch Statements" in perlsyn </L>
L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements">
<L 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" section="Member Data" type="pod"> "Member Data" </L>
- events with an element_name of E or Z
- While there are Pod codes E<...> and Z<>, these do not produce any E or Z events -- that is, there are no such events as E or Z.
- events with an element_name of Verbatim
- When a Pod verbatim paragraph (AKA "codeblock")
is parsed, it produces this event structure:
<Verbatim start_line="543" xml:space="preserve"> ...text... </Verbatim>
- events with an element_name of head1 .. head4
- When a "=head1 ..." directive is parsed, it
produces this event structure:
<head1> ...stuff... </head1>
=head1 Options to C<new> et al.
<head1 start_line="543"> Options to <C> new </C> et al. </head1>
- events with an element_name of over-bullet
- When an "=over ... =back" block is parsed where
the items are a bulleted list, it will produce this event structure:
<over-bullet indent="4" start_line="543"> <item-bullet start_line="545"> ...Stuff... </item-bullet> ...more item-bullets... </over-bullet>
=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>
- events with an element_name of over-number
- When an "=over ... =back" block is parsed where
the items are a numbered list, it will produce this event structure:
<over-number indent="4" start_line="543"> <item-number number="1" start_line="545"> ...Stuff... </item-number> ...more item-number... </over-bullet>
- events with an element_name of over-text
- These events are are somewhat unlike the other over-*
structures, as far as what their contents are. When an "=over ...
=back" block is parsed where the items are a list of text
"subheadings", it will produce this event structure:
<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>
=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>
- events with an element_name of over-block
- These events are are somewhat unlike the other over-*
structures, as far as what their contents are. When an "=over ...
=back" block is parsed where there are no items, it will produce this
event structure:
<over-block indent="4" start_line="543"> ...stuff (generally Para or Verbatim elements)... </over-block>
=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. =cut
<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>
- events with an element_name of item-bullet
- See "events with an element_name of over-bullet", above.
- events with an element_name of item-number
- See "events with an element_name of over-number", above.
- events with an element_name of item-text
- See "events with an element_name of over-text", above.
- events with an element_name of for
- TODO...
- events with an element_name of Data
- TODO...
More Pod::Simple Methods¶
Pod::Simple provides a lot of methods that aren't generally interesting to the end user of an existing Pod formatter, but some of which you might find useful in writing a Pod formatter. They are listed below. The first several methods (the accept_* methods) are for declaring the capabilities of your parser, notably what "=for targetname" sections it's interested in, what extra N<...> codes it accepts beyond the ones described in the perlpod.- "$parser->accept_targets( SOMEVALUE )"
- As the parser sees sections like:
=for html <img src="fig1.jpg">
=begin html <img src="fig1.jpg"> =end html
$parser->accept_targets('*');
- "$parser->accept_targets_as_text( SOMEVALUE )"
- This is like accept_targets, except that it specifies also
that the content of sections for this target should be treated as Pod text
even if the target name in "=for targetname" doesn't
start with a ":".
- "$parser->accept_codes( Codename, Codename... )"
- This tells the parser that you accept additional formatting
codes, beyond just the standard ones (I B C L F S X, plus the two weird
ones you don't actually see in the parse tree, Z and E). For example, to
also accept codes "N", "R", and "W":
$parser->accept_codes( qw( N R W ) );
- "$parser->accept_directive_as_data( directive_name )"
- "$parser->accept_directive_as_verbatim( directive_name )"
- "$parser->accept_directive_as_processed( directive_name )"
- In the unlikely situation that you need to tell the parser
that you will accept additional directives ("=foo" things), you
need to first set the parset to treat its content as data (i.e., not
really processed at all), or as verbatim (mostly just expanding tabs), or
as processed text (parsing formatting codes like B<...>).
$parser->accept_directive_as_processed("method");
=method I<$whatever> thing B<um>
- "$parser->nbsp_for_S( BOOLEAN );"
- Setting this attribute to a true value (and by default it
is false) will turn "S<...>" sequences into sequences of
words separated by "\xA0" (non-breaking space) characters. For
example, it will take this:
I like S<Dutch apple pie>, don't you?
I like DutchE<nbsp>appleE<nbsp>pie, don't you?
- "$parser->version_report()"
- This returns a string reporting the $VERSION value from
your module (and its classname) as well as the $VERSION value of
Pod::Simple. Note that perlpodspec requires output formats (wherever
possible) to note this detail in a comment in the output format. For
example, for some kind of SGML output format:
print OUT "<!-- \n", $parser->version_report, "\n -->";
- "$parser->pod_para_count()"
- This returns the count of Pod paragraphs seen so far.
- "$parser->line_count()"
- This is the current line number being parsed. But you might find the "line_number" event attribute more accurate, when it is present.
- "$parser->nix_X_codes( SOMEVALUE )"
- This attribute, when set to a true value (and it is false by default) ignores any "X<...>" sequences in the document being parsed. Many formats don't actually use the content of these codes, so have no reason to process them.
- "$parser->merge_text( SOMEVALUE )"
- This attribute, when set to a true value (and it is false
by default) makes sure that only one event (or token, or node) will be
created for any single contiguous sequence of text. For example, consider
this somewhat contrived example:
I just LOVE Z<>hotE<32>apple pie!
- "$parser->code_handler( CODE_REF )"
- This specifies code that should be called when a code line
is seen (i.e., a line outside of the Pod). Normally this is undef, meaning
that no code should be called. If you provide a routine, it should start
out like this:
sub get_code_line { # or whatever you'll call it my($line, $line_number, $parser) = @_; ... }
- "$parser->cut_handler( CODE_REF )"
- This is just like the code_handler attribute, except that it's for "=cut" lines, not code lines. The same caveats apply. "=cut" lines are unlikely to be interesting, but this is included for completeness.
- "$parser->whine( linenumber, complaint string )"
- This notes a problem in the Pod, which will be reported to in the "Pod Errors" section of the document and/or send to STDERR, depending on the values of the attributes "no_whining", "no_errata_section", and "complain_stderr".
- "$parser->scream( linenumber, complaint string )"
- This notes an error like "whine" does, except that it is not suppressible with "no_whining". This should be used only for very serious errors.
- "$parser->source_dead(1)"
- This aborts parsing of the current document, by switching on the flag that indicates that EOF has been seen. In particularly drastic cases, you might want to do this. It's rather nicer than just calling "die"!
- "$parser->hide_line_numbers( SOMEVALUE )"
- Some subclasses that indiscriminately dump event attributes (well, except for ones beginning with "~") can use this object attribute for refraining to dump the "start_line" attribute.
- "$parser->no_whining( SOMEVALUE )"
- This attribute, if set to true, will suppress reports of non-fatal error messages. The default value is false, meaning that complaints are reported. How they get reported depends on the values of the attributes "no_errata_section" and "complain_stderr".
- "$parser->no_errata_section( SOMEVALUE )"
- This attribute, if set to true, will suppress generation of an errata section. The default value is false -- i.e., an errata section will be generated.
- "$parser->complain_stderr( SOMEVALUE )"
- This attribute, if set to true will send complaints to STDERR. The default value is false -- i.e., complaints do not go to STDERR.
- "$parser->bare_output( SOMEVALUE )"
- Some formatter subclasses use this as a flag for whether
output should have prologue and epilogue code omitted. For example,
setting this to true for an HTML formatter class should omit the
"<html><head><title>...</title><body>..."
prologue and the "</body></html>" epilogue.
- "$parser->preserve_whitespace( SOMEVALUE )"
- If you set this attribute to a true value, the parser will try to preserve whitespace in the output. This means that such formatting conventions as two spaces after periods will be preserved by the parser. This is primarily useful for output formats that treat whitespace as significant (such as text or *roff, but not HTML).
SEE ALSO¶
Pod::Simple -- event-based Pod-parsing framework Pod::Simple::Methody -- like Pod::Simple, but each sort of event calls its own method (like "start_head3") Pod::Simple::PullParser -- a Pod-parsing framework like Pod::Simple, but with a token-stream interface Pod::Simple::SimpleTree -- a Pod-parsing framework like Pod::Simple, but with a tree interface Pod::Simple::Checker -- a simple Pod::Simple subclass that reads documents, and then makes a plaintext report of any errors found in the document Pod::Simple::DumpAsXML -- for dumping Pod documents as tidily indented XML, showing each event on its own line Pod::Simple::XMLOutStream -- dumps a Pod document as XML (without introducing extra whitespace as Pod::Simple::DumpAsXML does). Pod::Simple::DumpAsText -- for dumping Pod documents as tidily indented text, showing each event on its own line Pod::Simple::LinkSection -- class for objects representing the values of the TODO and TODO attributes of L<...> elements Pod::Escapes -- the module the Pod::Simple uses for evaluating E<...> content Pod::Simple::Text -- a simple plaintext formatter for Pod Pod::Simple::TextContent -- like Pod::Simple::Text, but makes no effort for indent or wrap the text being formatted Pod::Simple::HTML -- a simple HTML formatter for Pod perlpod perlpodspec perldocSUPPORT¶
Questions or discussion about POD and Pod::Simple should be sent to the pod-people@perl.org mail list. Send an empty email to pod-people-subscribe@perl.org to subscribe. This module is managed in an open GitHub repository, http://github.com/theory/pod-simple/ <http://github.com/theory/pod-simple/>. Feel free to fork and contribute, or to clone git://github.com/theory/pod-simple.git <git://github.com/theory/pod-simple.git> and send patches! Patches against Pod::Simple are welcome. Please send bug reports to <bug-pod-simple@rt.cpan.org>.COPYRIGHT AND DISCLAIMERS¶
Copyright (c) 2002 Sean M. Burke. This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.AUTHOR¶
Pod::Simple was created by Sean M. Burke <sburke@cpan.org>. But don't bother him, he's retired. Pod::Simple is maintained by:- •
- Allison Randal "allison@perl.org"
- •
- Hans Dieter Pearcey "hdp@cpan.org"
- •
- David E. Wheeler "dwheeler@cpan.org"
2011-09-26 | perl v5.14.2 |