lib/App/Dapper/Components.pm

filter: Statementstmt 100% 154 / 154 Branchbran 98.9% 95 / 96 Conditioncond 100% 35 / 35 MC/DCmcdc 100% 22 / 22 Subroutinesub 100% 16 / 16 Podpod 63.6% 7 / 11 totaltotal 98.5% 329 / 334 CC 63 SCAR 28.1
CC
63
Cov
100%
built_in
28.0
expand
20.0
video_id
7.0
CRAP 16.6
« lib/App/Dapper/Schema.pm ↑ Summary lib/App/Dapper/Publish.pm »
1 package App::Dapper::Components;
2  
3 =head1 NAME
4  
5 App::Dapper::Components - Callouts, videos, galleries and more in Markdown.
6  
7 =head1 DESCRIPTION
8  
9 Components add things Markdown can't express, without template code. A
10 component starts with three colons and its name. Most wrap Markdown and end
11 with three colons on a line of their own:
12  
13 ::: warning "Before you start"
14 Back up your site first. **Really.**
15 :::
16  
17 ::: details "Show the full list"
18 - one
19 - two
20 :::
21  
22 ::: gallery
23 ![The shop](shop.jpg)
24 ![The team](team.jpg)
25 :::
26  
27 Others are a single line:
28  
29 ::: youtube https://www.youtube.com/watch?v=dQw4w9WgXcQ "Our story"
30 ::: vimeo 76979871 "A short film"
31 ::: button /contact/ "Get in touch"
32 ::: figure shop.jpg "The shop at night" "Open until 9pm on Fridays"
33 ::: map "1 Main Street, Springfield"
34  
35 The built-in components are:
36  
37 =over 4
38  
39 =item B<note>, B<tip>, B<warning>, B<important>, B<callout>
40  
41 A box that stands out from the text, with an optional title. C<::: callout
42 tip> is the same as C<::: tip>. HTML: C<< <aside class="callout
43 callout-tip"> >>.
44  
45 =item B<details>
46  
47 A section that opens when clicked, with the summary given.
48  
49 =item B<gallery>
50  
51 The images inside, in a C<< <div class="gallery"> >>, for a grid.
52  
53 =item B<youtube>, B<vimeo>
54  
55 An embedded video, from its address or ID, with a title for screen readers.
56 YouTube videos use youtube-nocookie.com.
57  
58 =item B<button>
59  
60 A link styled as a button: C<< <a class="button"> >>.
61  
62 =item B<figure>
63  
64 An image with alt text and an optional caption.
65  
66 =item B<map>
67  
68 A map of an address, from Google Maps.
69  
70 =back
71  
72 Words after the name are its arguments; put quotes around ones with spaces.
73 To nest a component inside another, give the outer one more colons:
74  
75 :::: note
76 ::: details "More"
77 Hidden text
78 :::
79 ::::
80  
81 =head2 Components of your own
82  
83 A theme or site can add components, or change how the built-in ones look, with
84 templates in C<_layout/components>. C<_layout/components/pricing.html> is
85 used for C<::: pricing>, with these variables:
86  
87 args The arguments: args.0 is the first, args.size how many,
88 and args.list all of them, for FOR loops
89 content The HTML of the Markdown inside it (empty for a single line)
90 page The page
91 site The site
92  
93 Arguments written as C<name=value> are also available by name, as
94 C<args.name>. A component is a single line unless a matching line of colons
95 closes it.
96  
97 =cut
98  
99 191 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
100 191 ▶use 5.010;
Subroutine BEGIN: called CC=1 SCAR=0.0
101 191 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
102 191 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
103  
104 191 ▶use Text::ParseWords ();
Subroutine BEGIN: called CC=1 SCAR=0.0
105  
106 191 my %CALLOUTS = map { $_ => 1 } qw/ note tip warning important caution info /;
107 191 my %SINGLE_LINE = map { $_ => 1 } qw/ youtube vimeo button figure map /;
108 191 my %WRAPPING = map { $_ => 1 } (keys %CALLOUTS, qw/ callout details gallery /);
109  
110 =head2 names
111  
112 Returns the names of the built-in components.
113  
114 =cut
115  
116 1 ▶sub names {
Subroutine names: called CC=1 SCAR=0.0
Pod documented
117 1 return sort(keys %SINGLE_LINE, keys %WRAPPING);
118 }
119  
120 =head2 expand
121  
122 Takes Markdown, a function that turns Markdown into HTML, and options:
123 C<layout> (the layout directory, for components of your own), C<vars> (the
124 C<page> and C<site> for their templates) and C<unknown> (an array reference to
125 collect the names of components that don't exist). Returns the Markdown with
126 each component replaced by a placeholder line, and the HTML for each
127 placeholder.
128  
129 =cut
130  
131 185 ▶sub expand {
Subroutine expand: called CC=20 SCAR=30.0
Pod documented
132 185 my ($text, $to_html, $options) = @_;
133  
134 185 my @lines = split /\n/, $text, -1;
135 185 my (@out, @html);
136  
137 185 my $i = 0;
138 185 ▶ while ($i < @lines) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i < @lines) 415 184 599
139 415 my $line = $lines[$i];
140 415 my ($colons, $name, $rest) = $line =~ /^[ ]{0,3}(:{3,})[ \t]*([A-Za-z][\w-]*)[ \t]*(.*?)[ \t]*$/;
141 415 ▶ if (not defined $name) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $name) 221 194 415
142 221 push @out, $line;
143 221 $i++;
144 221 next;
145 }
146 194 $name = lc $name;
147  
148 194 my $template = template($options, $name);
149 194 ▶ my $known = defined $template || $SINGLE_LINE{$name} || $WRAPPING{$name};
Condition100%6/6
defined $template || $SINGLE_LINE{$name} || $WRAPPING{$name}
l!l&&r!l&&!r
939110
defined $template or $SINGLE_LINE{$name}
l!l&&r!l&&!r
3261101
MC/DC100%3/3
defined $template || $SINGLE_LINE{$name} || $WRAPPING{$name}
defined $template $SINGLE_LINE{$name} $WRAPPING{$name}
Truth table100%4/4
A or B || C
A= defined $templateB= $SINGLE_LINE{$name}C= $WRAPPING{$name}
ABCresult
1XX1
01X1
0011
0000
150 194 ▶ if (not $known) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($known) 10 184 194
151 10 ▶ push @{$options->{unknown}}, $name if $options->{unknown};
Branch: 1 branch
BranchTrueFalseTotal
if $options->{"unknown"} 7 3 10
152 10 push @out, $line;
153 10 $i++;
154 10 next;
155 }
156  
157 # Find the line that closes it: the same number of colons, alone
158 184 my $end;
159 184 ▶ if (!$SINGLE_LINE{$name} or defined $template) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $SINGLE_LINE{$name} or defined $template) 123 61 184
Condition100%3/3
not $SINGLE_LINE{$name} or defined $template
l!l&&r!l&&!r
121261
MC/DC100%2/2
not $SINGLE_LINE{$name} or defined $template
not $SINGLE_LINE{$name} defined $template
Truth table100%3/3
not(A) or B
A= not $SINGLE_LINE{$name}B= defined $template
ABresult
1X1
011
000
160 123 for my $j ($i + 1 .. $#lines) {
161 265 ▶ if ($lines[$j] =~ /^[ ]{0,3}\Q$colons\E[ \t]*$/) { $end = $j; last }
Branch: 1 branch
BranchTrueFalseTotal
if ($lines[$j] =~ /^[ ]{0,3}\Q$colons\E[ \t]*$/) 91 174 265
162 # Another component opening first means this one is a single line
163 174 ▶ last if $lines[$j] =~ /^[ ]{0,3}\Q$colons\E[ \t]*[A-Za-z]/;
Branch: 1 branch
BranchTrueFalseTotal
if $lines[$j] =~ /^[ ]{0,3}\Q$colons\E[ \t]*[A-Za-z]/ 6 168 174
164 }
165 }
166  
167 184 my $body = '';
168 184 ▶ if (defined $end and not $SINGLE_LINE{$name}) {
Branch: 2 branches
BranchTrueFalseTotal
if (defined $end and not $SINGLE_LINE{$name}) { } 90 94 184
elsif ($WRAPPING{$name} and not defined $template) { } 9 85 94
Condition100%3/3
defined $end and not $SINGLE_LINE{$name}
!ll&&!rl&&r
93190
MC/DC100%2/2
defined $end and not $SINGLE_LINE{$name}
defined $end not $SINGLE_LINE{$name}
Truth table100%3/3
A and not(B)
A= defined $endB= not $SINGLE_LINE{$name}
ABresult
0X0
100
111
169 90 $body = join("\n", @lines[$i + 1 .. $end - 1]);
170 }
171 ▶ elsif ($WRAPPING{$name} and not defined $template) {
Condition100%3/3
$WRAPPING{$name} and not defined $template
!ll&&!rl&&r
8419
MC/DC100%2/2
$WRAPPING{$name} and not defined $template
$WRAPPING{$name} not defined $template
Truth table100%3/3
A and not(B)
A= $WRAPPING{$name}B= not defined $template
ABresult
0X0
100
111
172 # A component that wraps text but is never closed is left as text
173 9 push @out, $line;
174 9 $i++;
175 9 next;
176 }
177 else {
178 85 undef $end;
179 }
180  
181 175 my @args = parse_args($rest);
182 175 ▶ my $inner = length $body ? $to_html->($body, $options) : '';
Branch: 1 branch
BranchTrueFalseTotal
length $body ? : 84 91 175
183 175 ▶ my $result = defined $template
Branch: 1 branch
BranchTrueFalseTotal
defined $template ? : 32 143 175
184 ? render_template($template, $name, \@args, $inner, $options)
185 : built_in($name, \@args, $inner);
186  
187 174 push @html, $result;
188 174 ▶ my $placeholder = defined $options->{placeholder} ? $options->{placeholder} : 'DAPPERCOMPONENT';
Branch: 1 branch
BranchTrueFalseTotal
defined $options->{'placeholder'} ? : 172 2 174
189 174 push @out, '', "$placeholder$#html", '';
190 174 ▶ $i = defined $end ? $end + 1 : $i + 1;
Branch: 1 branch
BranchTrueFalseTotal
defined $end ? : 90 84 174
191 }
192  
193 184 return (join("\n", @out), \@html);
194 }
195  
196 =head2 parse_args
197  
198 Takes the text after a component's name and returns its arguments: words, or
199 quoted text.
200  
201 =cut
202  
203 187 ▶sub parse_args {
Subroutine parse_args: called CC=4 SCAR=13.9
Pod documented
204 187 my ($text) = @_;
205 187 ▶ return () unless defined $text and length $text;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $text and length $text 73 114 187
Condition100%3/3
defined $text and length $text
!ll&&!rl&&r
172114
MC/DC100%2/2
defined $text and length $text
defined $text length $text
Truth table100%3/3
A and B
A= defined $textB= length $text
ABresult
0X0
100
111
206 114 my @words = Text::ParseWords::shellwords($text);
207 114 ▶ return @words ? @words : split ' ', $text;
Branch: 1 branch
BranchTrueFalseTotal
@words ? : 111 3 114
208 }
209  
210 =head2 template
211  
212 Takes the options given to L</expand> and a component name, and returns the
213 path of its template in C<_layout/components>, if there is one.
214  
215 =cut
216  
217 200 ▶sub template {
Subroutine template: called CC=4 SCAR=13.9
Pod documented
218 200 my ($options, $name) = @_;
219  
220 200 ▶ return unless defined $options->{layout};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $options->{"layout"} 161 39 200
221 39 for my $ext (qw/ .html .htm .tt /) {
222 53 my $path = "$options->{layout}/components/$name$ext";
223 53 ▶ return $path if -f $path;
Branch: 1 branch
BranchTrueFalseTotal
if -f $path 35 18 53
224 }
225 4 return;
226 }
227  
228 =head2 render_template
229  
230 Renders a component of your own with its template.
231  
232 =cut
233  
234 32 ▶sub render_template {
Subroutine render_template: called CC=4 SCAR=13.9
Pod documented
235 32 my ($path, $name, $args, $content, $options) = @_;
236  
237 32 require Template::Alloy;
238 32 require App::Dapper::Utils;
239 32 require App::Dapper::Filters;
240  
241 32 ▶ my %named = map { /^([A-Za-z_]\w*)=(.*)$/s ? ($1 => $2) : () } @$args;
Branch: 1 branch
BranchTrueFalseTotal
/^([A-Za-z_]\w*)=(.*)$/s ? : 5 20 25
242 32 my $tt = Template::Alloy->new({ ANYCASE => 1, ENCODING => 'utf8', FILTERS => App::Dapper::Filters::filters() });
243 32 my $source = App::Dapper::Utils::read_file($path);
244 my %vars = (
245 32 ▶ %{ $options->{vars} || {} },
Condition100%2/2
$options->{'vars'} || {}
l!l
311
MC/DC100%1/1
$options->{'vars'} || {}
$options->{'vars'}
Truth table100%2/2
A
A= $options->{'vars'}
Aresult
11
00
246 args => args_value($args, \%named),
247 content => $content,
248 name => $name,
249 );
250  
251 32 my $out = '';
252 32 ▶ $tt->process(\$source, \%vars, \$out)
Branch: 1 branch
BranchTrueFalseTotal
$tt->process(\$source, \%vars, \$out) or die "error: could not process the component template ${path}: " . $tt->error . "\n" 31 1 32
253 or die "error: could not process the component template $path: " . $tt->error() . "\n";
254 31 return $out;
255 }
256  
257 # A list of arguments that can also be read by name in a template: args.0 is
258 # the first argument, and args.title the one written title=...
259 32 ▶sub args_value {
Subroutine args_value: called CC=1 SCAR=0.0
Pod undocumented
260 32 my ($list, $named) = @_;
261 32 my %hash = (%$named, map { ($_ => $list->[$_]) } 0 .. $#$list);
262 32 $hash{size} = scalar @$list;
263 32 $hash{list} = $list;
264 32 return \%hash;
265 }
266  
267 =head2 built_in
268  
269 Takes a built-in component's name, arguments and inner HTML, and returns its
270 HTML.
271  
272 =cut
273  
274 148 ▶sub built_in {
Subroutine built_in: called CC=28 SCAR=33.3
Pod documented
275 148 my ($name, $args, $inner) = @_;
276  
277 148 my @args = @$args;
278  
279 148 ▶ if ($name eq 'callout' or $CALLOUTS{$name}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($name eq "callout" or $CALLOUTS{$name}) 68 80 148
Condition100%3/3
$name eq "callout" or $CALLOUTS{$name}
l!l&&r!l&&!r
155380
MC/DC100%2/2
$name eq "callout" or $CALLOUTS{$name}
$name eq "callout" $CALLOUTS{$name}
Truth table100%3/3
A or B
A= $name eq "callout"B= $CALLOUTS{$name}
ABresult
1X1
011
000
280 68 ▶ my $kind = $name eq 'callout' ? (@args && $CALLOUTS{lc $args[0]} ? lc shift @args : 'note') : $name;
Branch: 2 branches
BranchTrueFalseTotal
$name eq 'callout' ? : 15 53 68
@args && $CALLOUTS{lc $args[0]} ? : 11 4 15
Condition100%3/3
@args and $CALLOUTS{lc $args[0]}
!ll&&!rl&&r
2211
MC/DC100%2/2
@args and $CALLOUTS{lc $args[0]}
@args $CALLOUTS{lc $args[0]}
Truth table100%3/3
A and B
A= @argsB= $CALLOUTS{lc $args[0]}
ABresult
0X0
100
111
281 68 ▶ my $title = @args ? escape(join(' ', @args)) : '';
Branch: 1 branch
BranchTrueFalseTotal
@args ? : 15 53 68
282 68 ▶ my $heading = length $title ? qq{<p class="callout-title">$title</p>\n} : '';
Branch: 1 branch
BranchTrueFalseTotal
length $title ? : 14 54 68
283 68 return qq{<aside class="callout callout-$kind" role="note">\n$heading$inner</aside>};
284 }
285 80 ▶ if ($name eq 'details') {
Branch: 1 branch
BranchTrueFalseTotal
if ($name eq "details") 10 70 80
286 10 ▶ my $summary = @args ? escape(join(' ', @args)) : 'Details';
Branch: 1 branch
BranchTrueFalseTotal
@args ? : 7 3 10
287 10 return qq{<details>\n<summary>$summary</summary>\n$inner</details>};
288 }
289 70 ▶ if ($name eq 'gallery') {
Branch: 1 branch
BranchTrueFalseTotal
if ($name eq "gallery") 7 63 70
290 7 (my $images = $inner) =~ s{</?p>}{}g;
291 7 return qq{<div class="gallery">\n$images</div>};
292 }
293 63 ▶ if ($name eq 'youtube' or $name eq 'vimeo') {
Branch: 1 branch
BranchTrueFalseTotal
if ($name eq "youtube" or $name eq "vimeo") 21 42 63
Condition100%3/3
$name eq "youtube" or $name eq "vimeo"
l!l&&r!l&&!r
16542
MC/DC100%2/2
$name eq "youtube" or $name eq "vimeo"
$name eq "youtube" $name eq "vimeo"
Truth table100%3/3
A or B
A= $name eq "youtube"B= $name eq "vimeo"
ABresult
1X1
011
000
294 21 my ($video, @title) = @args;
295 21 my $id = video_id($name, $video);
296 21 ▶ return error($name, 'needs a video address or ID') unless defined $id;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $id 6 15 21
297 15 ▶ my $title = escape(@title ? join(' ', @title) : ($name eq 'youtube' ? 'YouTube video' : 'Vimeo video'));
Branch: 2 branches
BranchTrueFalseTotal
@title ? : 6 9 15
$name eq 'youtube' ? : 7 2 9
298 15 ▶ my $src = $name eq 'youtube' ? "https://www.youtube-nocookie.com/embed/$id" : "https://player.vimeo.com/video/$id";
Branch: 1 branch
BranchTrueFalseTotal
$name eq 'youtube' ? : 12 3 15
299 15 return qq{<div class="video video-$name"><iframe src="$src" title="$title" loading="lazy" }
300 . qq{allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; fullscreen" }
301 . qq{referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe></div>};
302 }
303 42 ▶ if ($name eq 'button') {
Branch: 1 branch
BranchTrueFalseTotal
if ($name eq "button") 17 25 42
304 17 my ($href, @label) = @args;
305 17 ▶ return error($name, 'needs an address and a label') unless defined $href and @label;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $href and @label 2 15 17
Condition100%3/3
defined $href and @label
!ll&&!rl&&r
1115
MC/DC100%2/2
defined $href and @label
defined $href @label
Truth table100%3/3
A and B
A= defined $hrefB= @label
ABresult
0X0
100
111
306 15 ▶ return error($name, 'needs a web address') unless safe_url($href);
Branch: 1 branch
BranchTrueFalseTotal
unless safe_url($href) 7 8 15
307 8 return '<p><a class="button" href="' . escape($href) . '">' . escape(join(' ', @label)) . '</a></p>';
308 }
309 25 ▶ if ($name eq 'figure') {
Branch: 1 branch
BranchTrueFalseTotal
if ($name eq "figure") 14 11 25
310 14 my ($src, $alt, @caption) = @args;
311 14 ▶ return error($name, 'needs an image and its alt text') unless defined $src and defined $alt;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $src and defined $alt 2 12 14
Condition100%3/3
defined $src and defined $alt
!ll&&!rl&&r
1112
MC/DC100%2/2
defined $src and defined $alt
defined $src defined $alt
Truth table100%3/3
A and B
A= defined $srcB= defined $alt
ABresult
0X0
100
111
312 12 ▶ return error($name, 'needs an image address') unless safe_url($src);
Branch: 1 branch
BranchTrueFalseTotal
unless safe_url($src) 2 10 12
313 10 ▶ my $caption = @caption ? "\n<figcaption>" . escape(join(' ', @caption)) . '</figcaption>' : '';
Branch: 1 branch
BranchTrueFalseTotal
@caption ? : 5 5 10
314 10 return '<figure><img src="' . escape($src) . '" alt="' . escape($alt) . qq{">$caption</figure>};
315 }
316 11 ▶ if ($name eq 'map') {
Branch: 1 branch
BranchTrueFalseTotal
if ($name eq "map") 10 1 11
317 10 my $place = join(' ', @args);
318 10 ▶ return error($name, 'needs an address or place') unless length $place;
Branch: 1 branch
BranchTrueFalseTotal
unless length $place 2 8 10
319 8 my $query = $place;
320 8 utf8::encode($query);
321 8 $query =~ s/([^A-Za-z0-9\-._~ ])/sprintf('%%%02X', ord $1)/ge;
322 8 $query =~ s/ /+/g;
323 8 return qq{<div class="map"><iframe src="https://maps.google.com/maps?q=$query&amp;output=embed" title="Map of }
324 . escape($place) . qq{" loading="lazy" referrerpolicy="no-referrer-when-downgrade"></iframe></div>};
325 }
326  
327 1 return error($name, 'is not a component');
328 }
329  
330 =head2 video_id
331  
332 Takes C<youtube> or C<vimeo> and a video's address or ID, and returns its ID.
333  
334 =cut
335  
336 62 ▶sub video_id {
Subroutine video_id: called CC=7 SCAR=19.5
Pod documented
337 62 my ($site, $video) = @_;
338  
339 62 ▶ return unless defined $video;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $video 5 57 62
340 57 ▶ if ($site eq 'youtube') {
Branch: 1 branch
BranchTrueFalseTotal
if ($site eq "youtube") 37 20 57
341 37 ▶ return $1 if $video =~ m{(?:youtu\.be/|[?&]v=|/embed/|/shorts/|/live/)([\w-]{6,})};
Branch: 1 branch
BranchTrueFalseTotal
if $video =~ m[(?:youtu\.be/|[?&]v=|/embed/|/shorts/|/live/)([\w-]{6,})] 18 19 37
342 19 ▶ return $video if $video =~ /^[\w-]{6,}$/;
Branch: 1 branch
BranchTrueFalseTotal
if $video =~ /^[\w-]{6,}$/ 11 8 19
343 8 return;
344 }
345 20 ▶ return $1 if $video =~ m{vimeo\.com/(?:.*/)?(\d+)(?:[/?#]|$)};
Branch: 1 branch
BranchTrueFalseTotal
if $video =~ m[vimeo\.com/(?:.*/)?(\d+)(?:[/?#]|$)] 11 9 20
346 9 ▶ return $video if $video =~ /^\d+$/;
Branch: 1 branch
BranchTrueFalseTotal
if $video =~ /^\d+$/ 3 6 9
347 6 return;
348 }
349  
350 27 ▶sub safe_url {
Subroutine safe_url: called CC=1 SCAR=0.0
Pod undocumented
351 27 my ($url) = @_;
352 27 return $url !~ /^\s*(?:javascript|vbscript|data):/i;
353 }
354  
355 22 ▶sub error {
Subroutine error: called CC=1 SCAR=0.0
Pod undocumented
356 22 my ($name, $message) = @_;
357 22 return '<p class="component-error"><strong>' . escape("::: $name $message") . '</strong></p>';
358 }
359  
360 108 ▶sub escape {
Subroutine escape: called CC=2 SCAR=7.0
Pod undocumented
361 108 my ($text) = @_;
362 108 ▶ $text = '' unless defined $text;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $text 0 108 108
363 108 $text =~ s/&/&amp;/g;
364 108 $text =~ s/</&lt;/g;
365 108 $text =~ s/>/&gt;/g;
366 108 $text =~ s/"/&quot;/g;
367 108 return $text;
368 }
369  
370 191 1;
« lib/App/Dapper/Schema.pm ↑ Summary lib/App/Dapper/Publish.pm »