1Pod::Eventual(3)      User Contributed Perl Documentation     Pod::Eventual(3)
2
3
4

NAME

6       Pod::Eventual - read a POD document as a series of trivial events
7

VERSION

9       version 0.093330
10

SYNOPSIS

12         package Your::Pod::Parser;
13       our $VERSION = '0.093330';
14
15
16         use base 'Pod::Eventual';
17
18         sub handle_event {
19           my ($self, $event) = @_;
20
21           print Dumper($event);
22         }
23

DESCRIPTION

25       POD is a pretty simple format to write, but it can be a big pain to
26       deal with reading it and doing anything useful with it.  Most existing
27       POD parsers care about semantics, like whether a "=item" occurred after
28       an "=over" but before a "back", figuring out how to link a
29       "LE<lt>E<gt>", and other things like that.
30
31       Pod::Eventual is much less ambitious and much more stupid.
32       Fortunately, stupid is often better.  (That's what I keep telling
33       myself, anyway.)
34
35       Pod::Eventual reads line-based input and produces events describing
36       each POD paragraph or directive it finds.  Once complete events are
37       immediately passed to the "handle_event" method.  This method should be
38       implemented by Pod::Eventual subclasses.  If it isn't, Pod::Eventual's
39       own "handle_event" will be called, and will raise an exception.
40

METHODS

42   read_handle
43         Pod::Eventual->read_handle($io_handle, \%arg);
44
45       This method iterates through the lines of a handle, producing events
46       and calling the "handle_event" method.
47
48       The only valid argument in %arg (for now) is "in_pod", which indicates
49       whether we should assume that we are parsing pod when we start parsing
50       the file.  By default, this is false.
51
52       This is useful to behave differently when reading a .pm or .pod file.
53
54   read_file
55       This behaves just like "read_handle", but expects a filename rather
56       than a handle.
57
58   read_string
59       This behaves just like "read_handle", but expects a string containing
60       POD rather than a handle.
61
62   handle_event
63       This method is called each time Pod::Evental finishes scanning for a
64       new POD event.  It must be implemented by a subclass or it will raise
65       an exception.
66
67   handle_nonpod
68       This method is called each time a non-POD segment is seen -- that is,
69       lines after "=cut" and before another command.
70
71       If unimplemented by a subclass, it does nothing by default.
72
73   handle_blank
74       This method is called at the end of a sequence of one or more blank
75       lines.
76
77       If unimplemented by a subclass, it does nothing by default.
78

EVENTS

80       There are four kinds of events that Pod::Eventual will produce.  All
81       are represented as hash references.
82
83   Command Events
84       These events represent commands -- those things that start with an
85       equals sign in the first column.  Here are some examples of POD and the
86       event that would be produced.
87
88       A simple header:
89
90         =head1 NAME
91
92         { type => 'command', command => 'head1', content => "NAME\n", start_line => 4 }
93
94       Notice that the content includes the trailing newline.  That's to
95       maintain similarity with this possibly-surprising case:
96
97         =for HTML
98         We're actually still in the command event, here.
99
100         {
101           type    => 'command',
102           command => 'for',
103           content => "HTML\nWe're actually still in the command event, here.\n",
104           start_line => 8,
105         }
106
107       Pod::Eventual does not care what the command is.  It doesn't keep track
108       of what it's seen or whether you've used a command that isn't defined.
109       The only special case is "=cut", which is never more than one line.
110
111         =cut
112         We are no longer parsing POD when this line is read.
113
114         {
115           type    => 'command',
116           command => 'cut',
117           content => "\n",
118           start_line => 15,
119         }
120
121       Waiving this special case may be an option in the future.
122
123   Text Events
124       A text event is just a paragraph of text, beginning after one or more
125       empty lines and running until the next empty line (or =cut).  In Perl
126       5's standard usage of Pod, text content that begins with whitespace is
127       a "verbatim" paragraph, and text content that begins with non-
128       whitespace is an "ordinary" paragraph.
129
130       Pod::Eventual doesn't care.
131
132       Text events look like this:
133
134         {
135           type    => 'text',
136           content => "a string of text ending with a\n",
137           start_line =>  16,
138         }
139
140   Blank events
141       These events represent blank lines (or many blank lines) within a Pod
142       section.
143
144       Blank events look like this:
145
146         {
147           type    => 'blank',
148           content => "\n\n\n\n",
149           start_line => 21,
150         }
151
152   Non-Pod events
153       These events represent non-Pod segments of the input.
154
155       Non-Pod events look like this:
156
157         {
158           type    => 'nonpod',
159           content => "#!/usr/bin/perl\nuse strict;\n\nuse Acme::ProgressBar\n\n",
160           start_line => 1,
161         }
162

AUTHOR

164         Ricardo SIGNES <rjbs@cpan.org>
165

167       This software is copyright (c) 2009 by Ricardo SIGNES.
168
169       This is free software; you can redistribute it and/or modify it under
170       the same terms as the Perl 5 programming language system itself.
171
172
173
174perl v5.12.0                      2009-11-29                  Pod::Eventual(3)
Impressum