Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  POD::EVENTUAL (3)

.ds Aq ’


Pod::Eventual - read a POD document as a series of trivial events



version 0.094001


  package Your::Pod::Parser;
  use base Pod::Eventual;

  sub handle_event {
    my ($self, $event) = @_;

    print Dumper($event);


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.



  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.

<B>Important:B> the handle is expected to have an encoding layer so that it will return text, not bytes, on reads.


This behaves just like read_handle, but expects a filename rather than a handle. The file will be assumed to be UTF-8 encoded.


This behaves just like read_handle, but expects a string containing POD text rather than a handle.


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.


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.


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.


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
  Were actually still in the command event, here.

    type    => command,
    command => for,
    content => "HTML\nWere 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.

  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,


Ricardo SIGNES <>


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.

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 POD::EVENTUAL (3) 2013-11-06

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.