Rechercher une page de manuel
Pod::Eventual.3pm
Langue: en
Version: 2009-11-13 (ubuntu - 24/10/10)
Section: 3 (Bibliothèques de fonctions)
Sommaire
NAME
Pod::Eventual - read a POD document as a series of trivial eventsVERSION
version 0.093170SYNOPSIS
package Your::Pod::Parser; our $VERSION = '0.093170'; 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.
read_file
This behaves just like "read_handle", but expects a filename rather than a handle.read_string
This behaves just like "read_handle", but expects a string containing POD 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) 2009 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.
Contenus ©2006-2024 Benjamin Poulain
Design ©2006-2024 Maxime Vantorre