line |
stmt |
bran |
cond |
sub |
pod |
time |
code |
1
|
|
|
|
|
|
|
package Pod::Abstract; |
2
|
3
|
|
|
3
|
|
93652
|
use strict; |
|
3
|
|
|
|
|
8
|
|
|
3
|
|
|
|
|
117
|
|
3
|
3
|
|
|
3
|
|
17
|
use warnings; |
|
3
|
|
|
|
|
6
|
|
|
3
|
|
|
|
|
92
|
|
4
|
|
|
|
|
|
|
|
5
|
3
|
|
|
3
|
|
1840
|
use Pod::Abstract::Node; |
|
3
|
|
|
|
|
12
|
|
|
3
|
|
|
|
|
110
|
|
6
|
3
|
|
|
3
|
|
2476
|
use Pod::Abstract::Path; |
|
3
|
|
|
|
|
9
|
|
|
3
|
|
|
|
|
171
|
|
7
|
3
|
|
|
3
|
|
34
|
use Pod::Abstract::Parser; |
|
3
|
|
|
|
|
4
|
|
|
3
|
|
|
|
|
141
|
|
8
|
3
|
|
|
3
|
|
2956
|
use IO::String; |
|
3
|
|
|
|
|
14305
|
|
|
3
|
|
|
|
|
972
|
|
9
|
|
|
|
|
|
|
|
10
|
|
|
|
|
|
|
our $VERSION = '0.20'; |
11
|
|
|
|
|
|
|
|
12
|
|
|
|
|
|
|
=head1 NAME |
13
|
|
|
|
|
|
|
|
14
|
|
|
|
|
|
|
Pod::Abstract - Abstract document tree for Perl POD documents |
15
|
|
|
|
|
|
|
|
16
|
|
|
|
|
|
|
=head1 SYNOPSIS |
17
|
|
|
|
|
|
|
|
18
|
|
|
|
|
|
|
use Pod::Abstract; |
19
|
|
|
|
|
|
|
use Pod::Abstract::BuildNode qw(node); |
20
|
|
|
|
|
|
|
|
21
|
|
|
|
|
|
|
# Get all the first level headings, and put them in a verbatim block |
22
|
|
|
|
|
|
|
# at the start of the document |
23
|
|
|
|
|
|
|
my $pa = Pod::Abstract->load_filehandle(\*STDIN); |
24
|
|
|
|
|
|
|
my @headings = $pa->select('/head1@heading'); |
25
|
|
|
|
|
|
|
my @headings_text = map { $_->pod } @headings; |
26
|
|
|
|
|
|
|
my $headings_node = node->verbatim(join "\n",@headings_text); |
27
|
|
|
|
|
|
|
|
28
|
|
|
|
|
|
|
$pa->unshift( node->cut ); |
29
|
|
|
|
|
|
|
$pa->unshift( $headings_node ); |
30
|
|
|
|
|
|
|
$pa->unshift( node->pod ); |
31
|
|
|
|
|
|
|
|
32
|
|
|
|
|
|
|
print $pa->pod; |
33
|
|
|
|
|
|
|
|
34
|
|
|
|
|
|
|
=head1 DESCRIPTION |
35
|
|
|
|
|
|
|
|
36
|
|
|
|
|
|
|
POD::Abstract provides a means to load a POD (or POD compatible) |
37
|
|
|
|
|
|
|
document without direct reference to it's syntax, and perform |
38
|
|
|
|
|
|
|
manipulations on the abstract syntax tree. |
39
|
|
|
|
|
|
|
|
40
|
|
|
|
|
|
|
This can be used to support additional features for POD, to format |
41
|
|
|
|
|
|
|
output, to compile into alternative formats, etc. |
42
|
|
|
|
|
|
|
|
43
|
|
|
|
|
|
|
=head2 WHY? |
44
|
|
|
|
|
|
|
|
45
|
|
|
|
|
|
|
If you've ever asked yourself "What does Pod do for me?", this module |
46
|
|
|
|
|
|
|
is intended to answer that question. |
47
|
|
|
|
|
|
|
|
48
|
|
|
|
|
|
|
While Pod looks like a simple format, the specification calls for a |
49
|
|
|
|
|
|
|
number of special cases to be handled, and that makes any software |
50
|
|
|
|
|
|
|
that works on Pod as text more complex than it needs to be. |
51
|
|
|
|
|
|
|
|
52
|
|
|
|
|
|
|
In addition to this, Pod does not lend itself to a natural structured |
53
|
|
|
|
|
|
|
model. This makes it difficult to manipulate without damaging the |
54
|
|
|
|
|
|
|
validity of the document. |
55
|
|
|
|
|
|
|
|
56
|
|
|
|
|
|
|
Pod::Abstract solves these problems by loading the document into a |
57
|
|
|
|
|
|
|
structured tree, and providing consistent traversal, searching, |
58
|
|
|
|
|
|
|
manpulation and re-serialisation. Pod related utilities are easy to |
59
|
|
|
|
|
|
|
write using Pod::Abstract. |
60
|
|
|
|
|
|
|
|
61
|
|
|
|
|
|
|
The design goal of Pod::Abstract is to do the hard work for the |
62
|
|
|
|
|
|
|
programmer - the library should work for you, and as such it should be |
63
|
|
|
|
|
|
|
significantly easier than string mashing what you want out of a Pod |
64
|
|
|
|
|
|
|
document. |
65
|
|
|
|
|
|
|
|
66
|
|
|
|
|
|
|
=head2 PROCESSING MODEL |
67
|
|
|
|
|
|
|
|
68
|
|
|
|
|
|
|
The intent with POD::Abstract is to provide a means to decorate a |
69
|
|
|
|
|
|
|
parse tree, rather than manipulate text, to allow other software to |
70
|
|
|
|
|
|
|
add features and functionality to POD based documenation systems. |
71
|
|
|
|
|
|
|
|
72
|
|
|
|
|
|
|
If you wish to write modules that interact nicely with other |
73
|
|
|
|
|
|
|
POD::Abstract modules, then you should provide a POD::Abstract -E |
74
|
|
|
|
|
|
|
POD::Abstract translation. Leave any document element that your |
75
|
|
|
|
|
|
|
program is not interested in directly untouched in the parse tree, and |
76
|
|
|
|
|
|
|
if you have data that could be useful to other packages, decorate the |
77
|
|
|
|
|
|
|
parse tree with that data even if you don't see any direct way to use |
78
|
|
|
|
|
|
|
it in the output. |
79
|
|
|
|
|
|
|
|
80
|
|
|
|
|
|
|
In this way, when you want one more feature for POD, rather than write |
81
|
|
|
|
|
|
|
or fork a whole translator, a single inline "decorator" can be added. |
82
|
|
|
|
|
|
|
|
83
|
|
|
|
|
|
|
The C utility provides a good starting point, which also allows |
84
|
|
|
|
|
|
|
you to hook in to an existing filter/transform library. Simply add a |
85
|
|
|
|
|
|
|
C class to the namespace and it should start |
86
|
|
|
|
|
|
|
working as a C command. |
87
|
|
|
|
|
|
|
|
88
|
|
|
|
|
|
|
=head2 EXAMPLE |
89
|
|
|
|
|
|
|
|
90
|
|
|
|
|
|
|
Suppose you are frustrated by the verbose list syntax used by regular |
91
|
|
|
|
|
|
|
POD. You might reasonably want to define a simplified list format for |
92
|
|
|
|
|
|
|
your own use, except POD formatters won't support it. |
93
|
|
|
|
|
|
|
|
94
|
|
|
|
|
|
|
With Pod::Abstract you can write an inline filter to convert: |
95
|
|
|
|
|
|
|
|
96
|
|
|
|
|
|
|
* item 1 |
97
|
|
|
|
|
|
|
* item 2 |
98
|
|
|
|
|
|
|
* item 3 |
99
|
|
|
|
|
|
|
|
100
|
|
|
|
|
|
|
into: |
101
|
|
|
|
|
|
|
|
102
|
|
|
|
|
|
|
=over |
103
|
|
|
|
|
|
|
|
104
|
|
|
|
|
|
|
=item * |
105
|
|
|
|
|
|
|
|
106
|
|
|
|
|
|
|
item 1 |
107
|
|
|
|
|
|
|
|
108
|
|
|
|
|
|
|
=item * |
109
|
|
|
|
|
|
|
|
110
|
|
|
|
|
|
|
item 2 |
111
|
|
|
|
|
|
|
|
112
|
|
|
|
|
|
|
=item * |
113
|
|
|
|
|
|
|
|
114
|
|
|
|
|
|
|
item 3 |
115
|
|
|
|
|
|
|
|
116
|
|
|
|
|
|
|
=back |
117
|
|
|
|
|
|
|
|
118
|
|
|
|
|
|
|
This transformation can be simply performed on the document tree. If |
119
|
|
|
|
|
|
|
your formatter does not use Pod::Abstract, you can simply pipe out POD |
120
|
|
|
|
|
|
|
and use a regular formatter. If your formatter supports Pod::Abstract |
121
|
|
|
|
|
|
|
though, then you can feed in the syntax tree directly without having |
122
|
|
|
|
|
|
|
to re-serialise and parse the document. |
123
|
|
|
|
|
|
|
|
124
|
|
|
|
|
|
|
In addition to this, because the source document is still valid Pod, |
125
|
|
|
|
|
|
|
you aren't breaking compatibility with regular perldoc just by making |
126
|
|
|
|
|
|
|
Pod::Abstract transformations. |
127
|
|
|
|
|
|
|
|
128
|
|
|
|
|
|
|
=head2 POD SUPPORT |
129
|
|
|
|
|
|
|
|
130
|
|
|
|
|
|
|
Pod::Abstract aims to support all POD rules defined in perlpodspec |
131
|
|
|
|
|
|
|
(even the ones I don't like), except for those directly related to |
132
|
|
|
|
|
|
|
formatting output, or which cannot be implemented generically. |
133
|
|
|
|
|
|
|
|
134
|
|
|
|
|
|
|
=head1 COMPONENTS |
135
|
|
|
|
|
|
|
|
136
|
|
|
|
|
|
|
Pod::Abstract is comprised of: |
137
|
|
|
|
|
|
|
|
138
|
|
|
|
|
|
|
=over |
139
|
|
|
|
|
|
|
|
140
|
|
|
|
|
|
|
=item * |
141
|
|
|
|
|
|
|
|
142
|
|
|
|
|
|
|
The parser, which loads a document tree for you. |
143
|
|
|
|
|
|
|
|
144
|
|
|
|
|
|
|
You should access this through C, not directly |
145
|
|
|
|
|
|
|
|
146
|
|
|
|
|
|
|
=item * |
147
|
|
|
|
|
|
|
|
148
|
|
|
|
|
|
|
The document tree, which is the root node you are given by the |
149
|
|
|
|
|
|
|
parser. Calling B on the root node should always give you back |
150
|
|
|
|
|
|
|
your original document. |
151
|
|
|
|
|
|
|
|
152
|
|
|
|
|
|
|
See L |
153
|
|
|
|
|
|
|
|
154
|
|
|
|
|
|
|
=item * |
155
|
|
|
|
|
|
|
|
156
|
|
|
|
|
|
|
L, the node selection expression language. This |
157
|
|
|
|
|
|
|
is generally called by doing |
158
|
|
|
|
|
|
|
C<< $node->select(PATH_EXP) >>. Pod::Abstract::Path is the most complex |
159
|
|
|
|
|
|
|
and powerful component of this module, and if you're not using it you |
160
|
|
|
|
|
|
|
should be. ;) |
161
|
|
|
|
|
|
|
|
162
|
|
|
|
|
|
|
This allows you to ask questions like: |
163
|
|
|
|
|
|
|
|
164
|
|
|
|
|
|
|
"In the first head1 that starts with "A", find me the head2 matching |
165
|
|
|
|
|
|
|
'foo' with bold text somewhere in the preceding paragraph or heading" |
166
|
|
|
|
|
|
|
|
167
|
|
|
|
|
|
|
/head1[@heading=~{^A}](0)/head2[@heading=~{foo}i]<
|
168
|
|
|
|
|
|
|
|
169
|
|
|
|
|
|
|
You probably don't need anything that complex, but it's there if you |
170
|
|
|
|
|
|
|
do. |
171
|
|
|
|
|
|
|
|
172
|
|
|
|
|
|
|
=item * |
173
|
|
|
|
|
|
|
|
174
|
|
|
|
|
|
|
The node builder, L |
175
|
|
|
|
|
|
|
|
176
|
|
|
|
|
|
|
=back |
177
|
|
|
|
|
|
|
|
178
|
|
|
|
|
|
|
=head1 METHODS |
179
|
|
|
|
|
|
|
|
180
|
|
|
|
|
|
|
=cut |
181
|
|
|
|
|
|
|
|
182
|
|
|
|
|
|
|
|
183
|
|
|
|
|
|
|
=head2 load_file |
184
|
|
|
|
|
|
|
|
185
|
|
|
|
|
|
|
my $pa = Pod::Abstract->load_file( FILENAME ); |
186
|
|
|
|
|
|
|
|
187
|
|
|
|
|
|
|
Read the POD document in the named file. Returns the root node of the |
188
|
|
|
|
|
|
|
document. |
189
|
|
|
|
|
|
|
|
190
|
|
|
|
|
|
|
=cut |
191
|
|
|
|
|
|
|
|
192
|
|
|
|
|
|
|
sub load_file { |
193
|
0
|
|
|
0
|
1
|
0
|
my $class = shift; |
194
|
0
|
|
|
|
|
0
|
my $filename = shift; |
195
|
|
|
|
|
|
|
|
196
|
0
|
|
|
|
|
0
|
my $p = Pod::Abstract::Parser->new; |
197
|
0
|
|
|
|
|
0
|
$p->parse_from_file($filename); |
198
|
0
|
|
|
|
|
0
|
$p->root->coalesce_body(":verbatim"); |
199
|
0
|
|
|
|
|
0
|
$p->root->coalesce_body(":text"); |
200
|
0
|
|
|
|
|
0
|
return $p->root; |
201
|
|
|
|
|
|
|
} |
202
|
|
|
|
|
|
|
|
203
|
|
|
|
|
|
|
=head2 load_filehandle |
204
|
|
|
|
|
|
|
|
205
|
|
|
|
|
|
|
my $pa = Pod::Abstract->load_file( FH ); |
206
|
|
|
|
|
|
|
|
207
|
|
|
|
|
|
|
Load a POD document from the provided filehandle reference. Returns |
208
|
|
|
|
|
|
|
the root node of the document. |
209
|
|
|
|
|
|
|
|
210
|
|
|
|
|
|
|
=cut |
211
|
|
|
|
|
|
|
|
212
|
|
|
|
|
|
|
sub load_filehandle { |
213
|
5
|
|
|
5
|
1
|
10
|
my $class = shift; |
214
|
5
|
|
|
|
|
8
|
my $fh = shift; |
215
|
|
|
|
|
|
|
|
216
|
5
|
|
|
|
|
37
|
my $p = Pod::Abstract::Parser->new; |
217
|
5
|
|
|
|
|
283
|
$p->parse_from_filehandle($fh); |
218
|
5
|
|
|
|
|
19
|
$p->root->coalesce_body(":verbatim"); |
219
|
5
|
|
|
|
|
17
|
$p->root->coalesce_body(":text"); |
220
|
5
|
|
|
|
|
19
|
return $p->root; |
221
|
|
|
|
|
|
|
} |
222
|
|
|
|
|
|
|
|
223
|
|
|
|
|
|
|
=head2 load_string |
224
|
|
|
|
|
|
|
|
225
|
|
|
|
|
|
|
my $pa = Pod::Abstract->load_string( STRING ); |
226
|
|
|
|
|
|
|
|
227
|
|
|
|
|
|
|
Loads a POD document from a scalar string value. Returns the root node |
228
|
|
|
|
|
|
|
of the document. |
229
|
|
|
|
|
|
|
|
230
|
|
|
|
|
|
|
=cut |
231
|
|
|
|
|
|
|
|
232
|
|
|
|
|
|
|
sub load_string { |
233
|
5
|
|
|
5
|
1
|
1949
|
my $class = shift; |
234
|
5
|
|
|
|
|
10
|
my $str = shift; |
235
|
|
|
|
|
|
|
|
236
|
5
|
|
|
|
|
37
|
my $fh = IO::String->new($str); |
237
|
5
|
|
|
|
|
264
|
return $class->load_filehandle($fh); |
238
|
|
|
|
|
|
|
} |
239
|
|
|
|
|
|
|
|
240
|
|
|
|
|
|
|
=head1 AUTHOR |
241
|
|
|
|
|
|
|
|
242
|
|
|
|
|
|
|
Ben Lilburne |
243
|
|
|
|
|
|
|
|
244
|
|
|
|
|
|
|
=head1 COPYRIGHT AND LICENSE |
245
|
|
|
|
|
|
|
|
246
|
|
|
|
|
|
|
Copyright (C) 2009 Ben Lilburne |
247
|
|
|
|
|
|
|
|
248
|
|
|
|
|
|
|
This program is free software; you can redistribute it and/or modify |
249
|
|
|
|
|
|
|
it under the same terms as Perl itself. |
250
|
|
|
|
|
|
|
|
251
|
|
|
|
|
|
|
=cut |
252
|
|
|
|
|
|
|
|
253
|
|
|
|
|
|
|
1; |