Phylo/NeXML/DOM/Element.pm untested

filter: Statementstmt 0.0% 0 / 43 Branchbran 0.0% 0 / 2 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 0.0% 0 / 25 Podpod 0.0% 0 / 21 totaltotal 0.0% 0 / 91 CC 2 SCAR 8.4
CC
2
Cov
0%
new
6.0
parse_element
2.0
_recurse_bless
2.0
CRAP 2.3
1 package Bio::Phylo::NeXML::DOM::Element;
2 use strict;
3 use warnings;
4 use Bio::Phylo::Util::Exceptions 'throw';
5 use Bio::Phylo::Util::CONSTANT qw'_ELEMENT_ /looks_like/';
6  
7 =head1 NAME
8  
9 Bio::Phylo::NeXML::DOM::Element - XML DOM Abstract class for
10 flexible document object model implementation
11  
12 =head1 SYNOPSIS
13  
14 Not used directly.
15  
16 =head1 DESCRIPTION
17  
18 This module describes an abstract implementation of a DOM object as
19 expected by Bio::Phylo. The methods here must be overridden in any
20 concrete implementation. The idea is that different implementations
21 use a particular XML DOM package, binding the methods here to
22 analogous package methods.
23  
24 This set of methods is intentionally minimal. The concrete instances
25 of this class should inherit both from ElementI and the underlying XML DOM
26 object class, so that package-specific methods can be directly
27 accessed from the instantiated object.
28  
29 =head1 AUTHOR
30  
31 Mark A. Jensen - maj -at- fortinbras -dot- us
32  
33 =cut
34  
35 =head2 Constructor
36  
37 =over
38  
39 =item new()
40  
41 Type : Constructor
42 Title : new
43 Usage : $elt = Bio::Phylo::NeXML::DOM::Element->new($tag, $attr)
44 Function: Create a new XML DOM element
45 Returns : DOM element object
46 Args : Optional:
47 '-tag' => $tag - tag name as string
48 '-attr' => $attr - hashref of attributes/values
49  
50 =cut
51  
52 sub new {
53 my $class = shift;
54 if ( my %args = looks_like_hash @_ ) {
55 $class = __PACKAGE__ . '::' . ucfirst( lc( $args{'-format'} ) );
56 delete $args{'-format'};
57 return looks_like_class($class)->new(%args);
58 }
59 }
60  
61 =item parse_element()
62  
63 Type : Factory method
64 Title : parse_element
65 Usage : $elt = $dom->parse_element($text)
66 Function: Create a new XML DOM element from XML text
67 Returns : DOM element
68 Args : An XML String
69  
70 =cut
71  
72 sub parse_element {
73 throw 'NotImplemented' => "Can't call 'get_tag' on interface";
74 }
75  
76 sub _recurse_bless {
77 my $node = shift;
78 my $class = ref $node;
79 for my $child ( @{ $node->get_children } ) {
80 bless $child, $class;
81 _recurse_bless($child);
82 }
83 }
84  
85 =back
86  
87 =head2 Namespace accessors/mutators
88  
89 =over
90  
91 =item
92  
93 Type :
94 Title :
95 Usage :
96 Function:
97 Returns :
98 Args :
99  
100 =cut
101  
102 =back
103  
104 =head2 Tagname mutators/accessors
105  
106 =over
107  
108 =item get_tag()
109  
110 Type : Accessor
111 Title : get_tag
112 Usage : $elt->get_tag()
113 Function: Get tag name
114 Returns : Tag name as scalar string
115 Args : none
116  
117 =cut
118  
119 sub get_tag {
120 throw 'NotImplemented' => "Can't call 'get_tag' on interface";
121 }
122  
123 =item set_tag()
124  
125 Type : Mutator
126 Title : set_tag
127 Usage : $elt->set_tag( $tagname )
128 Function: Set tagname
129 Returns : True on success
130 Args : Tag name as scalar string
131  
132 =cut
133  
134 sub set_tag {
135 throw 'NotImplemented' => "Can't call 'set_tag' on interface";
136 }
137  
138 =back
139  
140 =head2 Attribute mutators/accessors
141  
142 =over
143  
144 =item get_attributes()
145  
146 Type : Accessor
147 Title : get_attributes
148 Usage : $elt->get_attributes( @attribute_names )
149 Function: Get attribute values
150 Returns : A hash ref of key/value pairs
151 Args : Optional, [a list of] attribute name[s] as string[s]
152  
153 =cut
154  
155 sub get_attributes {
156 throw 'NotImplemented' => "Can't call 'get_attributes' on interface";
157 }
158  
159 =item set_attributes()
160  
161 Type : Mutator
162 Title : set_attributes
163 Usage : $elt->set_attributes( @attribute_assoc_array )
164 Function: Set attribute values
165 Returns : True on success
166 Args : An associative array of form ( $name => $value, ... )
167  
168 =cut
169  
170 sub set_attributes {
171 throw 'NotImplemented' => "Can't call 'set_attributes' on interface";
172 }
173  
174 =item clear_attributes()
175  
176 Type : Mutator
177 Title : clear_attributes
178 Usage : $elt->clear_attributes( @attribute_names )
179 Function: Remove attributes from element
180 Returns : Hash of removed attributes/values
181 Args : Array of attribute names
182  
183 =cut
184  
185 sub clear_attributes {
186 throw 'NotImplemented' => "Can't call 'clear_attributes' on interface";
187 }
188  
189 =back
190  
191 =head2 Content mutators/accessors
192  
193 =over
194  
195 =item set_text()
196  
197 Type : Mutator
198 Title : set_text
199 Usage : $elt->set_text($text_content)
200 Function: Add a #TEXT node to the element
201 Returns : True on success
202 Args : scalar string
203  
204 =cut
205  
206 sub set_text {
207 throw 'NotImplemented' => "Can't call 'set_text' on interface";
208 }
209  
210 =item get_text()
211  
212 Type : Accessor
213 Title : get_text
214 Usage : $elt->get_text()
215 Function: Retrieve direct #TEXT descendants as (concatenated) string
216 Returns : scalar string (the text content)
217 Args : none
218  
219 =cut
220  
221 sub get_text {
222 throw 'NotImplemented' => "Can't call 'get_text' on interface";
223 }
224  
225 =item clear_text()
226  
227 Type : Mutator
228 Title : clear_text
229 Usage : $elt->clear_text()
230 Function: Remove direct #TEXT descendant nodes from element
231 Returns : True on success; false if no #TEXT nodes removed
232 Args : none
233  
234 =cut
235  
236 sub clear_text {
237 throw 'NotImplemented' => "Can't call 'clear_text' on interface";
238 }
239  
240 =back
241  
242 =head2 Traversal methods
243  
244 =over
245  
246 =item get_parent()
247  
248 Type : Accessor
249 Title : get_parent
250 Usage : $elt->get_parent()
251 Function: Get parent DOM node of invocant
252 Returns : Element object or undef if invocant is root
253 Args : none
254  
255 =cut
256  
257 sub get_parent {
258 throw 'NotImplemented' => "Can't call 'get_parent' on interface";
259 }
260  
261 =item get_children()
262  
263 Type : Accessor
264 Title : get_children
265 Usage : $elt->get_children()
266 Function: Get child nodes of invocant
267 Returns : Array ref of Elements
268 Args : none
269  
270 =cut
271  
272 sub get_children {
273 throw 'NotImplemented' => "Can't call 'get_children' on interface";
274 }
275  
276 =item get_first_daughter()
277  
278 Type : Accessor
279 Title : get_first_daughter
280 Usage : $elt->get_first_daughter()
281 Function: Get first child (as defined by underlying package) of invocant
282 Returns : Element object or undef if invocant is childless
283 Args : none
284  
285 =cut
286  
287 sub get_first_daughter {
288 throw 'NotImplemented' => "Can't call 'get_first_daughter' on interface";
289 }
290  
291 =item get_last_daughter()
292  
293 Type : Accessor
294 Title : get_last_daughter
295 Usage : $elt->get_last_daughter()
296 Function: Get last child (as defined by underlying package) of invocant
297 Returns : Element object or undef if invocant is childless
298 Args : none
299  
300 =cut
301  
302 sub get_last_daughter {
303 throw 'NotImplemented' => "Can't call 'get_last_daughter' on interface";
304 }
305  
306 =item get_next_sister()
307  
308 Type : Accessor
309 Title : get_next_sister
310 Usage : $elt->get_next_sister()
311 Function: Gets next sibling (as defined by underlying package) of invocant
312 Returns : Element object or undef if invocant is the rightmost element
313 Args : none
314  
315 =cut
316  
317 sub get_next_sister {
318 throw 'NotImplemented' => "Can't call 'get_next_sister' on interface";
319 }
320  
321 =item get_previous_sister()
322  
323 Type : Accessor
324 Title : get_previous_sister
325 Usage : $elt->get_previous_sister()
326 Function: Get previous sibling (as defined by underlying package) of invocant
327 Returns : Element object or undef if invocant is leftmost element
328 Args : none
329  
330 =cut
331  
332 sub get_previous_sister {
333 throw 'NotImplemented' => "Can't call 'get_previous_sister' on interface";
334 }
335  
336 =item get_elements_by_tagname()
337  
338 Type : Accessor
339 Title : get_elements_by_tagname
340 Usage : $elt->get_elements_by_tagname($tagname)
341 Function: Get array of elements having given tag name from invocant's
342 descendants
343 Returns : Array of elements or undef if no match
344 Args : tag name as string
345  
346 =cut
347  
348 sub get_elements_by_tagname {
349 throw 'NotImplemented' =>
350 "Can't call 'get_elements_by_tagname' on interface";
351 }
352  
353 =back
354  
355 =head2 Prune and graft methods
356  
357 =over
358  
359 =item set_child()
360  
361 Type : Mutator
362 Title : set_child
363 Usage : $elt->set_child($child)
364 Function: Add child element object to invocant's descendants
365 Returns : the element object added
366 Args : Element object
367  
368 =cut
369  
370 sub set_child {
371 throw 'NotImplemented' => "Can't call 'set_child' on interface";
372 }
373  
374 =item prune_child()
375  
376 Type : Mutator
377 Title : prune_child
378 Usage : $elt->prune_child($child)
379 Function: Remove the subtree rooted by $child from among the invocant's
380 descendants
381 Returns : $child or undef if $child is not among the children of invocant
382 Args : Element object
383  
384 =cut
385  
386 sub prune_child {
387 throw 'NotImplemented' => "Can't call 'prune_child' on interface";
388 }
389  
390 =back
391  
392 =head2 Output methods
393  
394 =over
395  
396 =item to_xml()
397  
398 Type : Serializer
399 Title : to_xml
400 Usage : $elt->to_xml
401 Function: Create XML string from subtree rooted by invocant
402 Returns : XML string
403 Args : Formatting arguments as allowed by underlying package
404  
405 =cut
406  
407 sub to_xml {
408 throw 'NotImplemented' => "Can't call 'to_xml' on interface";
409 }
410  
411 =back
412  
413 =head1 CITATION
414  
415 If you use Bio::Phylo in published research, please cite it:
416  
417 B<Rutger A Vos>, B<Jason Caravas>, B<Klaas Hartmann>, B<Mark A Jensen>
418 and B<Chase Miller>, 2011. Bio::Phylo - phyloinformatic analysis using Perl.
419 I<BMC Bioinformatics> B<12>:63.
420 L<http://dx.doi.org/10.1186/1471-2105-12-63>
421  
422 =cut
423  
424 1;