Phylo/NeXML/DOM/Document/Libxml.pm untested

filter: Statementstmt 0.0% 0 / 49 Branchbran 0.0% 0 / 6 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 0.0% 0 / 15 Podpod 0.0% 0 / 9 totaltotal 0.0% 0 / 79 CC 4 SCAR 14.1
CC
4
Cov
0%
get_element_by_id
12.0
set_root
6.0
new
2.0
CRAP 4.1
1  
2 =head1 NAME
3  
4 Bio::Phylo::NeXML::DOM::Document::Libxml - XML DOM document mappings to the
5 C<XML::LibXML> package
6  
7 =head1 SYNOPSIS
8  
9 Don't use directly; use Bio::Phylo::NeXML::DOM->new( -format => 'libxml' ) instead.
10  
11 =head1 DESCRIPTION
12  
13 This module provides mappings the methods specified in the
14 L<Bio::Phylo::NeXML::DOM::Document> abstract class to the C<XML::LibXML::Document>
15 package.
16  
17 =head1 AUTHOR
18  
19 Mark A. Jensen ( maj -at- fortinbras -dot- us )
20  
21 =cut
22  
23 package Bio::Phylo::NeXML::DOM::Document::Libxml;
24 use strict;
25 use Bio::Phylo::Util::Exceptions 'throw';
26 use Bio::Phylo::Util::Dependency 'XML::LibXML';
27 use Bio::Phylo::Util::CONSTANT 'looks_like_instance';
28 use Bio::Phylo::NeXML::DOM::Element::Libxml (); # for blessing
29 use base qw'Bio::Phylo::NeXML::DOM::Document XML::LibXML::Document';
30  
31 =head2 Constructor
32  
33 =over
34  
35 =item new()
36  
37 Type : Constructor
38 Title : new
39 Usage : $doc = Bio::Phylo::NeXML::DOM::Document->new(@args)
40 Function: Create a Document object using the underlying package
41 Returns : Document object or undef on fail
42 Args : Package-specific arguments
43  
44 =cut
45  
46 sub new {
47 my ( $class, @args ) = @_;
48 my $self = XML::LibXML::Document->new(@args);
49 bless $self, $class;
50 return $self;
51 }
52  
53 =item parse_document()
54  
55 Type : Factory method
56 Title : parse_document
57 Usage : $doc = $dom->parse_document($text)
58 Function: Create a new XML DOM document from XML text
59 Returns : DOM document
60 Args : An XML String
61  
62 =cut
63  
64 sub parse_document {
65 my ( $class, $text ) = @_;
66 my $dom = XML::LibXML->load_xml($text);
67 bless $dom, $class;
68 return $dom;
69 }
70  
71 =back
72  
73 =cut
74  
75 =head2 Document property accessors/mutators
76  
77 =over
78  
79 =item set_encoding()
80  
81 Type : Mutator
82 Title : set_encoding
83 Usage : $doc->set_encoding($enc)
84 Function: Set encoding for document
85 Returns : True on success
86 Args : Encoding descriptor as string
87  
88 =cut
89  
90 sub set_encoding {
91 return shift->setEncoding(shift);
92 }
93  
94 =item get_encoding()
95  
96 Type : Accessor
97 Title : get_encoding
98 Usage : $doc->get_encoding()
99 Function: Get encoding for document
100 Returns : Encoding descriptor as string
101 Args : none
102  
103 =cut
104  
105 sub get_encoding {
106 return shift->encoding;
107 }
108  
109 =item set_root()
110  
111 Type : Mutator
112 Title : set_root
113 Usage : $doc->set_root($elt)
114 Function: Set the document's root element
115 Returns : True on success
116 Args : Element object
117  
118 =cut
119  
120 sub set_root {
121 my ( $self, $root ) = @_;
122 if ( looks_like_instance $root, 'XML::LibXML::Element' ) {
123 $self->setDocumentElement($root);
124 return 1;
125 }
126 else {
127 throw 'ObjectMismatch' => "Argument is not an XML::LibXML::Element";
128 }
129 }
130  
131 =item get_root()
132  
133 Type : Accessor
134 Title : get_root
135 Usage : $doc->get_root()
136 Function: Get the document's root element
137 Returns : Element object or undef if DNE
138 Args : none
139  
140 =cut
141  
142 sub get_root {
143 return shift->documentElement;
144 }
145  
146 =back
147  
148 =cut
149  
150 =head2 Document element accessors
151  
152 =over
153  
154 =item get_element_by_id()
155  
156 Type : Accessor
157 Title : get_element_by_id
158 Usage : $doc->get_element_by_id($id)
159 Function: Get element having id $id
160 Returns : Element object or undef if DNE
161 Args : id designator as string
162  
163 =cut
164  
165 # the XML::LibXML::Document::get_element_by_id() retrieves only
166 # via @xml:id attributes in a general XML file. This is a kludge
167 # using an XPath expression to find an unqualified id attribute
168 # that matches.
169 sub get_element_by_id {
170 my ( $self, $id ) = @_;
171 unless ($id) {
172 throw 'BadArgs' => "Argument 'id' required";
173 }
174 my $xp = "//*[\@id = '$id']";
175 my $e = $self->get_root->find($xp);
176 return unless $e; # don't return undef explicitly, do it this way
177 $e = $e->shift;
178 return bless $e, 'Bio::Phylo::NeXML::DOM::Element::Libxml';
179 }
180  
181 =item get_elements_by_tagname()
182  
183 Type : Accessor
184 Title : get_elements_by_tagname
185 Usage : $elt->get_elements_by_tagname($tagname)
186 Function: Get array of elements having given tag name
187 Returns : Array of elements or undef if no match
188 Args : tag name as string
189  
190 =cut
191  
192 sub get_elements_by_tagname {
193 my ( $self, $tagname, @args ) = @_;
194 my @a = $self->getElementsByTagName($tagname);
195 bless( $_, 'Bio::Phylo::NeXML::DOM::Element::Libxml' ) for (@a);
196 return @a;
197 }
198  
199 =back
200  
201 =head2 Output methods
202  
203 =over
204  
205 =item to_xml()
206  
207 Type : Serializer
208 Title : to_xml
209 Usage : $doc->to_xml
210 Function: Create XML string from document
211 Returns : XML string
212 Args : Formatting arguments as allowed by underlying package
213  
214 =cut
215  
216 sub to_xml {
217 my ( $self, @args ) = @_;
218 return $self->toString(@args);
219 }
220  
221 =back
222  
223 =head1 CITATION
224  
225 If you use Bio::Phylo in published research, please cite it:
226  
227 B<Rutger A Vos>, B<Jason Caravas>, B<Klaas Hartmann>, B<Mark A Jensen>
228 and B<Chase Miller>, 2011. Bio::Phylo - phyloinformatic analysis using Perl.
229 I<BMC Bioinformatics> B<12>:63.
230 L<http://dx.doi.org/10.1186/1471-2105-12-63>
231  
232 =cut
233  
234 1;