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

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