Unix/Linux Go Back    


CentOS 7.0 - man page for pod::eventual (centos section 3)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

SYNOPSIS
	 package Your::Pod::Parser;
       our $VERSION = '0.093330';

	 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.

perl v5.16.3				    2009-11-29				 Pod::Eventual(3)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:35 AM.