Positron/Handler/ArrayRef.pm

filter: Statementstmt 84.1% 53 / 63 Branchbran 53.5% 15 / 28 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 100% 12 / 12 Podpod 100% 8 / 8 totaltotal 79.2% 88 / 111 CC 15 SCAR 10.9
CC
15
Cov
75%
list_contents
4.5
set_attribute
4.2
shallow_clone
3.3
CRAP 3.0
« Positron/Environment.pm ↑ Summary Positron.pm »
1 package Positron::Handler::ArrayRef;
2 9 our $VERSION = 'v0.1.3'; # VERSION
3  
4 =head1 NAME
5  
6 Positron::Handler::ArrayRef - a DOM interface for ArrayRefs
7  
8 =head1 VERSION
9  
10 version v0.1.3
11  
12 =head1 SYNOPSIS
13  
14 my $engine = Positron::Template->new();
15  
16 my $template = [
17 'a',
18 { href => "/"},
19 [ 'b', "Now: " ],
20 "next page",
21 ];
22 my $data = { foo => 'bar', baz => [ 1, 2, 3 ] };
23 my $result = $engine->parse($template, $data);
24  
25 =head1 DESCRIPTION
26  
27 This module allows C<Positron::Template> to work with a simple DOM representation:
28 ArrayRefs.
29 This module can also be used as a blueprint for writing more handlers; the
30 documentation of the methods is therefore extra deep.
31  
32 =head2 ArrayRef representation
33  
34 In ArrayRef representation, a DOM element is simply a reference to an array
35 with at least one element: the node tag, an optional hash (reference) with attributes,
36 and any children the node might have. Pure text is represented by simple strings.
37 Comments, processing instructions or similar have no intrinsic representation;
38 at best they can be represented as simple nodes with special tag names.
39  
40 An example:
41  
42 [
43 'a',
44 { href => "/"},
45 [ 'b', "Now: " ],
46 "next page >>",
47 ['br'],
48 ];
49  
50 This corresponds to the HTML representation of:
51  
52 <a href="/"><b>Now: </b>next page &gt;&gt;<br /></a>
53  
54 Note the plain C<<< >> >>> in the ArrayRef representation: text does B<not>
55 need to be encoded in HTML entities.
56 Note also that the attributes, if present, need to occupy the second slot
57 of the array reference. A missing attribute hash reference corresponds to
58 no attributes.
59  
60 =cut
61  
62 9 ▶use v5.10;
Subroutine BEGIN: called CC=1 SCAR=0.0
63 9 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
64 9 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
65  
66 9 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
67  
68 # Format:
69 # [ 'a', { href => "/"},
70 # [ 'b', [ "Now: " ] ],
71 # "next page",
72 # ]
73  
74 # TODO: is_regular_node? Places burden of checking types on caller
75  
76 =head1 CONSTRUCTOR
77  
78 =head2 new
79  
80 $handler = Positron::Handler::ArrayRef->new();
81  
82 The constructor has no parameters; this is a very basic class.
83 Normally, the template engine will automatically call the constructor
84 of the correct handler for whatever it is handed as template.
85  
86 =cut
87  
88 9 ▶sub new {
Subroutine new: called CC=1 SCAR=0.0
Pod documented
89 9 my ($class) = @_;
90 9 return bless {}, $class;
91 }
92  
93 =head1 METHODS
94  
95 The following methods are part of the "handler interface". The point
96 of a handler is to present a unified interface for all DOM operations
97 that C<Positron::Template> needs to do. So even though these methods
98 are quite simple, even trivial, given the ArrayRef representation,
99 they must be fully implemented.
100  
101 =head2 shallow_clone
102  
103 $new_node = $handler->shallow_clone($orig_node);
104  
105 This method returns a clone of the given node. This clone has the
106 same attributes as the original, but no children. The clone is
107 never identical to the original, even if it could be (i.e. the
108 original has no children).
109  
110 Text nodes, which are simple strings, are cloned to copies of
111 themselves.
112  
113 =cut
114  
115 326 ▶sub shallow_clone {
Subroutine shallow_clone: called CC=3 SCAR=12.0
Pod documented
116 326 my ($self, $node) = @_;
117 326 ▶ if (ref($node)) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $node) { } 326 0 326
118 # should not clone children
119 326 my ($tag, $attributes) = @$node;
120 326 ▶ if (ref($attributes) ne 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $attributes ne "HASH") 0 326 326
121 0 $attributes = {};
122 }
123 326 my $new_node = [ $tag, { %$attributes } ];
124 326 return $new_node;
125 } else {
126 0 return "$node";
127 }
128 }
129  
130 =head2 get_attribute
131  
132 $value = $handler->get_attribute($node, $attr_name);
133  
134 Gets the I<value> of a named attribute of the node. If the node does
135 not have an attribute of this name, or it is a text node (which has
136 no attributes), C<undef> is returned.
137  
138 =cut
139  
140 375 ▶sub get_attribute {
Subroutine get_attribute: called CC=3 SCAR=11.8
Pod documented
141 # gets the value, not the attribute node.
142 375 my ($self, $node, $attr) = @_;
143 375 ▶ return unless ref($node);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $node 0 375 375
144 375 my ($tag, $attributes, @children) = @$node;
145 375 ▶ if (ref($attributes) ne 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $attributes ne "HASH") 0 375 375
146 0 $attributes = {};
147 }
148 375 return $attributes->{$attr};
149 }
150  
151 =head2 set_attribute
152  
153 $handler->set_attribute($node, $attr_name => $new_value);
154  
155 Sets the named attribute to the new value. Setting an attribute to
156 C<undef> will delete the attribute. It is not an error to try to
157 set an attribute on a text node, but nothing will happen.
158  
159 Returns the new value (or C<undef> as needed), though C<Positron::Template>
160 does not use the return value.
161  
162 =cut
163  
164 123 ▶sub set_attribute {
Subroutine set_attribute: called CC=4 SCAR=14.5
Pod documented
165 123 my ($self, $node, $attr, $value) = @_;
166 123 ▶ return unless ref($node);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $node 0 123 123
167 123 my ($tag, $attributes, @children) = @$node;
168 123 ▶ if (ref($attributes) ne 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $attributes ne "HASH") 0 123 123
169 0 $attributes = {};
170 0 splice @$node, 1, 0, $attributes;
171 }
172 123 ▶ if (defined($value)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $value) { } 11 112 123
173 11 return $attributes->{$attr} = $value;
174 } else {
175 112 delete $attributes->{$attr};
176 112 return;
177 }
178 }
179  
180 =head2 list_attributes
181  
182 @attr_names = $handler->list_attributes($node);
183  
184 Lists the I<names> of all (defined) attributes on the node.
185 Text nodes have no attributes and generate an empty list.
186  
187 =cut
188  
189 1067 ▶sub list_attributes {
Subroutine list_attributes: called CC=3 SCAR=11.3
Pod documented
190 1067 my ($self, $node) = @_;
191 1067 ▶ return unless ref($node);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $node 0 1067 1067
192 1067 my ($tag, $attributes, @children) = @$node;
193 1067 ▶ return unless ref($attributes) eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
unless ref $attributes eq "HASH" 0 1067 1067
194 1067 return sort keys %$attributes;
195 }
196  
197 =head2 push_contents
198  
199 $handler->push_contents($node, $child_1, $child_2, $child_3);
200  
201 Push the passed nodes, in the given order, onto the I<end> of the
202 child list of the first argument.
203 Text nodes, again, ignore this method silently.
204  
205 =cut
206  
207 322 ▶sub push_contents {
Subroutine push_contents: called CC=2 SCAR=7.1
Pod documented
208 # set_contents? Will only be called on shallow clones, right?
209 322 my ($self, $node, @contents) = @_;
210 322 ▶ return unless ref($node);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $node 0 322 322
211 322 return push @$node, @contents;
212 }
213  
214 =head2 list_contents
215  
216 @child_nodes = $handler->list_contents($node);
217  
218 Lists the contents, i.e. the child nodes, of the given node. These
219 are not cloned nodes, but the actual children. Text nodes, of course,
220 have none.
221  
222 =cut
223  
224 341 ▶sub list_contents {
Subroutine list_contents: called CC=4 SCAR=15.0
Pod documented
225 341 my ($self, $node) = @_;
226 341 ▶ return unless ref($node);
Branch: 1 branch
BranchTrueFalseTotal
unless ref $node 0 341 341
227 341 ▶ return unless (@$node > 1); # neither attributes nor content
Branch: 1 branch
BranchTrueFalseTotal
unless @$node > 1 0 341 341
228 341 my ($tag, $attributes, @children) = @$node;
229 341 ▶ if (ref($attributes) ne 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $attributes ne "HASH") 0 341 341
230 # not an attribute hash after all?
231 0 unshift @children, $attributes;
232 }
233 341 return @children;
234 }
235  
236 =head2 parse_file
237  
238 $root_node = $handler->parse_file($filename);
239  
240 Reads and parses a file with the given filename. It is recommended to pass
241 an absolute filename, unless you can be sure about your current directory.
242 Normally, this method would not be necessary (since the template engine works
243 on already-parsed DOM trees by design), but there are template constructs that
244 include files via filename.
245  
246 If C<$filename> ends in C<.json> or C<.js>, the file is assumed to be in JSON
247 format, and will be parsed with a freshly C<require>d C<JSON> module.
248  
249 Otherwise, it is assumed to be an array reference serialized with the
250 C<Storable> module.
251  
252 =cut
253  
254 18 ▶sub parse_file {
Subroutine parse_file: called CC=2 SCAR=8.7
Pod documented
255 # Needs more info on directories!
256 # Storable: { nodes = [ ... ] }
257 18 my ($self, $filename) = @_;
258 # TODO: select deserializer based on filename (Storable / JSON / eval?)
259 18 ▶ if ($filename =~ m{ \. (json|js) $ }xms) {
Branch: 1 branch
BranchTrueFalseTotal
if ($filename =~ / \. (json|js) $ /msx) { } 0 18 18
260 0 require JSON; # should use JSON::XS if available
261 0 require File::Slurp;
262 0 my $json = File::Slurp::read_file($filename);
263 0 return JSON->new->utf8->allow_nonref->decode($json);
264 } else {
265 # Storable
266 18 require Storable;
267 18 my $dom = Storable::retrieve($filename);
268 16 return $dom;
269 }
270 }
271  
272 9 1;
273  
274 __END__
« Positron/Environment.pm ↑ Summary Positron.pm »