.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "LibXML 3pm"
.TH LibXML 3pm "2017-10-29" "perl v5.26.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::LibXML \- Perl Binding for libxml2
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&  use XML::LibXML;
\&  my $dom = XML::LibXML\->load_xml(string => <<\*(AqEOT\*(Aq);
\&  <some\-xml/>
\&  EOT
\&
\&  $Version_String = XML::LibXML::LIBXML_DOTTED_VERSION;
\&  $Version_ID = XML::LibXML::LIBXML_VERSION;
\&  $DLL_Version = XML::LibXML::LIBXML_RUNTIME_VERSION;
\&  $libxmlnode = XML::LibXML\->import_GDOME( $node, $deep );
\&  $gdomenode = XML::LibXML\->export_GDOME( $node, $deep );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module is an interface to libxml2, providing \s-1XML\s0 and \s-1HTML\s0 parsers with
\&\s-1DOM, SAX\s0 and XMLReader interfaces, a large subset of \s-1DOM\s0 Layer 3 interface and
a XML::XPath\-like interface to XPath \s-1API\s0 of libxml2. The module is split into
several packages which are not described in this section; unless stated
otherwise, you only need to \f(CW\*(C`use XML::LibXML;\*(C'\fR in your programs.
.PP
For further information, please check the following documentation:
.IP "XML::LibXML::Parser" 4
.IX Item "XML::LibXML::Parser"
Parsing \s-1XML\s0 files with XML::LibXML
.IP "XML::LibXML::DOM" 4
.IX Item "XML::LibXML::DOM"
XML::LibXML Document Object Model (\s-1DOM\s0) Implementation
.IP "XML::LibXML::SAX" 4
.IX Item "XML::LibXML::SAX"
XML::LibXML direct \s-1SAX\s0 parser
.IP "XML::LibXML::Reader" 4
.IX Item "XML::LibXML::Reader"
Reading \s-1XML\s0 with a pull-parser
.IP "XML::LibXML::Dtd" 4
.IX Item "XML::LibXML::Dtd"
XML::LibXML frontend for \s-1DTD\s0 validation
.IP "XML::LibXML::RelaxNG" 4
.IX Item "XML::LibXML::RelaxNG"
XML::LibXML frontend for RelaxNG schema validation
.IP "XML::LibXML::Schema" 4
.IX Item "XML::LibXML::Schema"
XML::LibXML frontend for W3C Schema schema validation
.IP "XML::LibXML::XPathContext" 4
.IX Item "XML::LibXML::XPathContext"
\&\s-1API\s0 for evaluating XPath expressions with enhanced support for the evaluation
context
.IP "XML::LibXML::InputCallback" 4
.IX Item "XML::LibXML::InputCallback"
Implementing custom \s-1URI\s0 Resolver and input callbacks
.IP "XML::LibXML::Common" 4
.IX Item "XML::LibXML::Common"
Common functions for XML::LibXML related Classes
.PP
The nodes in the Document Object Model (\s-1DOM\s0) are represented by the following
classes (most of which \*(L"inherit\*(R" from XML::LibXML::Node):
.IP "XML::LibXML::Document" 4
.IX Item "XML::LibXML::Document"
XML::LibXML class for \s-1DOM\s0 document nodes
.IP "XML::LibXML::Node" 4
.IX Item "XML::LibXML::Node"
Abstract base class for XML::LibXML \s-1DOM\s0 nodes
.IP "XML::LibXML::Element" 4
.IX Item "XML::LibXML::Element"
XML::LibXML class for \s-1DOM\s0 element nodes
.IP "XML::LibXML::Text" 4
.IX Item "XML::LibXML::Text"
XML::LibXML class for \s-1DOM\s0 text nodes
.IP "XML::LibXML::Comment" 4
.IX Item "XML::LibXML::Comment"
XML::LibXML class for comment \s-1DOM\s0 nodes
.IP "XML::LibXML::CDATASection" 4
.IX Item "XML::LibXML::CDATASection"
XML::LibXML class for \s-1DOM CDATA\s0 sections
.IP "XML::LibXML::Attr" 4
.IX Item "XML::LibXML::Attr"
XML::LibXML \s-1DOM\s0 attribute class
.IP "XML::LibXML::DocumentFragment" 4
.IX Item "XML::LibXML::DocumentFragment"
XML::LibXML's \s-1DOM L2\s0 Document Fragment implementation
.IP "XML::LibXML::Namespace" 4
.IX Item "XML::LibXML::Namespace"
XML::LibXML \s-1DOM\s0 namespace nodes
.IP "XML::LibXML::PI" 4
.IX Item "XML::LibXML::PI"
XML::LibXML \s-1DOM\s0 processing instruction nodes
.SH "ENCODINGS SUPPORT IN XML::LIBXML"
.IX Header "ENCODINGS SUPPORT IN XML::LIBXML"
Recall that since version 5.6.1, Perl distinguishes between character strings
(internally encoded in \s-1UTF\-8\s0) and so called binary data and, accordingly,
applies either character or byte semantics to them. A scalar representing a
character string is distinguished from a byte string by special flag (\s-1UTF8\s0).
Please refer to \fIperlunicode\fR for details.
.PP
XML::LibXML's \s-1API\s0 is designed to deal with many encodings of \s-1XML\s0 documents
completely transparently, so that the application using XML::LibXML can be
completely ignorant about the encoding of the \s-1XML\s0 documents it works with. On
the other hand, functions like \f(CW\*(C`XML::LibXML::Document\->setEncoding\*(C'\fR give the user control over the document encoding.
.PP
To ensure the aforementioned transparency and uniformity, most functions of
XML::LibXML that work with in-memory trees accept and return data as character
strings (i.e. \s-1UTF\-8\s0 encoded with the \s-1UTF8\s0 flag on) regardless of the original
document encoding; however, the functions related to I/O operations (i.e.
parsing and saving) operate with binary data (in the original document
encoding) obeying the encoding declaration of the \s-1XML\s0 documents.
.PP
Below we summarize basic rules and principles regarding encoding:
.IP "1." 4
Do \s-1NOT\s0 apply any encoding-related PerlIO layers (\f(CW\*(C`:utf8\*(C'\fR or \f(CW\*(C`:encoding(...)\*(C'\fR) to file handles that are an input for the parses or an output for a
serializer of (full) \s-1XML\s0 documents. This is because the conversion of the data
to/from the internal character representation is provided by libxml2 itself
which must be able to enforce the encoding specified by the \f(CW\*(C`<?xml version="1.0" encoding="..."?>\*(C'\fR declaration. Here is an example to follow:
.Sp
.Vb 5
\&  use XML::LibXML;
\&  # load
\&  open my $fh, \*(Aq<\*(Aq, \*(Aqfile.xml\*(Aq;
\&  binmode $fh; # drop all PerlIO layers possibly created by a use open pragma
\&  $doc = XML::LibXML\->load_xml(IO => $fh);
\&
\&  # save
\&  open my $out, \*(Aq>\*(Aq, \*(Aqout.xml\*(Aq;
\&  binmode $out; # as above
\&  $doc\->toFH($out);
\&  # or
\&  print {$out} $doc\->toString();
.Ve
.IP "2." 4
All functions working with \s-1DOM\s0 accept and return character strings (\s-1UTF\-8\s0
encoded with \s-1UTF8\s0 flag on). E.g.
.Sp
.Vb 5
\&  my $doc = XML::LibXML::Document\->new(\*(Aq1.0\*(Aq,$some_encoding);
\&  my $element = $doc\->createElement($name);
\&  $element\->appendText($text);
\&  $xml_fragment = $element\->toString(); # returns a character string
\&  $xml_document = $doc\->toString(); # returns a byte string
.Ve
.Sp
where \f(CW$some_encoding\fR is the document encoding that will be used when saving the document, and \f(CW$name\fR and \f(CW$text\fR contain character strings (\s-1UTF\-8\s0 encoded with \s-1UTF8\s0 flag on). Note that the
method \f(CW\*(C`toString\*(C'\fR returns \s-1XML\s0 as a character string if applied to other node than the Document
node and a byte string containing the appropriate
.Sp
.Vb 1
\&  <?xml version="1.0" encoding="..."?>
.Ve
.Sp
declaration if applied to a XML::LibXML::Document.
.IP "3." 4
\&\s-1DOM\s0 methods also accept binary strings in the original encoding of the document
to which the node belongs (\s-1UTF\-8\s0 is assumed if the node is not attached to any
document). Exploiting this feature is \s-1NOT RECOMMENDED\s0 since it is considered
bad practice.
.Sp
.Vb 3
\&  my $doc = XML::LibXML::Document\->new(\*(Aq1.0\*(Aq,\*(Aqiso\-8859\-2\*(Aq);
\&  my $text = $doc\->createTextNode($some_latin2_encoded_byte_string);
\&  # WORKS, BUT NOT RECOMMENDED!
.Ve
.PP
\&\fI\s-1NOTE:\s0\fR libxml2 support for many encodings is based on the iconv library. The actual
list of supported encodings may vary from platform to platform. To test if your
platform works correctly with your language encoding, build a simple document
in the particular encoding and try to parse it with XML::LibXML to see if the
parser produces any errors. Occasional crashes were reported on rare platforms
that ship with a broken version of iconv.
.SH "THREAD SUPPORT"
.IX Header "THREAD SUPPORT"
XML::LibXML since 1.67 partially supports Perl threads in Perl >= 5.8.8.
XML::LibXML can be used with threads in two ways:
.PP
By default, all XML::LibXML classes use \s-1CLONE_SKIP\s0 class method to prevent Perl
from copying XML::LibXML::* objects when a new thread is spawn. In this mode,
all XML::LibXML::* objects are thread specific. This is the safest way to work
with XML::LibXML in threads.
.PP
Alternatively, one may use
.PP
.Vb 2
\&  use threads;
\&  use XML::LibXML qw(:threads_shared);
.Ve
.PP
to indicate, that all XML::LibXML node and parser objects should be shared
between the main thread and any thread spawn from there. For example, in
.PP
.Vb 6
\&  my $doc = XML::LibXML\->load_xml(location => $filename);
\&  my $thr = threads\->new(sub{
\&    # code working with $doc
\&    1;
\&  });
\&  $thr\->join;
.Ve
.PP
the variable \f(CW$doc\fR refers to the exact same XML::LibXML::Document in the spawned thread as in the
main thread.
.PP
Without using mutex locks, parallel threads may read the same document (i.e.
any node that belongs to the document), parse files, and modify different
documents.
.PP
However, if there is a chance that some of the threads will attempt to modify a
document (or even create new nodes based on that document, e.g. with \f(CW\*(C`$doc\->createElement\*(C'\fR) that other threads may be reading at the same time, the user is responsible
for creating a mutex lock and using it in \fIboth\fR in the thread that modifies and the thread that reads:
.PP
.Vb 10
\&  my $doc = XML::LibXML\->load_xml(location => $filename);
\&  my $mutex : shared;
\&  my $thr = threads\->new(sub{
\&     lock $mutex;
\&     my $el = $doc\->createElement(\*(Aqfoo\*(Aq);
\&     # ...
\&    1;
\&  });
\&  {
\&    lock $mutex;
\&    my $root = $doc\->documentElement;
\&    say $root\->name;
\&  }
\&  $thr\->join;
.Ve
.PP
Note that libxml2 uses dictionaries to store short strings and these
dictionaries are kept on a document node. Without mutex locks, it could happen
in the previous example that the thread modifies the dictionary while other
threads attempt to read from it, which could easily lead to a crash.
.SH "VERSION INFORMATION"
.IX Header "VERSION INFORMATION"
Sometimes it is useful to figure out, for which version XML::LibXML was
compiled for. In most cases this is for debugging or to check if a given
installation meets all functionality for the package. The functions
XML::LibXML::LIBXML_DOTTED_VERSION and XML::LibXML::LIBXML_VERSION provide this
version information. Both functions simply pass through the values of the
similar named macros of libxml2. Similarly, XML::LibXML::LIBXML_RUNTIME_VERSION
returns the version of the (usually dynamically) linked libxml2.
.IP "XML::LibXML::LIBXML_DOTTED_VERSION" 4
.IX Item "XML::LibXML::LIBXML_DOTTED_VERSION"
.Vb 1
\&  $Version_String = XML::LibXML::LIBXML_DOTTED_VERSION;
.Ve
.Sp
Returns the version string of the libxml2 version XML::LibXML was compiled for.
This will be \*(L"2.6.2\*(R" for \*(L"libxml2 2.6.2\*(R".
.IP "XML::LibXML::LIBXML_VERSION" 4
.IX Item "XML::LibXML::LIBXML_VERSION"
.Vb 1
\&  $Version_ID = XML::LibXML::LIBXML_VERSION;
.Ve
.Sp
Returns the version id of the libxml2 version XML::LibXML was compiled for.
This will be \*(L"20602\*(R" for \*(L"libxml2 2.6.2\*(R". Don't mix this version id with
\&\f(CW$XML::LibXML::VERSION\fR. The latter contains the version of XML::LibXML itself
while the first contains the version of libxml2 XML::LibXML was compiled for.
.IP "XML::LibXML::LIBXML_RUNTIME_VERSION" 4
.IX Item "XML::LibXML::LIBXML_RUNTIME_VERSION"
.Vb 1
\&  $DLL_Version = XML::LibXML::LIBXML_RUNTIME_VERSION;
.Ve
.Sp
Returns a version string of the libxml2 which is (usually dynamically) linked
by XML::LibXML. This will be \*(L"20602\*(R" for libxml2 released as \*(L"2.6.2\*(R" and
something like \*(L"20602\-CVS2032\*(R" for a \s-1CVS\s0 build of libxml2.
.Sp
XML::LibXML issues a warning if the version of libxml2 dynamically linked to it
is less than the version of libxml2 which it was compiled against.
.SH "EXPORTS"
.IX Header "EXPORTS"
By default the module exports all constants and functions listed in the :all
tag, described below.
.SH "EXPORT TAGS"
.IX Header "EXPORT TAGS"
.ie n .IP """:all""" 4
.el .IP "\f(CW:all\fR" 4
.IX Item ":all"
Includes the tags \f(CW\*(C`:libxml\*(C'\fR, \f(CW\*(C`:encoding\*(C'\fR, and \f(CW\*(C`:ns\*(C'\fR described below.
.ie n .IP """:libxml""" 4
.el .IP "\f(CW:libxml\fR" 4
.IX Item ":libxml"
Exports integer constants for \s-1DOM\s0 node types.
.Sp
.Vb 10
\&  XML_ELEMENT_NODE            => 1
\&  XML_ATTRIBUTE_NODE          => 2
\&  XML_TEXT_NODE               => 3
\&  XML_CDATA_SECTION_NODE      => 4
\&  XML_ENTITY_REF_NODE         => 5
\&  XML_ENTITY_NODE             => 6
\&  XML_PI_NODE                 => 7
\&  XML_COMMENT_NODE            => 8
\&  XML_DOCUMENT_NODE           => 9
\&  XML_DOCUMENT_TYPE_NODE      => 10
\&  XML_DOCUMENT_FRAG_NODE      => 11
\&  XML_NOTATION_NODE           => 12
\&  XML_HTML_DOCUMENT_NODE      => 13
\&  XML_DTD_NODE                => 14
\&  XML_ELEMENT_DECL            => 15
\&  XML_ATTRIBUTE_DECL          => 16
\&  XML_ENTITY_DECL             => 17
\&  XML_NAMESPACE_DECL          => 18
\&  XML_XINCLUDE_START          => 19
\&  XML_XINCLUDE_END            => 20
.Ve
.ie n .IP """:encoding""" 4
.el .IP "\f(CW:encoding\fR" 4
.IX Item ":encoding"
Exports two encoding conversion functions from XML::LibXML::Common.
.Sp
.Vb 2
\&  encodeToUTF8()
\&  decodeFromUTF8()
.Ve
.ie n .IP """:ns""" 4
.el .IP "\f(CW:ns\fR" 4
.IX Item ":ns"
Exports two convenience constants: the implicit namespace of the reserved \f(CW\*(C`xml:\*(C'\fR prefix, and the implicit namespace for the reserved \f(CW\*(C`xmlns:\*(C'\fR prefix.
.Sp
.Vb 2
\&  XML_XML_NS    => \*(Aqhttp://www.w3.org/XML/1998/namespace\*(Aq
\&  XML_XMLNS_NS  => \*(Aqhttp://www.w3.org/2000/xmlns/\*(Aq
.Ve
.SH "RELATED MODULES"
.IX Header "RELATED MODULES"
The modules described in this section are not part of the XML::LibXML package
itself. As they support some additional features, they are mentioned here.
.IP "XML::LibXSLT" 4
.IX Item "XML::LibXSLT"
\&\s-1XSLT 1.0\s0 Processor using libxslt and XML::LibXML
.IP "XML::LibXML::Iterator" 4
.IX Item "XML::LibXML::Iterator"
XML::LibXML Implementation of the \s-1DOM\s0 Traversal Specification
.IP "XML::CompactTree::XS" 4
.IX Item "XML::CompactTree::XS"
Uses XML::LibXML::Reader to very efficiently to parse \s-1XML\s0 document or element
into native Perl data structures, which are less flexible but significantly
faster to process then \s-1DOM.\s0
.SH "XML::LIBXML AND XML::GDOME"
.IX Header "XML::LIBXML AND XML::GDOME"
Note: \fI\s-1THE FUNCTIONS DESCRIBED HERE ARE STILL EXPERIMENTAL\s0\fR
.PP
Although both modules make use of libxml2's \s-1XML\s0 capabilities, the \s-1DOM\s0
implementation of both modules are not compatible. But still it is possible to
exchange nodes from one \s-1DOM\s0 to the other. The concept of this exchange is
pretty similar to the function \fIcloneNode()\fR: The particular node is copied on
the low-level to the opposite \s-1DOM\s0 implementation.
.PP
Since the \s-1DOM\s0 implementations cannot coexist within one document, one is forced
to copy each node that should be used. Because you are always keeping two nodes
this may cause quite an impact on a machines memory usage.
.PP
XML::LibXML provides two functions to export or import \s-1GDOME\s0 nodes:
\&\fIimport_GDOME()\fR and \fIexport_GDOME()\fR. Both function have two parameters: the node
and a flag for recursive import. The flag works as in \fIcloneNode()\fR.
.PP
The two functions allow one to export and import \s-1XML::GDOME\s0 nodes explicitly,
however, XML::LibXML also allows the transparent import of \s-1XML::GDOME\s0 nodes in
functions such as \fIappendChild()\fR, \fIinsertAfter()\fR and so on. While native nodes
are automatically adopted in most functions \s-1XML::GDOME\s0 nodes are always cloned
in advance. Thus if the original node is modified after the operation, the node
in the XML::LibXML document will not have this information.
.IP "import_GDOME" 4
.IX Item "import_GDOME"
.Vb 1
\&  $libxmlnode = XML::LibXML\->import_GDOME( $node, $deep );
.Ve
.Sp
This clones an \s-1XML::GDOME\s0 node to an XML::LibXML node explicitly.
.IP "export_GDOME" 4
.IX Item "export_GDOME"
.Vb 1
\&  $gdomenode = XML::LibXML\->export_GDOME( $node, $deep );
.Ve
.Sp
Allows one to clone an XML::LibXML node into an \s-1XML::GDOME\s0 node.
.SH "CONTACTS"
.IX Header "CONTACTS"
For bug reports, please use the \s-1CPAN\s0 request tracker on
http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML\-LibXML
.PP
For suggestions etc., and other issues related to XML::LibXML you may use the
perl \s-1XML\s0 mailing list (\f(CW\*(C`perl\-xml@listserv.ActiveState.com\*(C'\fR), where most XML-related Perl modules are discussed. In case of problems you
should check the archives of that list first. Many problems are already
discussed there. You can find the list's archives and subscription options at <http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/perl\-xml>.
.SH "AUTHORS"
.IX Header "AUTHORS"
Matt Sergeant,
Christian Glahn,
Petr Pajas
.SH "VERSION"
.IX Header "VERSION"
2.0128
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
2001\-2007, AxKit.com Ltd.
.PP
2002\-2006, Christian Glahn.
.PP
2006\-2009, Petr Pajas.
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.