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