NAME

Pod::Event::Parser - A simple event based POD parser

SYNOPSIS

  use v6-alpha;
  use Pod::Event::Parser;
  
  parse("path/to/file.pod", %event_handlers);

DESCRIPTION

This is a straightforward event based POD parser, it is modeled after XML SAX parsers and is currently in the early stages of development.

LIMITATIONS & CAVEATS

Basic parsing functionality is fairly solid right now. The t/complex.t test actually roundtrip parses this document successfully. However, more complex POD documents may not do as well. Error reporting is still pretty minimal and the parser is not very forgiving about whitespace in some situations.

FUNCTIONS

parse (Str $filename, Hash %events)

The main parse function currently takes a $filename and a Hash of %events which it uses to process each line of the file.

EVENTS

Document Events

start_document

This event is fired when a '=pod' directive is reached.

end_document

This event is fired when a '=cut' directive is reached.

Element Events

For each POD element, an event is fired, the first argument to all these events is the $event_type (header, list, item, etc.).

start_element ('header', $size)

This event is fired once the '=head(n)' directive is reached. This does not include the text of the header, that will be processed as a interpolated string (to allow for any modifiers).

end_element ('header')

This event is fired after the '=head(n)' directive and it's accompanying text has been parsed.

start_element ('begin')

This event is fired when a '=begin' directive is reached.

end_element ('begin')

This event is fired when a '=end' directive (which is preceeded by an '=begin' directive) is reached.

start_element ('for')

This event is fired when a '=for' directive is reached.

end_element ('for')

This event is fired when a '=end' directive (which is preceeded by an '=for' directive) is reached.

start_element ('list')

This event is fired when an '=over' directive is reached.

end_element ('list')

This event is fired when a '=back' directive is reached.

start_element ('item')

This event is fired when an '=item' directive is reached, the next event fired will be any text which follows the item.

end_element ('item')

This event is fired once the last '=item' directive, followed by any text on the same line.

start_element ('verbatim')

This event is fired once a verbatim section is found.

end_element ('verbatim')

This event closes a verbatim section.

start_element ('line_interpolation')

This event is begun when any block of characters is interpolated for modifiers.

end_element ('line_interpolation')

This event is fired when interpolation is complete.

Modifier Events

start_modifier

This event is fired when a modifier is encountered.

end_modifier

This event closes a modifier.

Text Events

verbatim

This event handles the entire verbatim string.

string

This event processes raw strings.

newline

This event handles newlines in the text, it is a specialization of the 'string' event.

SEE ALSO

Any of the Perl5 POD parsers

XML::SAX

AUTHOR

stevan little, <stevan@iinteractive.com>

COPYRIGHT

Copyright (c) 2005. Stevan Little. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html