SEARCH
NEW RPMS
DIRECTORIES
ABOUT
FAQ
VARIOUS
BLOG
DONATE


YUM REPOSITORY

 
 

MAN page from Fedora 8 perl-Pod-Eventual-0.094001-15.el8.noarch.rpm

Pod::Eventual

Section: User Contributed Perl Documentation (3)
Updated: 2013-11-06
Index 

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 withreading it and doing anything useful with it. Most existing POD parsers careabout semantics, like whether a "=item" occurred after an "=over" but beforea "back", figuring out how to link a "L<>", and other things likethat.

Pod::Eventual is much less ambitious and much more stupid. Fortunately, stupidis often better. (That's what I keep telling myself, anyway.)

Pod::Eventual reads line-based input and produces events describing each PODparagraph or directive it finds. Once complete events are immediately passedto the "handle_event" method. This method should be implemented byPod::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 andcalling the "handle_event" method.

The only valid argument in %arg (for now) is "in_pod", which indicateswhether we should assume that we are parsing pod when we start parsing thefile. 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 willreturn text, not bytes, on reads. 

read_file

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

read_string

This behaves just like "read_handle", but expects a string containing PODtext rather than a handle. 

handle_event

This method is called each time Pod::Evental finishes scanning for a new PODevent. 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, linesafter "=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 arerepresented as hash references. 

Command Events

These events represent commands --- those things that start with an equals signin the first column. Here are some examples of POD and the event that would beproduced.

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 maintainsimilarity 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 whatit's seen or whether you've used a command that isn't defined. The onlyspecial 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 emptylines and running until the next empty line (or =cut). In Perl 5's standardusage 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 <rjbsAATTcpan.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 underthe same terms as the Perl 5 programming language system itself.


 

Index

NAME
VERSION
SYNOPSIS
DESCRIPTION
METHODS
read_handle
read_file
read_string
handle_event
handle_nonpod
handle_blank
EVENTS
Command Events
Text Events
Blank events
Non-Pod events
AUTHOR
COPYRIGHT AND LICENSE

This document was created byman2html,using the manual pages.