File Coverage

blib/lib/Pod/LOL.pm
Criterion Covered Total %
statement 51 53 96.2
branch 16 24 66.6
condition n/a
subroutine 9 9 100.0
pod 1 1 100.0
total 77 87 88.5


line stmt bran cond sub pod time code
1             package Pod::LOL;
2              
3 4     4   293648 use 5.012; # Pod::Simple, parent.
  4         40  
4 4     4   17 use strict;
  4         5  
  4         65  
5 4     4   15 use warnings;
  4         6  
  4         110  
6 4     4   422 use parent qw( Pod::Simple );
  4         260  
  4         20  
7 4     4   107289 use Data::Dumper;
  4         24037  
  4         2265  
8              
9             =head1 NAME
10              
11             Pod::LOL - parse Pod into a list of lists (LOL)
12              
13             =head1 VERSION
14              
15             Version 0.11
16              
17             =cut
18              
19             our $VERSION = '0.11';
20             our $DEBUG = 0;
21              
22              
23             =head1 SYNOPSIS
24              
25             % cat my.pod
26              
27             =head1 NAME
28              
29             Pod::LOL - parse Pod into a list of lists (LOL)
30              
31              
32             % perl -MPod::LOL -MData::Dumper -e 'print Dumper( Pod::LOL->new_root("my.pod") )'
33              
34             Returns:
35              
36             [
37             [
38             "head1",
39             "NAME"
40             ],
41             [
42             "Para",
43             "Pod::LOL - parse Pod into a list of lists (LOL)"
44             ],
45             ]
46              
47              
48             =head1 DESCRIPTION
49              
50             This class may be of interest to anyone writing a pod parser.
51              
52             This module takes pod (as a file) and returns a list of lists (LOL) structure.
53              
54             This is a subclass of L and inherits all of its methods.
55              
56             =head1 SUBROUTINES/METHODS
57              
58             =head2 new_root
59              
60             Convenience method to do (mostly) this:
61              
62             Pod::LOL->new->parse_file( $file )->{root};
63              
64             =cut
65              
66             sub new_root {
67 8     8 1 9195 my ( $class, $file ) = @_;
68 8 50       31 if ( $DEBUG ) {
69 0         0 printf STDERR "class=$class, file=$file, ref=%s\n", ref $file;
70             }
71              
72 8         47 my $parser = $class->new;
73              
74             # Normally =for and =begin would otherwise be skipped.
75 8         235 $parser->accept_targets( '*' );
76              
77 8         159 my $s = $parser->parse_file( $file );
78              
79 8         787 $s->{root};
80             }
81              
82             =head2 _handle_element_start
83              
84             Overrides Pod::Simple.
85             Executed when a new pod element starts such as:
86              
87             "head1"
88             "Para"
89              
90             =cut
91              
92             sub _handle_element_start {
93 411     411   108208 my ( $s, $tag ) = @_;
94 411 50       646 print STDERR "TAG_START: $tag" if $DEBUG;
95              
96 411 100       601 if ( $s->{_pos} ) { # We already have a position.
97 403 100       753 my $x =
98             ( length( $tag ) == 1 ) ? [] : [$tag]; # Ignore single character tags.
99 403         505 push @{ $s->{_pos}[0] }, $x; # Append to root.
  403         688  
100 403         399 unshift @{ $s->{_pos} }, $x; # Set as current position.
  403         574  
101             }
102             else {
103 8         12 my $x = [];
104 8         18 $s->{root} = $x; # Set root.
105 8         18 $s->{_pos} = [$x]; # Set current position.
106             }
107              
108 411 50       717 print STDERR "{_pos}: " . Dumper $s->{_pos} if $DEBUG;
109             }
110              
111             =head2 _handle_text
112              
113             Overrides Pod::Simple.
114             Executed for each text element such as:
115              
116             "NAME"
117             "Pod::LOL - parse Pod into a list of lists (LOL)"
118              
119             =cut
120              
121             sub _handle_text {
122 547     547   3814 my ( $s, $text ) = @_;
123 547 50       778 print STDERR "TEXT: $text" if $DEBUG;
124              
125 547         588 push @{ $s->{_pos}[0] }, $text; # Add the new text.
  547         851  
126              
127 547 50       1000 print STDERR "{_pos}: " . Dumper $s->{_pos} if $DEBUG;
128             }
129              
130             =head2 _handle_element_end
131              
132             Overrides Pod::Simple.
133             Executed when a pod element ends.
134             Such as when these tags end:
135              
136             "head1"
137             "Para"
138              
139             =cut
140              
141             sub _handle_element_end {
142 411     411   1587 my ( $s, $tag ) = @_;
143 411 50       611 print STDERR "TAG_END: $tag" if $DEBUG;
144 411         364 shift @{ $s->{_pos} };
  411         542  
145              
146 411 100       708 if ( length $tag == 1 ) {
    100          
147              
148             # Single character tags (like L<>) should be on the same level as text.
149 151         208 $s->{_pos}[0][-1] = join "", @{ $s->{_pos}[0][-1] };
  151         335  
150 151 50       253 print STDERR "TAG_END_TEXT: @{[ $s->{_pos}[0][-1] ]}" if $DEBUG;
  0         0  
151             }
152             elsif ( $tag eq "Para" ) {
153              
154             # Should only have 2 elements: tag, entire text
155 78         81 my ( $_tag, @text ) = @{ $s->{_pos}[0][-1] };
  78         217  
156 78         208 my $text = join "", @text;
157 78         97 @{ $s->{_pos}[0][-1] } = ( $_tag, $text );
  78         226  
158             }
159              
160 411 50       715 print STDERR "{_pos}: " . Dumper $s->{_pos} if $DEBUG;
161             }
162              
163              
164             =head1 SEE ALSO
165              
166             L
167              
168             L
169              
170             L
171              
172              
173             =head1 AUTHOR
174              
175             Tim Potapov, C<< >>
176              
177             =head1 BUGS
178              
179             Please report any bugs or feature requests to L.
180              
181              
182             =head1 SUPPORT
183              
184             You can find documentation for this module with the perldoc command.
185              
186             perldoc Pod::LOL
187              
188              
189             You can also look for information at:
190              
191             L
192             L
193              
194              
195             =head1 ACKNOWLEDGEMENTS
196              
197             TBD
198              
199             =head1 LICENSE AND COPYRIGHT
200              
201             This software is Copyright (c) 2022 by Tim Potapov.
202              
203             This is free software, licensed under:
204              
205             The Artistic License 2.0 (GPL Compatible)
206              
207              
208             =cut
209              
210             1; # End of Pod::LOL