blib/lib/HTML/FromArrayref.pm

filter: Statementstmt 95.2% 40 / 42 Branchbran 100% 12 / 12 Conditioncond 83.3% 5 / 6 MC/DCmcdc 75.0% 3 / 4 Subroutinesub 84.6% 11 / 13 Podpod 62.5% 5 / 8 totaltotal 89.4% 76 / 85 CC 10 SCAR 11.3
CC
10
Cov
95%
element
6.0
attributes
4.0
HTML
2.0
CRAP 3.1
↑ Summary
1 package HTML::FromArrayref;
2  
3 3 ▶use 5.006;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
6  
7 3 ▶use base qw( Exporter );
Subroutine BEGIN: called CC=1 SCAR=0.0
8 3 our @EXPORT = qw( HTML );
9 3 our @EXPORT_OK = qw( start_tag end_tag html_strict html_transitional html_frameset );
10 3 our %EXPORT_TAGS = (
11 TAGS => [qw( start_tag end_tag )],
12 DOCTYPES => [qw( html_strict html_transitional html_frameset )]
13 );
14  
15 3 ▶use HTML::Entities;
Subroutine BEGIN: called CC=1 SCAR=0.0
16  
17 =head1 NAME
18  
19 HTML::FromArrayref - Output HTML described by a Perl data structure
20  
21 =head1 VERSION
22  
23 Version 1.06
24  
25 =cut
26  
27 3 our $VERSION = '1.06';
28  
29 =head1 SYNOPSIS
30  
31 use HTML::FromArrayref;
32 print HTML [ html => [ head => [ title => 'My Web page' ] ], [ body => 'Hello' ] ];
33  
34 =head1 EXPORT
35  
36 This module exports an HTML() function that lets you easily print valid HTML without embedding it in your Perl code.
37  
38 =head1 SUBROUTINES/METHODS
39  
40 =head2 HTML(@)
41  
42 Takes a list of strings and arrayrefs describing HTML content and returns the HTML string. The strings are encoded; each arrayref represents an HTML element, as follows:
43  
44 [ $tag_name, $attributes, @content ]
45  
46 =head3 $tag_name
47  
48 evaluates to a tag name such as 'html', 'head', 'title', 'body', 'table', 'tr', 'td', 'p', &c. If $tag_name is false then the whole element is replaced by its content.
49  
50 If an arrayref's first element is another arrayref instead of an tag name, then the value of the first item of that array will be included in the HTML string but will not be encoded. This lets you include text in the HTML that has already been entity-encoded.
51  
52 =head3 $attributes
53  
54 is an optional hashref defining the element's attributes. If an attribute's value is undefined then the attribute will not appear in the generated HTML string. Attribute values will be encoded. If there isn't a hashref in the second spot in the element-definition list then the element won't have any attributes in the generated HTML.
55  
56 =head3 @content
57  
58 is another list of strings and arrayrefs, which will be used to generate the content of the element. If the content list is empty, then the element has no content and will be represented in the generated HTML string by adjacent start and end tags. The content of elements that are defined in the HTML 4.01 specification as "void" will be discarded, and only their start tag will be printed.
59  
60 =cut
61  
62 17 ▶sub HTML (@) {
Subroutine HTML: called CC=2 SCAR=6.9
Pod documented
63 join '', grep defined $_, map {
64 17 ▶ ref $_ eq 'ARRAY' ? element( @$_ ) : encode_entities( $_ )
Branch: 1 branch
BranchTrueFalseTotal
ref $_ eq 'ARRAY' ? : 12 8 20
65 } @_;
66 }
67  
68 =head2 element()
69  
70 Recursively renders HTML elements from arrayrefs
71  
72 =cut
73  
74 3 my %void; @void{ qw(
75 area base br col command embed hr img input
76 keygen link meta param source track wbr
77 ) } = (1)x16;
78  
79 12 ▶sub element {
Subroutine element: called CC=6 SCAR=17.9
Pod documented
80 12 my ( $tag_name, $attributes, @content ) = @_;
81  
82 # If an element's name is an array ref then it's
83 # really text to print without encoding
84 12 ▶ return $tag_name->[0] if ref $tag_name eq 'ARRAY';
Branch: 1 branch
BranchTrueFalseTotal
if ref $tag_name eq "ARRAY" 1 11 12
85  
86 # If the second item in the list is not a hashref,
87 # then the element has no attributes
88 11 ▶ if ( defined $attributes and ref $attributes ne 'HASH' ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $attributes and ref $attributes ne "HASH") 6 5 11
Condition100%3/3
defined $attributes and ref $attributes ne "HASH"
!ll&&!rl&&r
236
MC/DC100%2/2
defined $attributes and ref $attributes ne "HASH"
defined $attributes ref $attributes ne "HASH"
Truth table100%3/3
A and B
A= defined $attributesB= ref $attributes ne "HASH"
ABresult
0X0
100
111
89 6 unshift @content, $attributes;
90 6 undef $attributes;
91 }
92  
93 # If the first expression in the list is false, then skip
94 # the element and return its content instead
95 11 ▶ return HTML( @content ) if not $tag_name;
Branch: 1 branch
BranchTrueFalseTotal
unless $tag_name 1 10 11
96  
97 # Return the element start tag with its formatted and
98 # encoded attributes, and (optionally) content and
99 # end tag
100 join '', '<', $tag_name, attributes( %$attributes ), '>',
101 10 ▶ ! $void{ lc $tag_name } && ( HTML( @content ), "</$tag_name>" );
Condition66%2/3
!$void{lc $tag_name} && (&HTML(@content), "</$tag_name>")
!ll&&!rl&&r
208
MC/DC50%1/2
!$void{lc $tag_name} && (&HTML(@content), "</$tag_name>")
!$void{lc $tag_name} (&HTML(@content), "</$tag_name>")
Truth table66%2/3
not(A) && B
A= !$void{lc $tag_name}B= (&HTML(@content), "</$tag_name>")
ABresult
0X0
100
111
102 }
103  
104 =head2 start_tag()
105  
106 Takes a list with an element name and an optional hashref defining the element's attributes, and returns just the opening tag of the element. This and end_tag() are useful in those occasions when you really want to print out HTML piecewise procedurally, rather than building the whole page in memory.
107  
108 =cut
109  
110 3 ▶sub start_tag {
Subroutine start_tag: called CC=1 SCAR=0.0
Pod documented
111 3 my ( $tag_name, $attributes ) = @_;
112  
113 3 join '', grep $_,
114 '<', $tag_name, attributes( %$attributes ), '>';
115 }
116  
117 =head2 end_tag()
118  
119 Just takes an element name and returns the end tag for that element.
120  
121 =cut
122  
123 1 ▶sub end_tag { "</$_[0]>" }
Subroutine end_tag: called CC=1 SCAR=0.0
Pod documented
124  
125 =head2 attributes()
126  
127 Takes a hash of HTML element attributes and returns an encoded string for use in a tag
128  
129 =cut
130  
131 13 ▶sub attributes {
Subroutine attributes: called CC=4 SCAR=13.9
Pod documented
132  
133 13 ▶ return unless my %attributes = @_;
Branch: 1 branch
BranchTrueFalseTotal
unless my(%attributes) = 8 5 13
134  
135 5 my @html;
136 5 for ( keys %attributes ) {
137 5 ▶ if ( defined $attributes{$_} ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $attributes{$_}) 4 1 5
138 4 push @html, join '', $_, '="', encode_entities( $attributes{$_} ), '"';
139 }
140 }
141 5 join ' ', '', @html;
142 }
143  
144 =head2 DOCTYPEs
145  
146 These make it easy to add a valid doctype declaration to your document
147  
148 =cut
149  
150 1 ▶sub html_strict { << '' }
Subroutine html_strict: called CC=1 SCAR=0.0
Pod undocumented
151 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
152 "http://www.w3.org/TR/html4/strict.dtd">
153  
154 0 ▶sub html_transitional { << '' }
Subroutine html_transitional: not called CC=1 SCAR=6.9
Pod undocumented
155 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
156 "http://www.w3.org/TR/html4/loose.dtd">
157  
158 0 ▶sub html_frameset { << '' }
Subroutine html_frameset: not called CC=1 SCAR=6.9
Pod undocumented
159 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Frameset//EN"
160 "http://www.w3.org/TR/html4/frameset.dtd">
161  
162 =head1 EXAMPLES
163  
164 Note that I've formatted the output HTML for clarity - the html() function returns it all machine-readable and compact.
165  
166 =head2 Simple content
167  
168 Strings are just encoded and printed, so
169  
170 print HTML 'Hi there, this & that';
171  
172 would print
173  
174 Hi there, this &amp; that
175  
176 =head2 Literal content
177  
178 If an element's name is an arrayref, its first item is printed without being encoded; this lets you include text that is already encoded by double-bracketing it:
179  
180 print HTML [ p => [[ '&copy; Angel Networks&trade;' ]] ];
181  
182 would print
183  
184 <p>&copy; Angel Networks&trade;</p>
185  
186 =head2 Using map to iterate, and optional elements
187  
188 You can map any element over a list to iterate it, and by testing the value being mapped over can wrap some values in sub-elements:
189  
190 print HTML map [ p => [ $_ > 100 && 'b' => $_ ] ], 4, 450, 12, 44, 74, 102;
191  
192 would print
193  
194 <p>4</p>
195 <p><b>450</b></p>
196 <p>12</p>
197 <p>44</p>
198 <p>74</p>
199 <p><b>102</b></p>
200  
201 =head2 Optional attributes
202  
203 Similarly, by testing the value being mapped over in the attributes hash, you can set an attribute for only some values. Note that you have to explicitly return undef to skip the attribute since 0 is a valid value for an attribute.
204  
205 print HTML [ select => { name => 'State' },
206 map
207 [ option => { selected => $_ eq $c{state} || undef }, $_ ],
208 @states
209 ];
210  
211 would print
212  
213 <select name="State">
214 <option>Alabama</option>
215 <option selected="1">Alaska</option>
216 <option>Arkansas</option>
217 ...
218 </select>
219  
220 assuming $c{state} equalled 'Alaska'.
221  
222 =head2 Printing HTML tags one at a time
223  
224 Sometimes you really don't want to build the whole page before printing it; you'd rather loop through some data and print an element at a time. The start_tag and end_tag functions will help you do this:
225  
226 print start_tag( [ td => { colspan => 3 } ] );
227 print end_tag( 'td' );
228  
229 would print
230  
231 <td colspan="3">
232 </td>
233  
234 =head1 SEE ALSO
235  
236 L<The HTML 4.01 specification|http://www.w3.org/TR/html401/>
237  
238 =head1 AUTHOR
239  
240 Nic Wolff, <nic@angel.net>
241  
242 =head1 BUGS
243  
244 Please report any bugs or feature requests through the web interface at L<https://github.com/nicwolff/HTML-FromArrayref/issues>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
245  
246 =head1 SUPPORT
247  
248 You can find documentation for this module with the perldoc command.
249  
250 perldoc HTML::FromArrayref
251  
252 You can also look for information at:
253  
254 =over 4
255  
256 =item * This module on GitHub
257  
258 L<https://github.com/nicwolff/HTML-FromArrayref>
259  
260 =item * GitHub request tracker (report bugs here)
261  
262 L<https://github.com/nicwolff/HTML-FromArrayref/issues>
263  
264 =item * AnnoCPAN: Annotated CPAN documentation
265  
266 L<http://annocpan.org/dist/HTML-FromArrayref>
267  
268 =item * Search CPAN
269  
270 L<http://search.cpan.org/dist/HTML-FromArrayref/>
271  
272 =back
273  
274 =head1 LICENSE AND COPYRIGHT
275  
276 Copyright 2012 Nic Wolff.
277  
278 This program is free software; you can redistribute it and/or modify it
279 under the terms of either: the GNU General Public License as published
280 by the Free Software Foundation; or the Artistic License.
281  
282 See http://dev.perl.org/licenses/ for more information.
283  
284 =cut
285  
286 3 1; # End of HTML::FromArrayref
↑ Summary