Phylo/NeXML/DOM/Element/Libxml.pm untested

filter: Statementstmt 0.0% 0 / 109 Branchbran 0.0% 0 / 26 Conditioncond 0.0% 0 / 9 MC/DCmcdc n/a Subroutinesub 0.0% 0 / 25 Podpod 0.0% 0 / 20 totaltotal 0.0% 0 / 189 CC 14 SCAR 23.4
CC
14
Cov
0%
new
42.0
set_attributes
12.0
clear_attributes
6.0
CRAP 10.4
1  
2 =head1 NAME
3  
4 Bio::Phylo::NeXML::DOM::Element::Libxml - XML DOM element mappings to the
5 C<XML::LibXML> package
6  
7 =head1 SYNOPSIS
8  
9 Don't use directly; use Bio::Phylo::NeXML::DOM->new( -format => 'libxml' ) instead.
10  
11 =head1 DESCRIPTION
12  
13 This module provides mappings the methods specified in the
14 L<Bio::Phylo::NeXML::DOM::Element> abstract class to the
15 C<XML::LibXML::Element> package.
16  
17 =head1 AUTHOR
18  
19 Mark A. Jensen ( maj -at- fortinbras -dot- us )
20  
21 =cut
22  
23 package Bio::Phylo::NeXML::DOM::Element::Libxml;
24 use strict;
25 use Bio::Phylo::Util::Exceptions 'throw';
26 use Bio::Phylo::Util::CONSTANT '/looks_like/';
27 use Bio::Phylo::Util::Dependency 'XML::LibXML';
28 use base qw'Bio::Phylo::NeXML::DOM::Element XML::LibXML::Element';
29 XML::LibXML->import(':libxml');
30  
31 =head2 Constructor
32  
33 =over
34  
35 =item new()
36  
37 Type : Constructor
38 Title : new
39 Usage : $elt = Bio::Phylo::NeXML::DOM::Element->new($tag, $attr)
40 Function: Create a new XML DOM element
41 Returns : DOM element object
42 Args : Optional:
43 '-tag' => $tag - tag name as string
44 '-attributes' => $attr - hashref of attributes/values
45  
46 =cut
47  
48 sub new {
49 my $class = shift;
50 if ( my %args = looks_like_hash @_ ) {
51 if ( $args{'-tag'} ) {
52 my $self = XML::LibXML::Element->new( $args{'-tag'} );
53 bless $self, $class;
54 delete $args{'-tag'};
55 for my $key ( keys %args ) {
56 my $method = $key;
57 $method =~ s/^-//;
58 $method = 'set_' . $method;
59 eval { $self->$method( $args{$key} ); };
60 if ($@) {
61 if ( blessed $@ and $@->can('rethrow') ) {
62 $@->rethrow;
63 }
64 elsif ( not ref($@)
65 and $@ =~ /^Can't locate object method / )
66 {
67 throw 'BadArgs' =>
68 "The named argument '${key}' cannot be passed to the constructor";
69 }
70 else {
71 throw 'Generic' => $@;
72 }
73 }
74 }
75 return $self;
76 }
77 else {
78 throw 'BadArgs' => "Tag name required for XML::LibXML::Element";
79 }
80 }
81 else {
82 throw 'BadArgs' => "Tag name required for XML::LibXML::Element";
83 }
84 }
85  
86 =item parse_element()
87  
88 Type : Factory method
89 Title : parse_element
90 Usage : $elt = $dom->parse_element($text)
91 Function: Create a new XML DOM element from XML text
92 Returns : DOM element
93 Args : An XML String
94  
95 =cut
96  
97 sub parse_element {
98 my ( $class, $text ) = @_;
99 my $dom = XML::LibXML->load_xml($text);
100 my $root = $dom->documentElement();
101 bless $root, __PACKAGE__;
102 Bio::Phylo::NeXML::DOM::Element::_recurse_bless($root);
103 return $root;
104 }
105  
106 =back
107  
108 =head2 Tagname mutators/accessors
109  
110 =over
111  
112 =item get_tag()
113  
114 Type : Accessor
115 Title : get_tag
116 Usage : $elt->get_tag()
117 Function: Get tag name
118 Returns : Tag name as scalar string
119 Args : none
120  
121 =cut
122  
123 sub get_tag {
124 return shift->tagName;
125 }
126  
127 =item set_tag()
128  
129 Type : Mutator
130 Title : set_tag
131 Usage : $elt->set_tag( $tagname )
132 Function: Set tagname
133 Returns : True on success
134 Args : Tag name as scalar string
135  
136 =cut
137  
138 sub set_tag {
139 my ( $self, $tagname, @args ) = @_;
140 $self->setNodeName($tagname);
141 return $self;
142 }
143  
144 =back
145  
146 =head2 Attribute mutators/accessors
147  
148 =over
149  
150 =item get_attributes()
151  
152 Type : Accessor
153 Title : get_attributes
154 Usage : $elt->get_attributes( @attribute_names )
155 Function: Get attribute values
156 Returns : Array of attribute values
157 Args : [an array of] attribute name[s] as string[s]
158  
159 =cut
160  
161 sub get_attributes {
162 my ( $self, @attr_names ) = @_;
163 my %ret = map { $_ => $self->getAttribute($_) } @attr_names;
164 return \%ret;
165 }
166  
167 =item set_attributes()
168  
169 Type : Mutator
170 Title : set_attributes
171 Usage : $elt->set_attributes( @attribute_assoc_array )
172 Function: Set attribute values
173 Returns : True on success
174 Args : An associative array of form ( $name => $value, ... )
175  
176 =cut
177  
178 sub set_attributes {
179 my $self = shift;
180 if (@_) {
181 my %attr;
182 if ( @_ == 1 && looks_like_instance $_[0], 'HASH' ) {
183 %attr = %{ $_[0] };
184 }
185 else {
186 %attr = looks_like_hash @_;
187 }
188 $self->setAttribute( $_, $attr{$_} ) for keys %attr;
189 }
190 return $self;
191 }
192  
193 =item clear_attributes()
194  
195 Type : Mutator
196 Title : clear_attributes
197 Usage : $elt->clear_attributes( @attribute_names )
198 Function: Remove attributes from element
199 Returns : Hash of removed attributes/values
200 Args : Array of attribute names
201  
202 =cut
203  
204 sub clear_attributes {
205 my ( $self, @attr_names ) = @_;
206 return 0 if not @attr_names;
207 my %ret;
208 $ret{$_} = $self->getAttribute($_) for @attr_names;
209 $self->removeAttribute($_) for @attr_names;
210 return %ret;
211 }
212  
213 =back
214  
215 =head2 Content mutators/accessors
216  
217 =over
218  
219 =item set_text()
220  
221 Type : Mutator
222 Title : set_text
223 Usage : $elt->set_text($text_content)
224 Function: Add a #TEXT node to the element
225 Returns : True on success
226 Args : scalar string
227  
228 =cut
229  
230 sub set_text {
231 my ( $self, $text, @args ) = @_;
232 if ($text) {
233 $self->appendTextNode($text);
234 return $self;
235 }
236 else {
237 throw 'BadArgs' => "No text specified";
238 }
239 }
240  
241 =item get_text()
242  
243 Type : Accessor
244 Title : get_text
245 Usage : $elt->get_text()
246 Function: Retrieve direct #TEXT descendants as (concatenated) string
247 Returns : scalar string (the text content) or undef if no text nodes
248 Args : none
249  
250 =cut
251  
252 #no strict;
253 sub get_text {
254 my ( $self, @args ) = @_;
255 my $text;
256 for ( $self->childNodes ) {
257 $text .= $_->nodeValue if $_->nodeType == XML::LibXML::XML_TEXT_NODE;
258 }
259 return $text;
260 }
261  
262 #use strict;
263  
264 =item clear_text()
265  
266 Type : Mutator
267 Title : clear_text
268 Usage : $elt->clear_text()
269 Function: Remove direct #TEXT descendant nodes from element
270 Returns : True on success; false if no #TEXT nodes removed
271 Args : none
272  
273 =cut
274  
275 #no strict;
276 sub clear_text {
277 my ( $self, @args ) = @_;
278 my @res = map {
279 $_->nodeType == XML::LibXML::XML_TEXT_NODE
280 ? $self->removeChild($_)
281 : ()
282 } $self->childNodes;
283 return !!scalar(@res);
284 }
285  
286 #use strict;
287  
288 =back
289  
290 =head2 Traversal methods
291  
292 =over
293  
294 =item get_parent()
295  
296 Type : Accessor
297 Title : get_parent
298 Usage : $elt->get_parent()
299 Function: Get parent DOM node of invocant
300 Returns : Element object or undef if invocant is root
301 Args : none
302  
303 =cut
304  
305 sub get_parent {
306 my $e = shift->parentNode;
307 return bless $e, __PACKAGE__;
308 }
309  
310 =item get_children()
311  
312 Type : Accessor
313 Title : get_children
314 Usage : $elt->get_children()
315 Function: Get child nodes of invocant
316 Returns : Array of Elements
317 Args : none
318  
319 =cut
320  
321 sub get_children {
322 my @ret = shift->childNodes;
323 bless( $_, __PACKAGE__ ) for (@ret);
324 return \@ret;
325 }
326  
327 =item get_first_daughter()
328  
329 Type : Accessor
330 Title : get_first_daughter
331 Usage : $elt->get_first_daughter()
332 Function: Get first child (as defined by underlying package) of invocant
333 Returns : Element object or undef if invocant is childless
334 Args : none
335  
336 =cut
337  
338 sub get_first_daughter {
339 my $e = shift->firstChild;
340 return bless $e, __PACKAGE__;
341 }
342  
343 =item get_last_daughter()
344  
345 Type : Accessor
346 Title : get_last_daughter
347 Usage : $elt->get_last_daughter()
348 Function: Get last child (as defined by underlying package) of invocant
349 Returns : Element object or undef if invocant is childless
350 Args : none
351  
352 =cut
353  
354 sub get_last_daughter {
355 my $e = shift->lastChild;
356 return bless $e, __PACKAGE__;
357 }
358  
359 =item get_next_sister()
360  
361 Type : Accessor
362 Title : get_next_sister
363 Usage : $elt->get_next_sister()
364 Function: Gets next sibling (as defined by underlying package) of invocant
365 Returns : Element object or undef if invocant is the rightmost element
366 Args : none
367  
368 =cut
369  
370 sub get_next_sister {
371 my $e = shift->nextSibling;
372 return bless $e, __PACKAGE__;
373 }
374  
375 =item get_previous_sister()
376  
377 Type : Accessor
378 Title : get_previous_sister
379 Usage : $elt->get_previous_sister()
380 Function: Get previous sibling (as defined by underlying package) of invocant
381 Returns : Element object or undef if invocant is leftmost element
382 Args : none
383  
384 =cut
385  
386 sub get_previous_sister {
387 my $e = shift->previousSibling;
388 return bless $e, __PACKAGE__;
389 }
390  
391 =item get_elements_by_tagname()
392  
393 Type : Accessor
394 Title : get_elements_by_tagname
395 Usage : $elt->get_elements_by_tagname($tagname)
396 Function: Get array of elements having given tag name from invocant's
397 descendants
398 Returns : Array of elements or undef if no match
399 Args : tag name as string
400  
401 =cut
402  
403 sub get_elements_by_tagname {
404 my ( $self, $tagname, @args ) = @_;
405 my @a = $self->getElementsByTagName($tagname);
406 bless( $_, __PACKAGE__ ) for (@a);
407 return @a;
408 }
409  
410 =back
411  
412 =head2 Prune and graft methods
413  
414 =over
415  
416 =item set_child()
417  
418 Type : Mutator
419 Title : set_child
420 Usage : $elt->set_child($child)
421 Function: Add child element object to invocant's descendants
422 Returns : the element object added
423 Args : Element object
424 Note : See caution at
425 L<http://search.cpan.org/~pajas/XML-LibXML-1.69/lib/XML/LibXML/Node.pod#addChild>
426  
427 =cut
428  
429 sub set_child {
430 my ( $self, $child, @args ) = @_;
431 if ( looks_like_instance $child, 'XML::LibXML::Node' ) {
432 return $self->addChild($child);
433 }
434 else {
435 throw 'ObjectMismatch' => "Argument is not an XML::LibXML::Node";
436 }
437 }
438  
439 =item prune_child()
440  
441 Type : Mutator
442 Title : prune_child
443 Usage : $elt->prune_child($child)
444 Function: Remove the subtree rooted by $child from among the invocant's
445 descendants
446 Returns : $child or undef if $child is not among the children of invocant
447 Args : Element object
448  
449 =cut
450  
451 sub prune_child {
452 my ( $self, $child, @args ) = @_;
453 if ( looks_like_instance $child, 'XML::LibXML::Node' ) {
454 return $self->removeChild($child);
455 }
456 else {
457 throw 'ObjectMismatch' => "Argument is not an XML::LibXML::Node";
458 }
459 }
460  
461 =back
462  
463 =head2 Output methods
464  
465 =over
466  
467 =item to_xml()
468  
469 Type : Serializer
470 Title : to_xml
471 Usage : $elt->to_xml
472 Function: Create XML string from subtree rooted by invocant
473 Returns : XML string
474 Args : Formatting arguments as allowed by underlying package
475  
476 =cut
477  
478 sub to_xml {
479 my ( $self, @args ) = @_;
480 return $self->toString(@args);
481 }
482  
483 =back
484  
485 =head1 CITATION
486  
487 If you use Bio::Phylo in published research, please cite it:
488  
489 B<Rutger A Vos>, B<Jason Caravas>, B<Klaas Hartmann>, B<Mark A Jensen>
490 and B<Chase Miller>, 2011. Bio::Phylo - phyloinformatic analysis using Perl.
491 I<BMC Bioinformatics> B<12>:63.
492 L<http://dx.doi.org/10.1186/1471-2105-12-63>
493  
494 =cut
495  
496 1;