1package Bio::Phylo::NeXML::DOM::Document;
2use strict;
3use warnings;
4use Bio::Phylo::Util::Exceptions 'throw';
5use Bio::Phylo::Util::CONSTANT qw'_DOCUMENT_ /looks_like/';
6
7=head1 NAME
8
9Bio::Phylo::NeXML::DOM::Document - XML DOM Abstract class for
10flexible document object model implementation
11
12=head1 SYNOPSIS
13
14Not used directly.
15
16=head1 DESCRIPTION
17
18This module describes an abstract implementation of a DOM document as
19expected by Bio::Phylo. The methods here must be overridden in any
20concrete implementation. The idea is that different implementations
21use a particular XML DOM package, binding the methods here to
22analogous package methods.
23
24This set of methods is intentionally minimal. The concrete instances
25of this class should inherit both from DocumentI and the underlying XML DOM
26object class, so that package-specific methods can be directly
27accessed from the instantiated object.
28
29=head1 AUTHOR
30
31Mark 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
50sub 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
70sub 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
93sub 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
108sub 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
123sub 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
138sub 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
161sub 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
176sub 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
198sub to_xml {
199    throw 'NotImplemented' => "Can't call 'to_xml_string' on interface";
200}
201
202=back
203
204=head1 CITATION
205
206If you use Bio::Phylo in published research, please cite it:
207
208B<Rutger A Vos>, B<Jason Caravas>, B<Klaas Hartmann>, B<Mark A Jensen>
209and B<Chase Miller>, 2011. Bio::Phylo - phyloinformatic analysis using Perl.
210I<BMC Bioinformatics> B<12>:63.
211L<http://dx.doi.org/10.1186/1471-2105-12-63>
212
213=cut
214
2151;
216