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