Phylo/NeXML/DOM/Element.pm untested

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