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

SYNOPSIS

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

DESCRIPTION

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

METHODS

39   read_handle
40         Pod::Eventual->read_handle($io_handle, \%arg);
41
42       This method iterates through the lines of a handle, producing events
43       and calling the "handle_event" method.
44
45       The only valid argument in %arg (for now) is "in_pod", which indicates
46       whether we should assume that we are parsing pod when we start parsing
47       the file.  By default, this is false.
48
49       This is useful to behave differently when reading a .pm or .pod file.
50
51       Important: the handle is expected to have an encoding layer so that it
52       will return text, not bytes, on reads.
53
54   read_file
55       This behaves just like "read_handle", but expects a filename rather
56       than a handle.  The file will be assumed to be UTF-8 encoded.
57
58   read_string
59       This behaves just like "read_handle", but expects a string containing
60       POD text 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) 2013 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.32.0                      2020-07-28                  Pod::Eventual(3)
Impressum