1Pod::Eventual(3) User Contributed Perl Documentation Pod::Eventual(3)
2
6 Pod::Eventual - read a POD document as a series of trivial events
7
9 version 0.094003
10
12 package Your::Pod::Parser;
13 use base 'Pod::Eventual';
14 sub handle_event {
16 my ($self, $event) = @_;
17 print Dumper($event);
19 }
20
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 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 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
39 This library should run on perls released even a long time ago. It
40 should work on any version of perl released in the last five years.
41 Although it may work on older versions of perl, no guarantee is made
43 that the minimum required version will not be increased. The version
44 may be increased for any reason, and there is no promise that patches
45 will be accepted to lower the minimum required perl.
46
48 read_handle
49 Pod::Eventual->read_handle($io_handle, \%arg);
50 This method iterates through the lines of a handle, producing events
52 and calling the "handle_event" method.
53 The only valid argument in %arg (for now) is "in_pod", which indicates
55 whether we should assume that we are parsing pod when we start parsing
56 the file. By default, this is false.
57 This is useful to behave differently when reading a .pm or .pod file.
59 Important: the handle is expected to have an encoding layer so that it
61 will return text, not bytes, on reads.
62 read_file
64 This behaves just like "read_handle", but expects a filename rather
65 than a handle. The file will be assumed to be UTF-8 encoded.
66 read_string
68 This behaves just like "read_handle", but expects a string containing
69 POD text rather than a handle.
70 handle_event
72 This method is called each time Pod::Eventual finishes scanning for a
73 new POD event. It must be implemented by a subclass or it will raise
74 an exception.
75 handle_nonpod
77 This method is called each time a non-POD segment is seen -- that is,
78 lines after "=cut" and before another command.
79 If unimplemented by a subclass, it does nothing by default.
81 handle_blank
83 This method is called at the end of a sequence of one or more blank
84 lines.
85 If unimplemented by a subclass, it does nothing by default.
87
89 There are four kinds of events that Pod::Eventual will produce. All
90 are represented as hash references.
91 Command Events
93 These events represent commands -- those things that start with an
94 equals sign in the first column. Here are some examples of POD and the
95 event that would be produced.
96 A simple header:
98 =head1 NAME
100 { type => 'command', command => 'head1', content => "NAME\n", start_line => 4 }
102 Notice that the content includes the trailing newline. That's to
104 maintain similarity with this possibly-surprising case:
105 =for HTML
107 We're actually still in the command event, here.
108 {
110 type => 'command',
111 command => 'for',
112 content => "HTML\nWe're actually still in the command event, here.\n",
113 start_line => 8,
114 }
115 Pod::Eventual does not care what the command is. It doesn't keep track
117 of what it's seen or whether you've used a command that isn't defined.
118 The only special case is "=cut", which is never more than one line.
119 =cut
121 We are no longer parsing POD when this line is read.
122 {
124 type => 'command',
125 command => 'cut',
126 content => "\n",
127 start_line => 15,
128 }
129 Waiving this special case may be an option in the future.
131 Text Events
133 A text event is just a paragraph of text, beginning after one or more
134 empty lines and running until the next empty line (or =cut). In Perl
135 5's standard usage of Pod, text content that begins with whitespace is
136 a "verbatim" paragraph, and text content that begins with non-
137 whitespace is an "ordinary" paragraph.
138 Pod::Eventual doesn't care.
140 Text events look like this:
142 {
144 type => 'text',
145 content => "a string of text ending with a\n",
146 start_line => 16,
147 }
148 Blank events
150 These events represent blank lines (or many blank lines) within a Pod
151 section.
152 Blank events look like this:
154 {
156 type => 'blank',
157 content => "\n\n\n\n",
158 start_line => 21,
159 }
160 Non-Pod events
162 These events represent non-Pod segments of the input.
163 Non-Pod events look like this:
165 {
167 type => 'nonpod',
168 content => "#!/usr/bin/perl\nuse strict;\n\nuse Acme::ProgressBar\n\n",
169 start_line => 1,
170 }
171
173 Ricardo SIGNES <cpan@semiotic.systems>
174
176 • Hans Dieter Pearcey <hdp@weftsoar.net>
177 • Philippe Bruhat (BooK) <book@cpan.org>
179 • Ricardo Signes <rjbs@semiotic.systems>
181
183 This software is copyright (c) 2022 by Ricardo SIGNES.
184 This is free software; you can redistribute it and/or modify it under
186 the same terms as the Perl 5 programming language system itself.
187perl v5.38.0 2023-07-21 Pod::Eventual(3)