NAME¶
Pod::Eventual - read a POD document as a series of trivial events
VERSION¶
version 0.094001
SYNOPSIS¶
package Your::Pod::Parser;
use base 'Pod::Eventual';
sub handle_event {
my ($self, $event) = @_;
print Dumper($event);
}
DESCRIPTION¶
POD is a pretty simple format to write, but it can be a big pain to deal with
reading it and doing anything useful with it. Most existing POD parsers care
about semantics, like whether a "=item" occurred after an
"=over" but before a "back", figuring out how to link a
"L<>", and other things like that.
Pod::Eventual is much less ambitious and much more stupid. Fortunately, stupid
is often better. (That's what I keep telling myself, anyway.)
Pod::Eventual reads line-based input and produces events describing each POD
paragraph or directive it finds. Once complete events are immediately passed
to the "handle_event" method. This method should be implemented by
Pod::Eventual subclasses. If it isn't, Pod::Eventual's own
"handle_event" will be called, and will raise an exception.
METHODS¶
read_handle¶
Pod::Eventual->read_handle($io_handle, \%arg);
This method iterates through the lines of a handle, producing events and calling
the "handle_event" method.
The only valid argument in %arg (for now) is "in_pod", which indicates
whether we should assume that we are parsing pod when we start parsing the
file. By default, this is false.
This is useful to behave differently when reading a
.pm or
.pod
file.
Important: the handle is expected to have an encoding layer so that it
will return text, not bytes, on reads.
read_file¶
This behaves just like "read_handle", but expects a filename rather
than a handle. The file will be assumed to be UTF-8 encoded.
read_string¶
This behaves just like "read_handle", but expects a string containing
POD text rather than a handle.
handle_event¶
This method is called each time Pod::Evental finishes scanning for a new POD
event. It must be implemented by a subclass or it will raise an exception.
handle_nonpod¶
This method is called each time a non-POD segment is seen -- that is, lines
after "=cut" and before another command.
If unimplemented by a subclass, it does nothing by default.
handle_blank¶
This method is called at the end of a sequence of one or more blank lines.
If unimplemented by a subclass, it does nothing by default.
EVENTS¶
There are four kinds of events that Pod::Eventual will produce. All are
represented as hash references.
Command Events¶
These events represent commands -- those things that start with an equals sign
in the first column. Here are some examples of POD and the event that would be
produced.
A simple header:
=head1 NAME
{ type => 'command', command => 'head1', content => "NAME\n", start_line => 4 }
Notice that the content includes the trailing newline. That's to maintain
similarity with this possibly-surprising case:
=for HTML
We're actually still in the command event, here.
{
type => 'command',
command => 'for',
content => "HTML\nWe're actually still in the command event, here.\n",
start_line => 8,
}
Pod::Eventual does not care what the command is. It doesn't keep track of what
it's seen or whether you've used a command that isn't defined. The only
special case is "=cut", which is never more than one line.
=cut
We are no longer parsing POD when this line is read.
{
type => 'command',
command => 'cut',
content => "\n",
start_line => 15,
}
Waiving this special case may be an option in the future.
Text Events¶
A text event is just a paragraph of text, beginning after one or more empty
lines and running until the next empty line (or
=cut). In Perl 5's
standard usage of Pod, text content that begins with whitespace is a
"verbatim" paragraph, and text content that begins with
non-whitespace is an "ordinary" paragraph.
Pod::Eventual doesn't care.
Text events look like this:
{
type => 'text',
content => "a string of text ending with a\n",
start_line => 16,
}
Blank events¶
These events represent blank lines (or many blank lines) within a Pod section.
Blank events look like this:
{
type => 'blank',
content => "\n\n\n\n",
start_line => 21,
}
Non-Pod events¶
These events represent non-Pod segments of the input.
Non-Pod events look like this:
{
type => 'nonpod',
content => "#!/usr/bin/perl\nuse strict;\n\nuse Acme::ProgressBar\n\n",
start_line => 1,
}
AUTHOR¶
Ricardo SIGNES <rjbs@cpan.org>
COPYRIGHT AND LICENSE¶
This software is copyright (c) 2013 by Ricardo SIGNES.
This is free software; you can redistribute it and/or modify it under the same
terms as the Perl 5 programming language system itself.