Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Pod::Eventual(3)      User Contributed Perl Documentation     Pod::Eventual(3)

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

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

perl v5.32.0			  2013-11-06		      Pod::Eventual(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | METHODS | EVENTS | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Pod::Eventual&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help