1LibXML(3) User Contributed Perl Documentation LibXML(3)
2
6 XML::LibXML - Perl Binding for libxml2
7
9 use XML::LibXML;
10 my $dom = XML::LibXML->load_xml(string => <<'EOT');
11 <some-xml/>
12 EOT
13 $Version_String = XML::LibXML::LIBXML_DOTTED_VERSION;
15 $Version_ID = XML::LibXML::LIBXML_VERSION;
16 $DLL_Version = XML::LibXML::LIBXML_RUNTIME_VERSION;
17 $libxmlnode = XML::LibXML->import_GDOME( $node, $deep );
18 $gdomenode = XML::LibXML->export_GDOME( $node, $deep );
19
21 This module is an interface to libxml2, providing XML and HTML parsers
22 with DOM, SAX and XMLReader interfaces, a large subset of DOM Layer 3
23 interface and a XML::XPath-like interface to XPath API of libxml2. The
24 module is split into several packages which are not described in this
25 section; unless stated otherwise, you only need to "use XML::LibXML;"
26 in your programs.
27 For further information, please check the following documentation:
29 XML::LibXML::Parser
31 Parsing XML files with XML::LibXML
32 XML::LibXML::DOM
34 XML::LibXML Document Object Model (DOM) Implementation
35 XML::LibXML::SAX
37 XML::LibXML direct SAX parser
38 XML::LibXML::Reader
40 Reading XML with a pull-parser
41 XML::LibXML::Dtd
43 XML::LibXML frontend for DTD validation
44 XML::LibXML::RelaxNG
46 XML::LibXML frontend for RelaxNG schema validation
47 XML::LibXML::Schema
49 XML::LibXML frontend for W3C Schema schema validation
50 XML::LibXML::XPathContext
52 API for evaluating XPath expressions with enhanced support for the
53 evaluation context
54 XML::LibXML::InputCallback
56 Implementing custom URI Resolver and input callbacks
57 XML::LibXML::Common
59 Common functions for XML::LibXML related Classes
60 The nodes in the Document Object Model (DOM) are represented by the
62 following classes (most of which "inherit" from XML::LibXML::Node):
63 XML::LibXML::Document
65 XML::LibXML class for DOM document nodes
66 XML::LibXML::Node
68 Abstract base class for XML::LibXML DOM nodes
69 XML::LibXML::Element
71 XML::LibXML class for DOM element nodes
72 XML::LibXML::Text
74 XML::LibXML class for DOM text nodes
75 XML::LibXML::Comment
77 XML::LibXML class for comment DOM nodes
78 XML::LibXML::CDATASection
80 XML::LibXML class for DOM CDATA sections
81 XML::LibXML::Attr
83 XML::LibXML DOM attribute class
84 XML::LibXML::DocumentFragment
86 XML::LibXML's DOM L2 Document Fragment implementation
87 XML::LibXML::Namespace
89 XML::LibXML DOM namespace nodes
90 XML::LibXML::PI
92 XML::LibXML DOM processing instruction nodes
93
95 Recall that since version 5.6.1, Perl distinguishes between character
96 strings (internally encoded in UTF-8) and so called binary data and,
97 accordingly, applies either character or byte semantics to them. A
98 scalar representing a character string is distinguished from a byte
99 string by special flag (UTF8). Please refer to perlunicode for
100 details.
101 XML::LibXML's API is designed to deal with many encodings of XML
103 documents completely transparently, so that the application using
104 XML::LibXML can be completely ignorant about the encoding of the XML
105 documents it works with. On the other hand, functions like
106 "XML::LibXML::Document->setEncoding" give the user control over the
107 document encoding.
108 To ensure the aforementioned transparency and uniformity, most
110 functions of XML::LibXML that work with in-memory trees accept and
111 return data as character strings (i.e. UTF-8 encoded with the UTF8 flag
112 on) regardless of the original document encoding; however, the
113 functions related to I/O operations (i.e. parsing and saving) operate
114 with binary data (in the original document encoding) obeying the
115 encoding declaration of the XML documents.
116 Below we summarize basic rules and principles regarding encoding:
118 1. Do NOT apply any encoding-related PerlIO layers (":utf8" or
120 ":encoding(...)") to file handles that are an input for the parses
121 or an output for a serializer of (full) XML documents. This is
122 because the conversion of the data to/from the internal character
123 representation is provided by libxml2 itself which must be able to
124 enforce the encoding specified by the "<?xml version="1.0"
125 encoding="..."?>" declaration. Here is an example to follow:
126 use XML::LibXML;
128 # load
129 open my $fh, '<', 'file.xml';
130 binmode $fh; # drop all PerlIO layers possibly created by a use open pragma
131 $doc = XML::LibXML->load_xml(IO => $fh);
132 # save
134 open my $out, '>', 'out.xml';
135 binmode $out; # as above
136 $doc->toFH($out);
137 # or
138 print {$out} $doc->toString();
139 2. All functions working with DOM accept and return character strings
141 (UTF-8 encoded with UTF8 flag on). E.g.
142 my $doc = XML::LibXML::Document->new('1.0',$some_encoding);
144 my $element = $doc->createElement($name);
145 $element->appendText($text);
146 $xml_fragment = $element->toString(); # returns a character string
147 $xml_document = $doc->toString(); # returns a byte string
148 where $some_encoding is the document encoding that will be used
150 when saving the document, and $name and $text contain character
151 strings (UTF-8 encoded with UTF8 flag on). Note that the method
152 "toString" returns XML as a character string if applied to other
153 node than the Document node and a byte string containing the
154 appropriate
155 <?xml version="1.0" encoding="..."?>
157 declaration if applied to a XML::LibXML::Document.
159 3. DOM methods also accept binary strings in the original encoding of
161 the document to which the node belongs (UTF-8 is assumed if the
162 node is not attached to any document). Exploiting this feature is
163 NOT RECOMMENDED since it is considered bad practice.
164 my $doc = XML::LibXML::Document->new('1.0','iso-8859-2');
166 my $text = $doc->createTextNode($some_latin2_encoded_byte_string);
167 # WORKS, BUT NOT RECOMMENDED!
168 NOTE: libxml2 support for many encodings is based on the iconv library.
170 The actual list of supported encodings may vary from platform to
171 platform. To test if your platform works correctly with your language
172 encoding, build a simple document in the particular encoding and try to
173 parse it with XML::LibXML to see if the parser produces any errors.
174 Occasional crashes were reported on rare platforms that ship with a
175 broken version of iconv.
176
178 XML::LibXML since 1.67 partially supports Perl threads in Perl >=
179 5.8.8. XML::LibXML can be used with threads in two ways:
180 By default, all XML::LibXML classes use CLONE_SKIP class method to
182 prevent Perl from copying XML::LibXML::* objects when a new thread is
183 spawn. In this mode, all XML::LibXML::* objects are thread specific.
184 This is the safest way to work with XML::LibXML in threads.
185 Alternatively, one may use
187 use threads;
189 use XML::LibXML qw(:threads_shared);
190 to indicate, that all XML::LibXML node and parser objects should be
192 shared between the main thread and any thread spawn from there. For
193 example, in
194 my $doc = XML::LibXML->load_xml(location => $filename);
196 my $thr = threads->new(sub{
197 # code working with $doc
198 1;
199 });
200 $thr->join;
201 the variable $doc refers to the exact same XML::LibXML::Document in the
203 spawned thread as in the main thread.
204 Without using mutex locks, parallel threads may read the same document
206 (i.e. any node that belongs to the document), parse files, and modify
207 different documents.
208 However, if there is a chance that some of the threads will attempt to
210 modify a document (or even create new nodes based on that document,
211 e.g. with "$doc->createElement") that other threads may be reading at
212 the same time, the user is responsible for creating a mutex lock and
213 using it in both in the thread that modifies and the thread that reads:
214 my $doc = XML::LibXML->load_xml(location => $filename);
216 my $mutex : shared;
217 my $thr = threads->new(sub{
218 lock $mutex;
219 my $el = $doc->createElement('foo');
220 # ...
221 1;
222 });
223 {
224 lock $mutex;
225 my $root = $doc->documentElement;
226 say $root->name;
227 }
228 $thr->join;
229 Note that libxml2 uses dictionaries to store short strings and these
231 dictionaries are kept on a document node. Without mutex locks, it could
232 happen in the previous example that the thread modifies the dictionary
233 while other threads attempt to read from it, which could easily lead to
234 a crash.
235
237 Sometimes it is useful to figure out, for which version XML::LibXML was
238 compiled for. In most cases this is for debugging or to check if a
239 given installation meets all functionality for the package. The
240 functions XML::LibXML::LIBXML_DOTTED_VERSION and
241 XML::LibXML::LIBXML_VERSION provide this version information. Both
242 functions simply pass through the values of the similar named macros of
243 libxml2. Similarly, XML::LibXML::LIBXML_RUNTIME_VERSION returns the
244 version of the (usually dynamically) linked libxml2.
245 XML::LibXML::LIBXML_DOTTED_VERSION
247 $Version_String = XML::LibXML::LIBXML_DOTTED_VERSION;
248 Returns the version string of the libxml2 version XML::LibXML was
250 compiled for. This will be "2.6.2" for "libxml2 2.6.2".
251 XML::LibXML::LIBXML_VERSION
253 $Version_ID = XML::LibXML::LIBXML_VERSION;
254 Returns the version id of the libxml2 version XML::LibXML was
256 compiled for. This will be "20602" for "libxml2 2.6.2". Don't mix
257 this version id with $XML::LibXML::VERSION. The latter contains the
258 version of XML::LibXML itself while the first contains the version
259 of libxml2 XML::LibXML was compiled for.
260 XML::LibXML::LIBXML_RUNTIME_VERSION
262 $DLL_Version = XML::LibXML::LIBXML_RUNTIME_VERSION;
263 Returns a version string of the libxml2 which is (usually
265 dynamically) linked by XML::LibXML. This will be "20602" for
266 libxml2 released as "2.6.2" and something like "20602-CVS2032" for
267 a CVS build of libxml2.
268 XML::LibXML issues a warning if the version of libxml2 dynamically
270 linked to it is less than the version of libxml2 which it was
271 compiled against.
272
274 By default the module exports all constants and functions listed in the
275 :all tag, described below.
276
278 ":all"
279 Includes the tags ":libxml", ":encoding", and ":ns" described
280 below.
281 ":libxml"
283 Exports integer constants for DOM node types.
284 XML_ELEMENT_NODE => 1
286 XML_ATTRIBUTE_NODE => 2
287 XML_TEXT_NODE => 3
288 XML_CDATA_SECTION_NODE => 4
289 XML_ENTITY_REF_NODE => 5
290 XML_ENTITY_NODE => 6
291 XML_PI_NODE => 7
292 XML_COMMENT_NODE => 8
293 XML_DOCUMENT_NODE => 9
294 XML_DOCUMENT_TYPE_NODE => 10
295 XML_DOCUMENT_FRAG_NODE => 11
296 XML_NOTATION_NODE => 12
297 XML_HTML_DOCUMENT_NODE => 13
298 XML_DTD_NODE => 14
299 XML_ELEMENT_DECL => 15
300 XML_ATTRIBUTE_DECL => 16
301 XML_ENTITY_DECL => 17
302 XML_NAMESPACE_DECL => 18
303 XML_XINCLUDE_START => 19
304 XML_XINCLUDE_END => 20
305 ":encoding"
307 Exports two encoding conversion functions from XML::LibXML::Common.
308 encodeToUTF8()
310 decodeFromUTF8()
311 ":ns"
313 Exports two convenience constants: the implicit namespace of the
314 reserved "xml:" prefix, and the implicit namespace for the reserved
315 "xmlns:" prefix.
316 XML_XML_NS => 'http://www.w3.org/XML/1998/namespace'
318 XML_XMLNS_NS => 'http://www.w3.org/2000/xmlns/'
319
321 The modules described in this section are not part of the XML::LibXML
322 package itself. As they support some additional features, they are
323 mentioned here.
324 XML::LibXSLT
326 XSLT 1.0 Processor using libxslt and XML::LibXML
327 XML::LibXML::Iterator
329 XML::LibXML Implementation of the DOM Traversal Specification
330 XML::CompactTree::XS
332 Uses XML::LibXML::Reader to very efficiently to parse XML document
333 or element into native Perl data structures, which are less
334 flexible but significantly faster to process then DOM.
335
337 Note: THE FUNCTIONS DESCRIBED HERE ARE STILL EXPERIMENTAL
338 Although both modules make use of libxml2's XML capabilities, the DOM
340 implementation of both modules are not compatible. But still it is
341 possible to exchange nodes from one DOM to the other. The concept of
342 this exchange is pretty similar to the function cloneNode(): The
343 particular node is copied on the low-level to the opposite DOM
344 implementation.
345 Since the DOM implementations cannot coexist within one document, one
347 is forced to copy each node that should be used. Because you are always
348 keeping two nodes this may cause quite an impact on a machines memory
349 usage.
350 XML::LibXML provides two functions to export or import GDOME nodes:
352 import_GDOME() and export_GDOME(). Both function have two parameters:
353 the node and a flag for recursive import. The flag works as in
354 cloneNode().
355 The two functions allow one to export and import XML::GDOME nodes
357 explicitly, however, XML::LibXML also allows the transparent import of
358 XML::GDOME nodes in functions such as appendChild(), insertAfter() and
359 so on. While native nodes are automatically adopted in most functions
360 XML::GDOME nodes are always cloned in advance. Thus if the original
361 node is modified after the operation, the node in the XML::LibXML
362 document will not have this information.
363 import_GDOME
365 $libxmlnode = XML::LibXML->import_GDOME( $node, $deep );
366 This clones an XML::GDOME node to an XML::LibXML node explicitly.
368 export_GDOME
370 $gdomenode = XML::LibXML->export_GDOME( $node, $deep );
371 Allows one to clone an XML::LibXML node into an XML::GDOME node.
373
375 For bug reports, please use the CPAN request tracker on
376 http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXML
377 For suggestions etc., and other issues related to XML::LibXML you may
379 use the perl XML mailing list ("perl-xml@listserv.ActiveState.com"),
380 where most XML-related Perl modules are discussed. In case of problems
381 you should check the archives of that list first. Many problems are
382 already discussed there. You can find the list's archives and
383 subscription options at
384 <http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/perl-xml>.
385
387 Matt Sergeant, Christian Glahn, Petr Pajas
388
390 2.0132
391
393 2001-2007, AxKit.com Ltd.
394 2002-2006, Christian Glahn.
396 2006-2009, Petr Pajas.
398
400 This program is free software; you can redistribute it and/or modify it
401 under the same terms as Perl itself.
402perl v5.28.0 2017-10-28 LibXML(3)