1 2=head1 NAME 3 4Bio::Phylo::NeXML::DOM::Document::Twig - XML DOM document mappings to the 5C<XML::Twig> package 6 7=head1 SYNOPSIS 8 9Don't use directly; use Bio::Phylo::NeXML::DOM->new( -format => 'twig' ) instead. 10 11=head1 DESCRIPTION 12 13This module provides mappings the methods specified in the 14L<Bio::Phylo::NeXML::DOM::Document> abstract class to the 15C<XML::Twig> package. 16 17=head1 AUTHOR 18 19Mark A. Jensen ( maj -at- fortinbras -dot- us ) 20 21=cut 22 23package Bio::Phylo::NeXML::DOM::Document::Twig; 24use strict; 25use warnings; 26use Bio::Phylo::Util::Exceptions 'throw'; 27use Bio::Phylo::Util::Dependency 'XML::Twig'; 28use Bio::Phylo::NeXML::DOM::Document; 29use Bio::Phylo::Util::CONSTANT 'looks_like_instance'; 30use base qw'Bio::Phylo::NeXML::DOM::Document XML::Twig'; 31 32=head2 Constructor 33 34=over 35 36=item new() 37 38 Type : Constructor 39 Title : new 40 Usage : $doc = Bio::Phylo::NeXML::DOM::Document->new(@args) 41 Function: Create a Document object using the underlying package 42 Returns : Document object or undef on fail 43 Args : Package-specific arguments 44 45=cut 46 47sub new { 48 my ( $class, @args ) = @_; 49 my $self = XML::Twig->new(); 50 $self->set_encoding(); 51 bless $self, $class; 52 return $self; 53} 54 55=item parse_document() 56 57 Type : Factory method 58 Title : parse_document 59 Usage : $doc = $dom->parse_document($text) 60 Function: Create a new XML DOM document from XML text 61 Returns : DOM document 62 Args : An XML String 63 64=cut 65 66sub parse_document { 67 my ( $class, $text ) = @_; 68 my $self = XML::Twig->new(); 69 $self->parse($text); 70 bless $self, $class; 71 return $self; 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 my ( $self, $encoding, @args ) = @_; 95 $self->set_encoding($encoding); 96 return 1; 97} 98 99=item get_encoding() 100 101 Type : Accessor 102 Title : get_encoding 103 Usage : $doc->get_encoding() 104 Function: Get encoding for document 105 Returns : Encoding descriptor as string 106 Args : none 107 108=cut 109 110sub get_encoding { 111 return shift->encoding; 112} 113 114=item set_root() 115 116 Type : Mutator 117 Title : set_root 118 Usage : $doc->set_root($elt) 119 Function: Set the document's root element 120 Returns : True on success 121 Args : Element object 122 123=cut 124 125sub set_root { 126 my ( $self, $root ) = @_; 127 if ( looks_like_instance $root, 'XML::Twig::Elt' ) { 128 XML::Twig::set_root( $self, $root ); 129 130 # manage ids 131 for ( $root->descendants_or_self ) { 132 ${ $self->{twig_id_list} }{ $_->att('id') } = $_ if $_->att('id'); 133 } 134 return 1; 135 } 136 else { 137 throw 'ObjectMisMatch' => 'Argument is not an XML::Twig::Elt'; 138 } 139} 140 141=item get_root() 142 143 Type : Accessor 144 Title : get_root 145 Usage : $doc->get_root() 146 Function: Get the document's root element 147 Returns : Element object or undef if DNE 148 Args : none 149 150=cut 151 152sub get_root { 153 return shift->root; 154} 155 156=back 157 158=cut 159 160=head2 Document element accessors 161 162=over 163 164=item get_element_by_id() 165 166 Type : Accessor 167 Title : get_element_by_id 168 Usage : $doc->get_element_by_id($id) 169 Function: Get element having id $id 170 Returns : Element object or undef if DNE 171 Args : id designator as string 172 173=cut 174 175sub get_element_by_id { 176 return shift->elt_id(shift); 177} 178 179=item get_elements_by_tagname() 180 181 Type : Accessor 182 Title : get_elements_by_tagname 183 Usage : $elt->get_elements_by_tagname($tagname) 184 Function: Get array of elements having given tag name 185 Returns : Array of elements or undef if no match 186 Args : tag name as string 187 188=cut 189 190sub get_elements_by_tagname { 191 my ( $self, $tagname, @args ) = @_; 192 return $self->get_root->get_elements_by_tagname($tagname); 193} 194 195=back 196 197=head2 Output methods 198 199=over 200 201=item to_xml() 202 203 Type : Serializer 204 Title : to_xml 205 Usage : $doc->to_xml 206 Function: Create XML string from document 207 Returns : XML string 208 Args : Formatting arguments as allowed by underlying package 209 210=cut 211 212sub to_xml { 213 my ( $self, @args ) = @_; 214 return $self->sprint(@args); 215} 216 217=back 218 219=head1 CITATION 220 221If you use Bio::Phylo in published research, please cite it: 222 223B<Rutger A Vos>, B<Jason Caravas>, B<Klaas Hartmann>, B<Mark A Jensen> 224and B<Chase Miller>, 2011. Bio::Phylo - phyloinformatic analysis using Perl. 225I<BMC Bioinformatics> B<12>:63. 226L<http://dx.doi.org/10.1186/1471-2105-12-63> 227 228=cut 229 2301; 231