| 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 >><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
| |||||||||||
| 118 | # should not clone children | ||||||||||
| 119 | 326 | my ($tag, $attributes) = @$node; | |||||||||
| 120 | 326 | ▶ | if (ref($attributes) ne 'HASH') { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 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
| |||||||||||
| 144 | 375 | my ($tag, $attributes, @children) = @$node; | |||||||||
| 145 | 375 | ▶ | if (ref($attributes) ne 'HASH') { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 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
| |||||||||||
| 167 | 123 | my ($tag, $attributes, @children) = @$node; | |||||||||
| 168 | 123 | ▶ | if (ref($attributes) ne 'HASH') { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 169 | 0 | $attributes = {}; | |||||||||
| 170 | 0 | splice @$node, 1, 0, $attributes; | |||||||||
| 171 | } | ||||||||||
| 172 | 123 | ▶ | if (defined($value)) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 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
| |||||||||||
| 192 | 1067 | my ($tag, $attributes, @children) = @$node; | |||||||||
| 193 | 1067 | ▶ | return unless ref($attributes) eq 'HASH'; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 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
| |||||||||||
| 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
| |||||||||||
| 227 | 341 | ▶ | return unless (@$node > 1); # neither attributes nor content | ||||||||
|
Branch: 1 branch
| |||||||||||
| 228 | 341 | my ($tag, $attributes, @children) = @$node; | |||||||||
| 229 | 341 | ▶ | if (ref($attributes) ne 'HASH') { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 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
| |||||||||||
| 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__ | ||||||||||