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::Eventual 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.

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,
  }