Navigator/Node.pm

filter: Statementstmt 30.7% 35 / 114 Branchbran 0.0% 0 / 22 Conditioncond 0.0% 0 / 9 MC/DCmcdc 0.0% 0 / 5 Subroutinesub 27.2% 9 / 33 Podpod 37.5% 6 / 16 totaltotal 25.1% 50 / 199 CC 19 SCAR 21.4
CC
19
Cov
24%
_join_path
30.0
descendent
20.0
mount
12.0
CRAP 8.5
« Navigator/Node/Filesys.pm ↑ Summary Navigator/Node/Perl/Symdump.pm »
1 package Tree::Navigator::Node;
2 1 ▶use utf8;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 1 ▶use Moose;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 1 ▶use namespace::autoclean;
Subroutine BEGIN: called CC=1 SCAR=0.0
8 1 ▶use List::MoreUtils qw/part/;
Subroutine BEGIN: called CC=1 SCAR=0.0
9  
10 1 ▶use MooseX::Params::Validate;
Subroutine BEGIN: called CC=1 SCAR=0.0
11 1 ▶use Params::Validate qw/ARRAYREF HASHREF/;
Subroutine BEGIN: called CC=1 SCAR=0.0
12 1 ▶use Scalar::Util qw/weaken/;
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 #======================================================================
15 # attributes
16 #======================================================================
17  
18 1 has 'mount_point' => (
19 is => 'ro',
20 isa => 'HashRef',
21 required => 1,
22 );
23  
24 1 has 'path' => ( # cumulated path from the mount point
25 is => 'ro',
26 isa => 'Str',
27 default => '',
28 );
29  
30 1 has 'attributes' => (
31 is => 'ro',
32 isa => 'HashRef',
33 lazy => 1,
34 builder => '_attributes',
35 );
36  
37 1 has 'content' => (
38 # "is => 'ro'" but don't generate the accessor, it's coded below
39 isa => 'FileHandle',
40 predicate => 'has_content',
41 lazy => 1,
42 builder => '_content',
43 init_arg => undef,
44 );
45  
46 has 'mounted' => (
47 is => 'ro',
48 isa => 'ArrayRef',
49 0 ▶ default => sub { [] },
Subroutine __ANON__: not called CC=1 SCAR=6.9
50 1 init_arg => undef,
51 );
52 has 'mounted_at' => (
53 is => 'ro',
54 isa => 'HashRef',
55 0 ▶ default => sub { {} },
Subroutine __ANON__: not called CC=1 SCAR=6.9
56 1 init_arg => undef,
57 );
58  
59  
60  
61 #======================================================================
62 # mounting a node from a different subclass
63 #======================================================================
64  
65 # class method to check and rearrange $mount_args, before giving
66 # them to ->new()
67 0 ▶sub MOUNT {
Subroutine MOUNT: not called CC=1 SCAR=6.9
Pod documented
68 0 my ($class, $mount_args) = @_;
69 0 return;
70 }
71  
72 0 ▶sub mount {
Subroutine mount: not called CC=3 SCAR=24.8
Pod undocumented
73 0 my $self = shift;
74  
75 # validate method arguments
76 0 my ($path, $node_class, $node_args, $mount_args) = pos_validated_list(
77 \@_,
78 { regex => qr[^[^/]*$] }, # path: no '/'
79 { regex => qr[.+] }, # node class
80 { type => HASHREF, default => {} }, # node_args
81 { type => HASHREF, default => {} }, # $mount_args
82 );
83  
84 # validate mount path
85 0 my $mounted_at = $self->mounted_at;
86 0 ▶ not exists $mounted_at->{$path}
Branch: 1 branch
BranchTrueFalseTotal
exists $mounted_at->{$path} and die "mount path ${path}' already in use" 0 0 0
87 or die "mount path $path' already in use";
88  
89 # load and instantiate
90 0 my $class = Plack::Util::load_class($node_class, 'Tree::Navigator::Node');
91 0 $class->MOUNT($node_args); # validates and rearranges $node_args
92 0 my $node = $class->new(path => '', %$node_args);
93  
94 # inject some info into mount point
95 0 my $mount_point = $node->mount_point;
96 0 $mount_point->{path} = $self->_join_path($self->full_path, $path);
97 0 $mount_point->{navigator} = $self->mount_point->{navigator};
98 0 weaken $mount_point->{navigator};
99  
100 # register
101 0 ▶ push @{$self->mounted}, $path unless $mount_args->{hidden};
Branch: 1 branch
BranchTrueFalseTotal
unless $mount_args->{"hidden"} 0 0 0
102 0 $mounted_at->{$path} = $node;
103 }
104  
105  
106  
107  
108 #======================================================================
109 # instance methods to be refined in subclasses
110 #======================================================================
111 0 ▶sub _attributes {
Subroutine _attributes: not called CC=1 SCAR=6.9
112 0 my $self = shift;
113 0 return {};
114 }
115  
116 0 ▶sub _children {
Subroutine _children: not called CC=1 SCAR=6.9
117 0 my $self = shift;
118 0 return [];
119 }
120  
121 0 ▶sub child {
Subroutine child: not called CC=3 SCAR=24.8
Pod documented
122 0 my ($self, $child_name) = @_;
123 0 ▶ my $child = $self->mounted_at->{$child_name}
Branch: 1 branch
BranchTrueFalseTotal
my $child = $self->mounted_at->{$child_name} || $self->_child($child_name) or die "no such child: '${child_name}' in " . $self->full_path 0 0 0
Condition0%0/3
$self->mounted_at->{$child_name} || $self->_child($child_name)
l!l&&r!l&&!r
000
MC/DC0%0/2
$self->mounted_at->{$child_name} || $self->_child($child_name)
$self->mounted_at->{$child_name} $self->_child($child_name)
Truth table0%0/3
A || B
A= $self->mounted_at->{$child_name}B= $self->_child($child_name)
ABresult
1X1
011
000
124 || $self->_child($child_name)
125 or die "no such child: '$child_name' in " . $self->full_path;
126 0 return $child;
127 }
128  
129  
130 0 ▶sub _child {
Subroutine _child: not called CC=1 SCAR=6.9
131 0 my ($self, $child_name) = @_;
132 0 return undef;
133 }
134  
135  
136 0 ▶sub children {
Subroutine children: not called CC=1 SCAR=6.9
Pod documented
137 0 my $self = shift;
138 0 my $mounted = $self->mounted;
139 0 my $children = $self->_children;
140 0 return @$mounted, @$children;
141 }
142  
143  
144 0 ▶sub content {
Subroutine content: not called CC=2 SCAR=17.9
Pod documented
145 0 my $self = shift;
146 0 ▶ if (my $fh = $self->{content}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $fh = $self->{'content'}) { } 0 0 0
147 # if the filehandle is already present, rewind it to beginning of file
148 0 $fh->seek(0, 0);
149 0 return $fh;
150 }
151 else {
152 0 return $self->_content;
153 }
154 }
155  
156  
157  
158 0 ▶sub _content {
Subroutine _content: not called CC=1 SCAR=6.9
159 0 my $self = shift;
160 0 return undef;
161 }
162  
163 0 ▶sub content_text {
Subroutine content_text: not called CC=2 SCAR=17.9
Pod undocumented
164 0 my $self = shift;
165 0 my $fh = $self->content;
166 0 ▶ return $fh ? join("", <$fh>) : "";
Branch: 1 branch
BranchTrueFalseTotal
$fh ? : 0 0 0
167 }
168  
169  
170 #======================================================================
171 # generic methods
172 #======================================================================
173 0 ▶sub descendent {
Subroutine descendent: not called CC=4 SCAR=30.0
Pod documented
174 0 my ($self, $path) = @_;
175  
176 # $self is its own descendent if $path is empty
177 0 ▶ return $self if ($path // '') eq ''; # NOTE : '0' is a valid nonempty path!
Branch: 1 branch
BranchTrueFalseTotal
if ($path // "") eq "" 0 0 0
Condition0%0/2
$path // ""
l!l
00
MC/DC0%0/1
$path // ""
$path
Truth table0%0/2
A
A= $path
Aresult
11
00
178  
179 # otherwise, find the child from initial path segment, and then recurse
180 0 my ($child_name, $subpath) = split m{/}, $path, 2;
181 0 ▶ my $child = $self->child($child_name)
Branch: 1 branch
BranchTrueFalseTotal
my $child = $self->child($child_name) or die "no such child: $child_name" 0 0 0
182 or die "no such child: $child_name";
183 0 return $child->descendent($subpath);
184 }
185  
186 0 ▶sub is_parent { # default implementation; may be optimised in subclasses
Subroutine is_parent: not called CC=2 SCAR=17.9
Pod documented
187 0 my $self = shift;
188 0 my @children = $self->children;
189 0 ▶ return @children ? 1 : 0;
Branch: 1 branch
BranchTrueFalseTotal
@children ? : 0 0 0
190 }
191  
192 0 ▶sub _join_path {
Subroutine _join_path: not called CC=5 SCAR=34.0
193 0 my ($self, $path_ini, $path_end) = @_;
194 0 ▶ $_ //= '' for $path_ini, $path_end;
Condition0%0/2
$_ //= ""
l!l
00
MC/DC0%0/1
$_ //= ""
$_
Truth table0%0/2
A
A= $_
Aresult
11
00
195  
196 0 ▶ return $path_ini ne '' ? $path_end ne '' ? "$path_ini/$path_end"
Branch: 2 branches
BranchTrueFalseTotal
$path_ini ne '' ? : 0 0 0
$path_end ne '' ? : 0 0 0
197 : $path_ini
198 : $path_end;
199 }
200  
201 0 ▶sub full_path {
Subroutine full_path: not called CC=1 SCAR=6.9
Pod undocumented
202 0 my $self = shift;
203  
204 0 return $self->_join_path($self->mount_point->{path}, $self->path);
205 }
206  
207  
208 0 ▶sub last_path {
Subroutine last_path: not called CC=1 SCAR=6.9
Pod undocumented
209 0 my $self = shift;
210 0 my $path = $self->full_path;
211 0 $path =~ s[^.*/][];
212 0 return $path;
213 }
214  
215 0 ▶sub subnodes_and_leaves {
Subroutine subnodes_and_leaves: not called CC=3 SCAR=24.8
Pod undocumented
216 0 my $self = shift;
217 my ($subnodes, $leaves)
218 0 ▶ = part {$self->child($_)->is_parent ? 0 : 1} $self->children;
Subroutine __ANON__: not called CC=2 SCAR=17.9
Branch: 1 branch
BranchTrueFalseTotal
$self->child($_)->is_parent ? : 0 0 0
219 0 ▶ $_ //= [] for $subnodes, $leaves;
Condition0%0/2
$_ //= []
l!l
00
MC/DC0%0/1
$_ //= []
$_
Truth table0%0/2
A
A= $_
Aresult
11
00
220 0 return ($subnodes, $leaves);
221 }
222  
223  
224  
225 #======================================================================
226 # WORK IN PROGRESS
227 #======================================================================
228  
229 0 ▶sub navigator {
Subroutine navigator: not called CC=1 SCAR=6.9
Pod undocumented
230 0 my $self = shift;
231 0 return $self->mount_point->{navigator};
232 }
233  
234 0 ▶sub data {
Subroutine data: not called CC=2 SCAR=17.9
Pod undocumented
235 0 my $self = shift;
236 0 my %data = (attributes => $self->attributes,
237 content_text => $self->content_text);
238  
239 0 foreach my $child_name ($self->children) {
240 0 my $child = $self->child($child_name);
241 0 push @{$data{children}}, {name => $child_name,
242 attributes => $child->attributes};
243 }
244  
245 0 return \%data;
246 }
247  
248  
249 0 ▶sub view {
Subroutine view: not called CC=1 SCAR=6.9
Pod undocumented
250 0 my $self = shift;
251 0 return $self->navigator->view(@_);
252 }
253  
254  
255 0 ▶sub response {
Subroutine response: not called CC=1 SCAR=6.9
Pod undocumented
256 0 my ($self, $request) = @_;
257 0 my $view = $self->view($self->choose_view($request));
258 0 return $view->render($self, $request);
259 }
260  
261  
262 0 ▶sub choose_view {
Subroutine choose_view: not called CC=1 SCAR=6.9
Pod undocumented
263 0 my ($self, $request) = @_;
264 0 return;
265 }
266  
267  
268  
269  
270 1 __PACKAGE__->meta->make_immutable;
271  
272 1 1; # End of Tree::Navigator::Node
273  
274 =encoding utf8
275  
276 =head1 NAME
277  
278 Tree::Navigator::Node - a node to be displayed in a Tree::Navigator
279  
280 =cut
281  
282 =head1 SYNOPSIS
283  
284 See L<Tree::Navigator>
285  
286 =head1 SPECIFICATION
287  
288 =head2 Node structure
289  
290 A B<node> is an object that may contain
291  
292 =over
293  
294 =item attributes
295  
296 An B<attribute value> is either C<undef> or a Perl string.
297 An B<attribute name> is a non-empty Perl string.
298 An B<attribute list> is an ordered list of pairs (name, value).
299  
300  
301 =item content
302  
303 A filehandle to some opaque content stored within the node.
304  
305  
306 =item children
307  
308 A B<child> is another node stored under the current node.
309 A B<child name> is a non-empty Perl string.
310 The B<children> of a node is an ordered list of pairs (name, child).
311  
312 =back
313  
314  
315 =head1 METHODS
316  
317 =head2 Basic node access methods
318  
319 =head3 attributes
320  
321 my $attrs = $node->attributes;
322  
323 Returns a hashref of key-value pairs. Values are either C<undef> or
324 Perl strings (or anything that may stringify to a Perl string).
325  
326 =head3 children
327  
328 my @children_names = $node->children;
329  
330 Returns an ordered list of distinct, non-empty strings (the names of
331 B<published children>).
332  
333 =head3 child
334  
335 my $child = $node->child($child_name);
336  
337 Returns a reference to the node stored under name C<$child_name>
338 within C<$node>. The name C<$child_name> does not necessarily belong
339 to the list of published children (in which case this is a B<hidden
340 child>). If the node contains neither a published nor a hidden child
341 under C<$child_name>, an exception is raised.
342  
343 C<$child_name> must be a non-empty string and must not contain any
344 slash (C<'/'>).
345  
346 =head3 content
347  
348 my $fh = $node->content or die "this node has no content";
349 while (my $content_line = <$fh>) {
350 print $content_line;
351 }
352  
353 Returns either C<undef>, or a reference to an IO::Handle-like object
354 having a C<getline> method. Several successive calls to the C<content()>
355 method will return the same handle, but each time re-positioned at
356 the beginning of the file (see L<IO::Seekable>).
357  
358  
359 =head2 Derived access methods
360  
361  
362  
363  
364 =head3 descendent
365  
366 my $descendent_node = $node->descendent($path);
367  
368 Returns the descendent node path C<$path>.
369  
370  
371  
372 =head1 SUBCLASSING
373  
374 To implement a new kind of node, you must subclass
375 C<Tree::Navigator::Node> and implement the methods described
376 below.
377  
378 =head2 MOUNT
379  
380 =head2 _children
381  
382 =head2 _child
383  
384 =head2 _attributes
385  
386 =head2 _content
387  
388 =head2 is_parent
389  
390  
391 =head1 AUTHOR, BUGS, SUPPORT, COPYRIGHT
392  
393 See L<Tree::Navigator>.
394  
395  
396 =head1 TODO
397  
398 - maybe this class should be split into a Role + a Base class
399  
400 REST API
401 /path/to/node
402 /path/to/node?v=view_name
403 /path/to/node/child_name
404 /path/to/node.attributes
405 /path/to/node.content
406 /path/to/node.children
407 ex: /path/to/file.doc
408 /path/to/file.doc?v=frame
409 /_toc/path/to/file.doc
410 /path/to/file.doc?v=title
411 /path/to/file.doc.attributes+content
412  
413 # OTHER POSSIBILITY
414 /path/to/node.$view_name (handy for .xml, .yaml, : auto MIME detection)
415 /path/to/node;subitem.$view_name
416 /path/to/node/@subitem.$view_name
417 /path/to/node?search=query
418  
419 Q : diff between
420 /path/to/node/ : full data (attributes, children % content)
421 /path/to/node
422 ?v=view
423 p=part1,part2
424 s=search_string
425  
426  
427  
428 METHODS
429  
430 my $data = $node->data(@parts);
431 my $view = $node->view($name, $view_args) || $tn->view()
432 my $resp = $view->render($data, $node, $tn);
433  
434 $node->retrieve($parts) # subnodes, leaves, attributes, content
435 $node->render($tn, $parts, $view, $view_args);
436 my $view = $node->view($name, $view_args) || $tn->view()
437 $node->present($tn, $parts, $view)
438 $view->present($node)
439  
440 Decide
441 - $node->child($wrong_path) : should die or return undef ?
442  
443  
444 ->mount(path => 'foo',
445 node_class => 'Filesys',
446 mount_point => )
447  
448 =cut
449  
450  
451  
452  
453  
454  
« Navigator/Node/Filesys.pm ↑ Summary Navigator/Node/Perl/Symdump.pm »