| 1 | package Pod::LOL; | ||||||||||||||
| 2 | |||||||||||||||
| 3 | 4 | ▶ | use 5.012; # Pod::Simple, parent. | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 4 | 4 | ▶ | use strict; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 5 | 4 | ▶ | use warnings; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 6 | 4 | ▶ | use parent qw( Pod::Simple ); | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 7 | 4 | ▶ | use Data::Dumper; | ||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||
| 8 | |||||||||||||||
| 9 | =head1 NAME | ||||||||||||||
| 10 | |||||||||||||||
| 11 | Pod::LOL - parse Pod into a list of lists (LOL) | ||||||||||||||
| 12 | |||||||||||||||
| 13 | =head1 VERSION | ||||||||||||||
| 14 | |||||||||||||||
| 15 | Version 0.14 | ||||||||||||||
| 16 | |||||||||||||||
| 17 | =cut | ||||||||||||||
| 18 | |||||||||||||||
| 19 | 4 | our $VERSION = '0.15'; | |||||||||||||
| 20 | 4 | 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<Pod::Simple> 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 | 8 | ▶ | sub new_root { | ||||||||||||
|
Subroutine
new_root: called CC=2 SCAR=7.1
Pod
documented
| |||||||||||||||
| 67 | 8 | my ( $class, $file ) = @_; | |||||||||||||
| 68 | 8 | ▶ | if ( $DEBUG ) { | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 69 | 0 | printf STDERR "class=$class, file=$file, ref=%s\n", ref $file; | |||||||||||||
| 70 | } | ||||||||||||||
| 71 | |||||||||||||||
| 72 | 8 | my $parser = $class->new; | |||||||||||||
| 73 | |||||||||||||||
| 74 | # Normally =for and =begin would otherwise be skipped. | ||||||||||||||
| 75 | 8 | $parser->accept_targets( '*' ); | |||||||||||||
| 76 | |||||||||||||||
| 77 | 8 | my $s = $parser->parse_file( $file ); | |||||||||||||
| 78 | |||||||||||||||
| 79 | 8 | $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 | 411 | ▶ | sub _handle_element_start { | ||||||||||||
|
Subroutine
_handle_element_start: called CC=5 SCAR=16.1
| |||||||||||||||
| 93 | 411 | my ( $s, $tag ) = @_; | |||||||||||||
| 94 | 411 | ▶ | print STDERR "TAG_START: $tag" if $DEBUG; | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 95 | |||||||||||||||
| 96 | 411 | ▶ | if ( $s->{_pos} ) { # We already have a position. | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 97 | 403 | ▶ | my $x = | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 98 | ( length( $tag ) == 1 ) ? [] : [$tag]; # Ignore single character tags. | ||||||||||||||
| 99 | 403 | push @{ $s->{_pos}[0] }, $x; # Append to root. | |||||||||||||
| 100 | 403 | unshift @{ $s->{_pos} }, $x; # Set as current position. | |||||||||||||
| 101 | } | ||||||||||||||
| 102 | else { | ||||||||||||||
| 103 | 8 | my $x = []; | |||||||||||||
| 104 | 8 | $s->{root} = $x; # Set root. | |||||||||||||
| 105 | 8 | $s->{_pos} = [$x]; # Set current position. | |||||||||||||
| 106 | } | ||||||||||||||
| 107 | |||||||||||||||
| 108 | 411 | ▶ | print STDERR "{_pos}: " . Dumper $s->{_pos} if $DEBUG; | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 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 | 547 | ▶ | sub _handle_text { | ||||||||||||
|
Subroutine
_handle_text: called CC=3 SCAR=11.3
| |||||||||||||||
| 122 | 547 | my ( $s, $text ) = @_; | |||||||||||||
| 123 | 547 | ▶ | print STDERR "TEXT: $text" if $DEBUG; | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 124 | |||||||||||||||
| 125 | 547 | push @{ $s->{_pos}[0] }, $text; # Add the new text. | |||||||||||||
| 126 | |||||||||||||||
| 127 | 547 | ▶ | print STDERR "{_pos}: " . Dumper $s->{_pos} if $DEBUG; | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 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 | 411 | ▶ | sub _handle_element_end { | ||||||||||||
|
Subroutine
_handle_element_end: called CC=6 SCAR=18.2
| |||||||||||||||
| 142 | 411 | my ( $s, $tag ) = @_; | |||||||||||||
| 143 | 411 | ▶ | print STDERR "TAG_END: $tag" if $DEBUG; | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 144 | 411 | shift @{ $s->{_pos} }; | |||||||||||||
| 145 | |||||||||||||||
| 146 | 411 | ▶ | if ( length $tag == 1 ) { | ||||||||||||
|
Branch: 2 branches
| |||||||||||||||
| 147 | |||||||||||||||
| 148 | # Single character tags (like L<>) should be on the same level as text. | ||||||||||||||
| 149 | 151 | $s->{_pos}[0][-1] = join "", @{ $s->{_pos}[0][-1] }; | |||||||||||||
| 150 | 0 | ▶ | print STDERR "TAG_END_TEXT: @{[ $s->{_pos}[0][-1] ]}" if $DEBUG; | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 151 | } | ||||||||||||||
| 152 | elsif ( $tag eq "Para" ) { | ||||||||||||||
| 153 | |||||||||||||||
| 154 | # Should only have 2 elements: tag, entire text | ||||||||||||||
| 155 | 78 | my ( $_tag, @text ) = @{ $s->{_pos}[0][-1] }; | |||||||||||||
| 156 | 78 | my $text = join "", @text; | |||||||||||||
| 157 | 78 | @{ $s->{_pos}[0][-1] } = ( $_tag, $text ); | |||||||||||||
| 158 | } | ||||||||||||||
| 159 | |||||||||||||||
| 160 | 411 | ▶ | print STDERR "{_pos}: " . Dumper $s->{_pos} if $DEBUG; | ||||||||||||
|
Branch: 1 branch
| |||||||||||||||
| 161 | } | ||||||||||||||
| 162 | |||||||||||||||
| 163 | |||||||||||||||
| 164 | =head1 SEE ALSO | ||||||||||||||
| 165 | |||||||||||||||
| 166 | L<App::Pod> | ||||||||||||||
| 167 | |||||||||||||||
| 168 | L<Pod::Query> | ||||||||||||||
| 169 | |||||||||||||||
| 170 | L<Pod::Simple> | ||||||||||||||
| 171 | |||||||||||||||
| 172 | |||||||||||||||
| 173 | =head1 AUTHOR | ||||||||||||||
| 174 | |||||||||||||||
| 175 | Tim Potapov, C<< <tim.potapov[AT]gmail.com> >> | ||||||||||||||
| 176 | |||||||||||||||
| 177 | =head1 BUGS | ||||||||||||||
| 178 | |||||||||||||||
| 179 | Please report any bugs or feature requests to L<https://github.com/poti1/pod-lol/issues>. | ||||||||||||||
| 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<https://metacpan.org/pod/Pod::LOL> | ||||||||||||||
| 192 | L<https://github.com/poti1/pod-lol> | ||||||||||||||
| 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 | 4 | 1; # End of Pod::LOL | |||||||||||||