blib/lib/Pod/Elemental/Transformer/List.pm

filter: Statementstmt 100% 74 / 74 Branchbran 92.8% 26 / 28 Conditioncond 75.0% 9 / 12 MC/DCmcdc 50.0% 4 / 8 Subroutinesub 100% 11 / 11 Podpod 0.0% 0 / 1 totaltotal 92.5% 124 / 134 CC 21 SCAR 22.4
CC
21
Cov
96%
_expand_list_paras
16.1
__is_xformable
4.0
transform_node
3.0
CRAP 9.4
↑ Summary
1 package Pod::Elemental::Transformer::List 0.102001;
2 # ABSTRACT: transform :list regions into =over/=back to save typing
3  
4 2 ▶use Moose;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 2 ▶use Pod::Elemental::Transformer 0.101620;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 2 with 'Pod::Elemental::Transformer';
7  
8 #pod =head1 SYNOPSIS
9 #pod
10 #pod By transforming your L<Pod::Elemental::Document> like this:
11 #pod
12 #pod my $xform = Pod::Elemental::Transfomer::List->new;
13 #pod $xform->transform_node($pod_document);
14 #pod
15 #pod You can then produce traditional Pod5 lists by using C<:list> regions like
16 #pod this:
17 #pod
18 #pod =for :list
19 #pod * Doe
20 #pod a (female) deer
21 #pod * Ray
22 #pod a drop of golden sun
23 #pod
24 #pod The behavior of list regions is slighly complex, and described L<below|/LIST
25 #pod REGION PARSING>.
26 #pod
27 #pod =head1 LIST REGION PARSING
28 #pod
29 #pod There are three kinds of lists: numbered, bulleted, and definition. Every list
30 #pod must be only one kind of list. Trying to mix list styles will result in an
31 #pod exception during transformation.
32 #pod
33 #pod Lists can be written as a single paragraph beginning C<< =for :list >> or a
34 #pod region marked off with C<< =begin :list >> and C<< =end :list >>. The content
35 #pod allowed in each of those two types is defined by the L<Pod
36 #pod specification|perlpodspec> but boils down to this: "for" regions will only be
37 #pod able to contain list markers and paragraphs of text, while "begin and end"
38 #pod regions can contain arbitrary Pod paragraphs and nested list regions.
39 #pod
40 #pod All lists have a default C<indentlevel> value of 4. Adding
41 #pod C<< :over<n> >> to a C<=begin :list> definition will result in that list
42 #pod having an C<indentlevel> of C<n> instead. (This functionality is not
43 #pod available for lists defined with C<=for :list>.)
44 #pod
45 #pod Ordinary paragraphs in list regions are scanned for lines beginning with list
46 #pod item markers (see below). If they're found, the list is broken into paragraphs
47 #pod and markers. Here's a demonstrative example:
48 #pod
49 #pod =for :list
50 #pod * Doe
51 #pod a deer,
52 #pod a female deer
53 #pod * Ray
54 #pod a drop of golden sun
55 #pod or maybe it's a golden
56 #pod drop of sun
57 #pod
58 #pod The above is equivalent to
59 #pod
60 #pod =begin :list
61 #pod
62 #pod * Doe
63 #pod a deer,
64 #pod a female deer
65 #pod * Ray
66 #pod a drop of golden sun
67 #pod or maybe it's a golden
68 #pod drop of sun
69 #pod
70 #pod =end :list
71 #pod
72 #pod It will be transformed into:
73 #pod
74 #pod =over 4
75 #pod
76 #pod =item *
77 #pod
78 #pod Doe
79 #pod
80 #pod a deer,
81 #pod a female deer
82 #pod
83 #pod =item *
84 #pod
85 #pod Ray
86 #pod
87 #pod a drop of golden sun
88 #pod or maybe it's a golden
89 #pod drop of sun
90 #pod
91 #pod Which renders as:
92 #pod
93 #pod =over 4
94 #pod
95 #pod =item *
96 #pod
97 #pod Doe
98 #pod
99 #pod a deer,
100 #pod a female deer
101 #pod
102 #pod =item *
103 #pod
104 #pod Ray
105 #pod
106 #pod a drop of golden sun
107 #pod or maybe it's a golden
108 #pod drop of sun
109 #pod
110 #pod =back
111 #pod
112 #pod I<rendering ends here>
113 #pod
114 #pod In other words: the B<C<*>> indicates a new bullet. The rest of the line is
115 #pod made into one paragraph, which will become the text of the bullet point when
116 #pod rendered. (Yeah, Pod is weird.) To continue the text of the bullet point
117 #pod on more than one line, start subsequent lines with white space.
118 #pod
119 #pod =for :list
120 #pod * this bullet line
121 #pod continues on a second line
122 #pod
123 #pod Will be transformed into:
124 #pod
125 #pod =over 4
126 #pod
127 #pod =item *
128 #pod
129 #pod this bullet line continues on a second line
130 #pod
131 #pod =back
132 #pod
133 #pod Which renders as:
134 #pod
135 #pod =over 4
136 #pod
137 #pod =item *
138 #pod
139 #pod this bullet line continues on a second line
140 #pod
141 #pod =back
142 #pod
143 #pod I<rendering ends here>
144 #pod
145 #pod All subsequent lines without markers or leading white space will be kept
146 #pod together as one paragraph.
147 #pod
148 #pod Asterisks mark off bullet list items. Numbered lists are marked off with
149 #pod "C<1.>" (or any number followed by a dot). Equals signs mark off definition
150 #pod lists. The markers must be followed by a space.
151 #pod
152 #pod Here's a numbered list:
153 #pod
154 #pod =for :list
155 #pod 1. bell
156 #pod 2. book
157 #pod 3. candle
158 #pod
159 #pod The choice of number doesn't matter. The generated Pod C<=item> commands will
160 #pod start with 1 and increase by 1 each time.
161 #pod
162 #pod This is rendered as:
163 #pod
164 #pod =over 4
165 #pod
166 #pod =item 1.
167 #pod
168 #pod bell
169 #pod
170 #pod =item 2.
171 #pod
172 #pod book
173 #pod
174 #pod =item 3.
175 #pod
176 #pod candle
177 #pod
178 #pod =back
179 #pod
180 #pod I<rendering ends here>
181 #pod
182 #pod Definition lists are unusual in that the text on the line after a item marker
183 #pod will be used as the bullet, rather than the next paragraph. So this input:
184 #pod
185 #pod =begin :list
186 #pod
187 #pod = benefits
188 #pod
189 #pod There are more benefits than can be listed here.
190 #pod
191 #pod =end :list
192 #pod
193 #pod Or this input:
194 #pod
195 #pod =for :list
196 #pod = benefits
197 #pod There are more benefits than can be listed here.
198 #pod
199 #pod Will become the following output Pod:
200 #pod
201 #pod =over 4
202 #pod
203 #pod =item benefits
204 #pod
205 #pod There are more benefits than can be listed here
206 #pod
207 #pod =back
208 #pod
209 #pod Which is rendered as:
210 #pod
211 #pod =over 4
212 #pod
213 #pod =item benefits
214 #pod
215 #pod There are more benefits than can be listed here
216 #pod
217 #pod =back
218 #pod
219 #pod I<rendering ends here>
220 #pod
221 #pod If you want to nest lists, you have to make the outer list a begin/end region,
222 #pod like this:
223 #pod
224 #pod =begin :list
225 #pod
226 #pod * first outer item
227 #pod
228 #pod * second outer item
229 #pod
230 #pod =begin :list
231 #pod
232 #pod 1. first inner item
233 #pod
234 #pod 2. second inner item
235 #pod
236 #pod =end :list
237 #pod
238 #pod * third outer item
239 #pod
240 #pod =end :list
241 #pod
242 #pod The inner list, above, could have been written as a compact "for" region.
243 #pod
244 #pod =cut
245  
246 2 ▶use Pod::Elemental::Element::Pod5::Command;
Subroutine BEGIN: called CC=1 SCAR=0.0
247 2 ▶use Pod::Elemental::Types qw(FormatName);
Subroutine BEGIN: called CC=1 SCAR=0.0
248  
249 2 ▶use namespace::autoclean;
Subroutine BEGIN: called CC=1 SCAR=0.0
250  
251 #pod =attr format_name
252 #pod
253 #pod This attribute, which defaults to "list" is the region format that will be
254 #pod processed by this transformer.
255 #pod
256 #pod =cut
257  
258 2 has format_name => (
259 is => 'ro',
260 isa => FormatName,
261 default => 'list',
262 );
263  
264 15 ▶sub transform_node {
Subroutine transform_node: called CC=3 SCAR=11.0
Pod undocumented
265 15 my ($self, $node) = @_;
266  
267 15 for my $i (reverse(0 .. $#{ $node->children })) {
268 14 my $para = $node->children->[ $i ];
269 14 ▶ next unless $self->__is_xformable($para);
Branch: 1 branch
BranchTrueFalseTotal
unless $self->__is_xformable($para) 1 12 13
270 12 my @replacements = $self->_expand_list_paras( $para );
271 12 splice @{ $node->children }, $i, 1, @replacements;
272 }
273 }
274  
275 20 ▶sub __is_xformable {
Subroutine __is_xformable: called CC=4 SCAR=13.9
276 20 my ($self, $para) = @_;
277  
278 20 ▶ return unless $para->isa('Pod::Elemental::Element::Pod5::Region')
Branch: 1 branch
BranchTrueFalseTotal
unless $para->isa("Pod::Elemental::Element::Pod5::Region") and $para->format_name eq $self->format_name 1 19 20
Condition66%2/3
$para->isa("Pod::Elemental::Element::Pod5::Region") and $para->format_name eq $self->format_name
!ll&&!rl&&r
1019
MC/DC50%1/2
$para->isa("Pod::Elemental::Element::Pod5::Region") and $para->format_name eq $self->format_name
$para->isa("Pod::Elemental::Element::Pod5::Region") $para->format_name eq $self->format_name
Truth table66%2/3
A and B
A= $para->isa("Pod::Elemental::Element::Pod5::Region")B= $para->format_name eq $self->format_name
ABresult
0X0
100
111
279 and $para->format_name eq $self->format_name;
280  
281 19 ▶ confess("list regions must be pod (=begin :" . $self->format_name . ")")
Branch: 1 branch
BranchTrueFalseTotal
unless $para->is_pod 1 18 19
282 unless $para->is_pod;
283  
284 18 return 1;
285 }
286  
287 2 my %_TYPE = (
288 '=' => 'def',
289 '*' => 'bul',
290 '0' => 'num',
291 );
292  
293 18 ▶sub _expand_list_paras {
Subroutine _expand_list_paras: called CC=16 SCAR=27.8
294 18 my ($self, $parent) = @_;
295  
296 18 my @replacements;
297  
298 my $type;
299 18 my $i = 1;
300  
301 18 PARA: for my $para (@{ $parent->children }) {
302 46 ▶ unless ($para->isa('Pod::Elemental::Element::Pod5::Ordinary')) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($para->isa("Pod::Elemental::Element::Pod5::Ordinary")) 6 40 46
303 6 ▶ push @replacements, $self->__is_xformable($para)
Branch: 1 branch
BranchTrueFalseTotal
$self->__is_xformable($para) ? : 6 0 6
304 ? $self->_expand_list_paras($para)
305 : $para;
306  
307 6 next PARA;
308 }
309  
310 40 my $pip = q{}; # paragraph in progress
311 40 my @lines = split /\n/, $para->content;
312  
313 40 ▶ LINE: while (@lines) {
Branch: 1 branch
BranchTrueFalseTotal
if (@lines) 73 40 113
314 73 my $line = shift @lines;
315 73 ▶ if (my ($prefix, $rest) = $line =~ m{^(=|\*|(?:[0-9]+\.))\s+(.+)$}) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = $line =~ /^(=|\*|(?:[0-9]+\.))\s+(.+)$/) { } 47 26 73
316 47 ▶ if (length $pip) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $pip) 5 42 47
317 5 push @replacements, Pod::Elemental::Element::Pod5::Ordinary->new({
318 content => $pip,
319 });
320 }
321  
322 47 ▶ $prefix = '0' if $prefix =~ /^[0-9]/;
Branch: 1 branch
BranchTrueFalseTotal
if $prefix =~ /^[0-9]/ 18 29 47
323 47 my $line_type = $_TYPE{ $prefix };
324 47 ▶ $type ||= $line_type;
Condition66%2/3
$type ||= $line_type
l!l&&r!l&&!r
30170
MC/DC0%0/2
$type ||= $line_type
$type $line_type
Truth table66%2/3
A ||= B
A= $typeB= $line_type
ABresult
1X1
011
000
325  
326 47 ▶ confess("mismatched list types; saw $line_type marker after $type")
Branch: 1 branch
BranchTrueFalseTotal
if $line_type ne $type 0 47 47
327 if $line_type ne $type;
328  
329 47 my $method = "__paras_for_$type\_marker";
330 47 my ($marker, $leftover) = $self->$method($rest, $i++);
331 47 push @replacements, $marker;
332 47 ▶ if (defined $leftover and length $leftover) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $leftover and length $leftover) 36 11 47
Condition66%2/3
defined $leftover and length $leftover
!ll&&!rl&&r
01136
MC/DC50%1/2
defined $leftover and length $leftover
defined $leftover length $leftover
Truth table66%2/3
A and B
A= defined $leftoverB= length $leftover
ABresult
0X0
100
111
333 36 ▶ while (@lines && $lines[0] =~ /^\s+/) {
Branch: 1 branch
BranchTrueFalseTotal
if (@lines and $lines[0] =~ /^\s+/) 3 36 39
Condition100%3/3
@lines and $lines[0] =~ /^\s+/
!ll&&!rl&&r
17193
MC/DC100%2/2
@lines and $lines[0] =~ /^\s+/
@lines $lines[0] =~ /^\s+/
Truth table100%3/3
A and B
A= @linesB= $lines[0] =~ /^\s+/
ABresult
0X0
100
111
334 3 my $cont = shift @lines;
335 3 $cont =~ s/^\s+//;
336 3 $leftover .= " $cont";
337 }
338 36 push @replacements, Pod::Elemental::Element::Pod5::Ordinary->new({
339 content => $leftover,
340 });
341 }
342 47 $pip = q{};
343 } else {
344 26 $pip .= "$line\n";
345 }
346 }
347  
348 40 ▶ if (length $pip) {
Branch: 1 branch
BranchTrueFalseTotal
if (length $pip) 19 21 40
349 19 push @replacements, Pod::Elemental::Element::Pod5::Ordinary->new({
350 content => $pip,
351 });
352 }
353 }
354  
355 18 my $indentlevel = 4;
356 18 ▶ $indentlevel = $1 if $parent->content =~ /:over<(\d+)>/;
Branch: 1 branch
BranchTrueFalseTotal
if $parent->content =~ /:over<(\d+)>/ 3 15 18
357 18 unshift @replacements, Pod::Elemental::Element::Pod5::Command->new({
358 command => 'over',
359 content => $indentlevel,
360 });
361  
362 18 push @replacements, Pod::Elemental::Element::Pod5::Command->new({
363 command => 'back',
364 content => '',
365 });
366  
367 18 return @replacements;
368 }
369  
370 18 ▶sub __paras_for_num_marker {
Subroutine __paras_for_num_marker: called CC=1 SCAR=0.0
371 18 my ($self, $rest, $i) = @_;
372  
373 return (
374 18 Pod::Elemental::Element::Pod5::Command->new({
375 command => 'item',
376 content => $i,
377 }),
378 $rest,
379 );
380 }
381  
382 11 ▶sub __paras_for_def_marker {
Subroutine __paras_for_def_marker: called CC=1 SCAR=0.0
383 11 my ($self, $rest) = @_;
384  
385 return (
386 11 Pod::Elemental::Element::Pod5::Command->new({
387 command => 'item',
388 content => $rest,
389 }),
390 '',
391 );
392 }
393  
394 18 ▶sub __paras_for_bul_marker {
Subroutine __paras_for_bul_marker: called CC=1 SCAR=0.0
395 18 my ($self, $rest) = @_;
396  
397 return (
398 18 Pod::Elemental::Element::Pod5::Command->new({
399 command => 'item',
400 content => '*',
401 }),
402 $rest,
403 );
404 }
405  
406 2 1;
407  
408 __END__
↑ Summary