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

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