Phylo/NeXML/DOM/Document.pm untested

filter: Statementstmt 0.0% 0 / 26 Branchbran 0.0% 0 / 2 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 0.0% 0 / 13 Podpod 0.0% 0 / 9 totaltotal 0.0% 0 / 50 CC 2 SCAR 9.4
CC
2
Cov
0%
new
6.0
parse_document
2.0
set_encoding
2.0
CRAP 2.6
1 package Bio::Phylo::NeXML::DOM::Document;
2 use strict;
3 use warnings;
4 use Bio::Phylo::Util::Exceptions 'throw';
5 use Bio::Phylo::Util::CONSTANT qw'_DOCUMENT_ /looks_like/';
6  
7 =head1 NAME
8  
9 Bio::Phylo::NeXML::DOM::Document - 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 document 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 DocumentI 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 : $doc = Bio::Phylo::NeXML::DOM::Document->new(@args)
44 Function: Create a Document object using the underlying package
45 Returns : Document object or undef on fail
46 Args : Package-specific arguments
47  
48 =cut
49  
50 sub new {
51 my $class = shift;
52 if ( my %args = looks_like_hash @_ ) {
53 $class = __PACKAGE__ . '::' . ucfirst( lc( $args{'-format'} ) );
54 delete $args{'-format'};
55 return looks_like_class($class)->new(%args);
56 }
57 }
58  
59 =item parse_document()
60  
61 Type : Factory method
62 Title : parse_document
63 Usage : $doc = $dom->parse_document($text)
64 Function: Create a new XML DOM document from XML text
65 Returns : DOM document
66 Args : An XML String
67  
68 =cut
69  
70 sub parse_document {
71 throw 'NotImplemented' => "Can't call 'parse_document' on interface";
72 }
73  
74 =back
75  
76 =cut
77  
78 =head2 Document property accessors/mutators
79  
80 =over
81  
82 =item set_encoding()
83  
84 Type : Mutator
85 Title : set_encoding
86 Usage : $doc->set_encoding($enc)
87 Function: Set encoding for document
88 Returns : True on success
89 Args : Encoding descriptor as string
90  
91 =cut
92  
93 sub set_encoding {
94 throw 'NotImplemented' => "Can't call 'set_encoding' on interface";
95 }
96  
97 =item get_encoding()
98  
99 Type : Accessor
100 Title : get_encoding
101 Usage : $doc->get_encoding()
102 Function: Get encoding for document
103 Returns : Encoding descriptor as string
104 Args : none
105  
106 =cut
107  
108 sub get_encoding {
109 throw 'NotImplemented' => "Can't call 'get_encoding' on interface";
110 }
111  
112 =item set_root()
113  
114 Type : Mutator
115 Title : set_root
116 Usage : $doc->set_root($elt)
117 Function: Set the document's root element
118 Returns : True on success
119 Args : Element object
120  
121 =cut
122  
123 sub set_root {
124 throw 'NotImplemented' => "Can't call 'set_root' on interface";
125 }
126  
127 =item get_root()
128  
129 Type : Accessor
130 Title : get_root
131 Usage : $doc->get_root()
132 Function: Get the document's root element
133 Returns : Element object or undef if DNE
134 Args : none
135  
136 =cut
137  
138 sub get_root {
139 throw 'NotImplemented' => "Can't call 'get_root' on interface";
140 }
141  
142 =back
143  
144 =cut
145  
146 =head2 Document element accessors
147  
148 =over
149  
150 =item get_element_by_id()
151  
152 Type : Accessor
153 Title : get_element_by_id
154 Usage : $doc->get_element_by_id($id)
155 Function: Get element having id $id
156 Returns : Element object or undef if DNE
157 Args : id designator as string
158  
159 =cut
160  
161 sub get_element_by_id {
162 throw 'NotImplemented' => "Can't call 'get_element_by_id' on interface";
163 }
164  
165 =item get_elements_by_tagname()
166  
167 Type : Accessor
168 Title : get_elements_by_tagname
169 Usage : $elt->get_elements_by_tagname($tagname)
170 Function: Get array of elements having given tag name
171 Returns : Array of elements or undef if no match
172 Args : tag name as string
173  
174 =cut
175  
176 sub get_elements_by_tagname {
177 throw 'NotImplemented' =>
178 "Can't call 'get_elements_by_tagname' on interface";
179 }
180  
181 =back
182  
183 =head2 Output methods
184  
185 =over
186  
187 =item to_xml()
188  
189 Type : Serializer
190 Title : to_xml
191 Usage : $doc->to_xml
192 Function: Create XML string from document
193 Returns : XML string
194 Args : Formatting arguments as allowed by underlying package
195  
196 =cut
197  
198 sub to_xml {
199 throw 'NotImplemented' => "Can't call 'to_xml_string' on interface";
200 }
201  
202 =back
203  
204 =head1 CITATION
205  
206 If you use Bio::Phylo in published research, please cite it:
207  
208 B<Rutger A Vos>, B<Jason Caravas>, B<Klaas Hartmann>, B<Mark A Jensen>
209 and B<Chase Miller>, 2011. Bio::Phylo - phyloinformatic analysis using Perl.
210 I<BMC Bioinformatics> B<12>:63.
211 L<http://dx.doi.org/10.1186/1471-2105-12-63>
212  
213 =cut
214  
215 1;