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

filter: Statementstmt 0.0% 0 / 147 Branchbran 0.0% 0 / 48 Conditioncond 0.0% 0 / 18 MC/DCmcdc 0.0% 0 / 12 Subroutinesub 0.0% 0 / 28 Podpod 0.0% 0 / 21 totaltotal 0.0% 0 / 274 CC 25 SCAR 34.7
CC
25
Cov
0%
_manage_ids
110.0
new
56.0
set_attributes
12.0
CRAP 32.2
1 package Bio::Phylo::NeXML::DOM::Element::Twig;
2 use strict;
3 use warnings;
4 use Bio::Phylo::Util::Exceptions 'throw';
5 use Bio::Phylo::Util::Dependency 'XML::Twig';
6 use base qw'Bio::Phylo::NeXML::DOM::Element XML::Twig::Elt';
7 use Bio::Phylo::Util::CONSTANT '/looks_like/';
8 use Scalar::Util 'blessed';
9 our %extant_ids;
10  
11 =head1 NAME
12  
13 Bio::Phylo::NeXML::DOM::Element::Twig - XML DOM mappings to the
14 XML::Twig package
15  
16 =head1 SYNOPSIS
17  
18 Don't use directly; use Bio::Phylo::NeXML::DOM->new( -format => 'twig' ) instead.
19  
20 =head1 DESCRIPTION
21  
22 This module provides mappings the methods specified in the
23 L<Bio::Phylo::NeXML::DOM::Element> abstract class.
24  
25 =head1 AUTHOR
26  
27 Mark A. Jensen ( maj -at- fortinbras -dot- us )
28  
29 =cut
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 my $self = XML::Twig::Elt->new;
51 bless $self, $class;
52 if (@_) {
53 if ( my %arguments = looks_like_hash @_ ) {
54 for my $key ( keys %arguments ) {
55 my $method = $key;
56 $method =~ s/^-//;
57 $method = 'set_' . $method;
58 eval { $self->$method( $arguments{$key} ); };
59 if ($@) {
60 if ( blessed $@ and $@->can('rethrow') ) {
61 $@->rethrow;
62 }
63 elsif ( not ref($@)
64 and $@ =~ /^Can't locate object method / )
65 {
66 throw 'BadArgs' =>
67 "The named argument '${key}' cannot be passed to the constructor";
68 }
69 else {
70 throw 'Generic' => $@;
71 }
72 }
73 }
74 if ( $arguments{'-attributes'} ) {
75 my %attributes = %{ $arguments{'-attributes'} };
76 $self->_manage_ids( 'ADD', %attributes );
77 }
78 }
79 }
80 return $self;
81 }
82  
83 =item parse_element()
84  
85 Type : Factory method
86 Title : parse_element
87 Usage : $elt = $dom->parse_element($text)
88 Function: Create a new XML DOM element from XML text
89 Returns : DOM element
90 Args : An XML String
91  
92 =cut
93  
94 sub parse_element {
95 my ( $class, $text ) = @_;
96 my $twig = XML::Twig->new;
97 $twig->parse($text);
98 my $root = $twig->root;
99 bless $root, __PACKAGE__;
100 Bio::Phylo::NeXML::DOM::Element::_recurse_bless($root);
101 return $root;
102 }
103  
104 =back
105  
106 =head2 Tagname mutators/accessors
107  
108 =over
109  
110 =item get_tag()
111  
112 Type : Accessor
113 Title : get_tag
114 Usage : $elt->get_tag()
115 Function: Get tag name
116 Returns : Tag name as scalar string
117 Args : none
118  
119 =cut
120  
121 sub get_tag {
122 return shift->gi;
123 }
124  
125 =item set_tag()
126  
127 Type : Mutator
128 Title : set_tag
129 Usage : $elt->set_tag( $tagname )
130 Function: Set tagname
131 Returns : True on success
132 Args : Tag name as scalar string
133  
134 =cut
135  
136 sub set_tag {
137 my ( $self, $tagname ) = @_;
138 $self->set_gi($tagname);
139 return $self;
140 }
141  
142 =back
143  
144 =head2 Attribute mutators/accessors
145  
146 =over
147  
148 =item get_attributes()
149  
150 Type : Accessor
151 Title : get_attributes
152 Usage : $elt->get_attributes( @attribute_names )
153 Function: Get attribute values
154 Returns : Array of attribute values
155 Args : [an array of] attribute name[s] as string[s]
156  
157 =cut
158  
159 sub get_attributes {
160 my ( $self, @att_names ) = @_;
161 @att_names = $self->att_names if not @att_names;
162 my %ret = map { $_ => $self->att($_) } @att_names;
163 return \%ret;
164 }
165  
166 =item set_attributes()
167  
168 Type : Mutator
169 Title : set_attributes
170 Usage : $elt->set_attributes( @attribute_assoc_array )
171 Function: Set attribute values
172 Returns : True on success
173 Args : An associative array of form ( $name => $value, ... )
174  
175 =cut
176  
177 sub set_attributes {
178 my $self = shift;
179 if (@_) {
180 my %attr;
181 if ( @_ == 1 && looks_like_instance $_[0], 'HASH' ) {
182 %attr = %{ $_[0] };
183 }
184 else {
185 %attr = looks_like_hash @_;
186 }
187 $self->set_att(%attr);
188 $self->_manage_ids( 'ADD', %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 my %ret;
207 $ret{$_} = $self->att($_) for @attr_names;
208 $self->_manage_ids( 'DEL', @attr_names ); # must come before actual removal
209 $self->del_att(@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 my $t = XML::Twig::Elt->new( '#PCDATA', $text );
234 $t->paste( last_child => $self );
235 return 1;
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)
249 Args : none
250  
251 =cut
252  
253 sub get_text {
254 my ( $self, @args ) = @_;
255 return $self->text;
256 }
257  
258 =item clear_text()
259  
260 Type : Mutator
261 Title : clear_text
262 Usage : $elt->clear_text()
263 Function: Remove direct #TEXT descendant nodes from element
264 Returns : True on success; false if no #TEXT nodes removed
265 Args : none
266  
267 =cut
268  
269 sub clear_text {
270 my ( $self, @args ) = @_;
271 my @res;
272 @res = map {
273 $_->is_text ? do { $_->delete; 1 } : ()
274 } $self->children;
275 return 1 if @res;
276 return 0;
277 }
278  
279 =back
280  
281 =head2 Traversal methods
282  
283 =over
284  
285 =item get_parent()
286  
287 Type : Accessor
288 Title : get_parent
289 Usage : $elt->get_parent()
290 Function: Get parent DOM node of invocant
291 Returns : Element object or undef if invocant is root
292 Args : none
293  
294 =cut
295  
296 sub get_parent {
297 return shift->parent();
298 }
299  
300 =item get_children()
301  
302 Type : Accessor
303 Title : get_children
304 Usage : $elt->get_children()
305 Function: Get child nodes of invocant
306 Returns : Array of Elements
307 Args : none
308  
309 =cut
310  
311 sub get_children {
312 return [ shift->children() ];
313 }
314  
315 =item get_first_daughter()
316  
317 Type : Accessor
318 Title : get_first_daughter
319 Usage : $elt->get_first_daughter()
320 Function: Get first child (as defined by underlying package) of invocant
321 Returns : Element object or undef if invocant is childless
322 Args : none
323  
324 =cut
325  
326 sub get_first_daughter {
327 return shift->first_child();
328 }
329  
330 =item get_last_daughter()
331  
332 Type : Accessor
333 Title : get_last_daughter
334 Usage : $elt->get_last_daughter()
335 Function: Get last child (as defined by underlying package) of invocant
336 Returns : Element object or undef if invocant is childless
337 Args : none
338  
339 =cut
340  
341 sub get_last_daughter {
342 return shift->last_child();
343 }
344  
345 =item get_next_sister()
346  
347 Type : Accessor
348 Title : get_next_sister
349 Usage : $elt->get_next_sister()
350 Function: Gets next sibling (as defined by underlying package) of invocant
351 Returns : Element object or undef if invocant is the rightmost element
352 Args : none
353  
354 =cut
355  
356 sub get_next_sister {
357 return shift->next_sibling();
358 }
359  
360 =item get_previous_sister()
361  
362 Type : Accessor
363 Title : get_previous_sister
364 Usage : $elt->get_previous_sister()
365 Function: Get previous sibling (as defined by underlying package) of invocant
366 Returns : Element object or undef if invocant is leftmost element
367 Args : none
368  
369 =cut
370  
371 sub get_previous_sister {
372 return shift->prev_sibling();
373 }
374  
375 =item get_elements_by_tagname()
376  
377 Type : Accessor
378 Title : get_elements_by_tagname
379 Usage : $elt->get_elements_by_tagname($tagname)
380 Function: Get array of elements having given tag name from invocant's
381 descendants
382 Returns : Array of elements or undef if no match
383 Args : tag name as string
384  
385 =cut
386  
387 sub get_elements_by_tagname {
388 my ( $self, $tagname, @args ) = @_;
389 return $self->descendants_or_self($tagname);
390 }
391  
392 =back
393  
394 =head2 Prune and graft methods
395  
396 =over
397  
398 =item set_child()
399  
400 Type : Mutator
401 Title : set_child
402 Usage : $elt->set_child($child)
403 Function: Add child element object to invocant's descendants
404 Returns : the element object added
405 Args : Element object
406  
407 =cut
408  
409 sub set_child {
410 my ( $self, $child, @args ) = @_;
411 if ( looks_like_instance $child, 'XML::Twig::Elt' ) {
412 $child->paste( last_child => $self );
413 $self->_manage_ids('ADD');
414 return $child;
415 }
416 else {
417 throw 'ObjectMismatch' => 'Argument is not an XML::Twig::Elt';
418 }
419 }
420  
421 =item prune_child()
422  
423 Type : Mutator
424 Title : prune_child
425 Usage : $elt->prune_child($child)
426 Function: Remove the subtree rooted by $child from among the invocant's
427 descendants
428 Returns : $child or undef if $child is not among the children of invocant
429 Args : Element object
430  
431 =cut
432  
433 sub prune_child {
434 my ( $self, $child, @args ) = @_;
435 if ( looks_like_instance $child, 'XML::Twig::Elt' ) {
436 my $par = $child->parent;
437 return unless ( $par && ( $par == $self ) );
438  
439 # or delete?
440 $child->_manage_ids('DEL');
441 $child->cut;
442 return $child;
443 }
444 else {
445 throw 'ObjectMismatch' => 'Argument is not an XML::Twig::Elt';
446 }
447 }
448  
449 =back
450  
451 =head2 Output methods
452  
453 =over
454  
455 =item to_xml()
456  
457 Type : Serializer
458 Title : to_xml
459 Usage : $elt->to_xml
460 Function: Create XML string from subtree rooted by invocant
461 Returns : XML string
462 Args : Formatting arguments as allowed by underlying package
463  
464 =cut
465  
466 sub to_xml {
467 return shift->sprint(@_);
468 }
469  
470 =back
471  
472 =head1 CITATION
473  
474 If you use Bio::Phylo in published research, please cite it:
475  
476 B<Rutger A Vos>, B<Jason Caravas>, B<Klaas Hartmann>, B<Mark A Jensen>
477 and B<Chase Miller>, 2011. Bio::Phylo - phyloinformatic analysis using Perl.
478 I<BMC Bioinformatics> B<12>:63.
479 L<http://dx.doi.org/10.1186/1471-2105-12-63>
480  
481 =cut
482  
483 # note: we do our own updates of the Twig id list (the property
484 # $twig->{twig_id_list}, since according to the XML::Twig source
485 # "WARNING: at the moment the id list is not updated reliably" which
486 # evidently means that it isn't updated at all, unless the special
487 # add_id method is used. Since we want to create elements independent
488 # of the twig, I felt more in control doing it by by hand. The kludge
489 # allows the use of the Twig method elt_id() to "get_element_by_id"
490 # off a document object.
491 sub _manage_ids {
492 my ( $self, $action, @attrs ) = @_;
493 for ($action) {
494 $_ eq 'ADD' && do {
495 my %attrs = @attrs;
496 if (%attrs) { # changing/adding id attribute
497 my $id = $attrs{id};
498 if ($id) {
499 $extant_ids{$id} = $self; # log this id
500 ${ $self->twig->{twig_id_list} }{$id} = $self
501 if $self->twig;
502 }
503 else {
504 return 0;
505 }
506 }
507 else { # add this element and its descendants
508 # if all elements were created with new(), they all should
509 # logged in %extant_ids
510 if ( $self->twig ) {
511 for ( $self->descendants_or_self ) {
512 ${ $self->twig->{twig_id_list} }{ $_->att('id') } = $_
513 if $_->att('id');
514 }
515 }
516 }
517 last;
518 };
519 $_ eq 'DEL' && do {
520 if (@attrs) {
521 if ( grep /^id$/, @attrs ) {
522 my $id = $self->att('id');
523 delete $extant_ids{$id}; # clear this id
524 delete ${ $self->twig->{twig_id_list} }{$id} if $self->twig;
525 }
526 else {
527 return 0;
528 }
529 }
530 else {
531 if ( $self->twig ) {
532 delete $extant_ids{ $_->att('id') }
533 for $self->descendants_or_self;
534 delete ${ $self->twig->{twig_id_list} }{ $_->att('id') }
535 for $self->descendants_or_self;
536 }
537 }
538 last;
539 };
540 do {
541 throw 'BadArgs' => 'Unknown action for _manage_ids()';
542 };
543 }
544 return 1;
545 }
546 1;