On Apache
Under GNU General Public License
2012-05-25 10:52 @38.107.179.239 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)
LibXML(3pm) User Contributed Perl Documentation LibXML(3pm)
NAME
XML::LibXML - Perl Binding for libxml2
SYNOPSIS
use XML::LibXML;
my $parser = XML::LibXML->new();
my $doc = $parser->parse_string(<<'EOT');
<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 );
DESCRIPTION
This module is an interface to libxml2, providing XML and HTML parsers with DOM, SAX and
XMLReader interfaces, a large subset of DOM Layer 3 interface and a XML::XPath-like
interface to XPath API of libxml2. The module is split into several packages which are not
described in this section; unless stated otherwise, you only need to "use XML::LibXML;" in
your programs.
For further information, please check the following documentation:
Parsing XML Files with XML::LibXML
XML::LibXML DOM Implementation
XML::LibXML direct SAX parser
Reading XML with a pull-parser
XML::LibXML DOM Document Class
Abstract Base Class of XML::LibXML Nodes
XML::LibXML Class for Element Nodes
XML::LibXML Class for Text Nodes
XML::LibXML Comment Nodes
XML::LibXML Class for CDATA Sections
XML::LibXML Attribute Class
XML::LibXML's DOM L2 Document Fragment Implementation
XML::LibXML Namespace Implementation
XML::LibXML Processing Instructions
XML::LibXML DTD Support
XML::LibXML frontend for RelaxNG schema validation
XML::LibXML frontend for W3C Schema schema validation
API for evaluating XPath expressions with enhanced support for the evaluation context
ENCODINGS SUPPORT IN XML::LIBXML
Recall that since version 5.6.1, Perl distinguishes between character strings (internally
encoded in UTF-8) 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 (UTF8). Please refer to perlunicode for details.
XML::LibXML's API is designed to deal with many encodings of XML documents completely
transparently, so that the application using XML::LibXML can be completely ignorant about
the encoding of the XML documents it works with. On the other hand, functions like
"XML::LibXML::Document->setEncoding" give the user control over the document encoding.
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. UTF-8
encoded with the UTF8 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 XML documents.
Below we summarize basic rules and principles regarding encoding:
1. Do NOT apply any encoding-related PerlIO layers (":utf8" or ":encoding(...)") to file
handles that are an imput for the parses or an ouptut for a serializer of (full) XML
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 "<?xml version="1.0" encoding="..."?>" declaration. Here is
an example to follow:
use XML::LibXML;
my $parser = XML::LibXML->new;
open my $fh, "file.xml";
binmode $fh; # drop all PerlIO layers possibly created by a use open pragma
$doc = $parser->parse_fh($fh);
open my $out, "out.xml";
binmode $fh; # as above
$doc->toFh($fh);
# or
print $fh $doc->toString();
2. All functions working with DOM accept and return character strings (UTF-8 encoded with
UTF8 flag on). E.g.
my $doc = XML::LibXML:Document->new('1.0',$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
where $some_encoding is the document encoding that will be used when saving the
document, and $name and $text contain character strings (UTF-8 encoded with UTF8 flag
on). Note that the method "toString" returns XML as a character string if applied to
other node than the Document node and a byte string containing the apropriate
<?xml version="1.0" encoding="..."?>
declaration if appliled to a XML::LibXML DOM Document Class.
3. DOM methods also accept binary strings in the original encoding of the document to
which the node belongs (UTF-8 is assumed if the node is not attached to any document).
Exploiting this feature is NOT RECOMMENDED since it is considered a bad practice.
my $doc = XML::LibXML:Document->new('1.0','iso-8859-2');
my $text = $doc->createTextNode($some_latin2_encoded_byte_string);
# WORKS, BUT NOT RECOMMENDED!
NOTE: 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.
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.
XML::LibXML::LIBXML_DOTTED_VERSION
$Version_String = XML::LibXML::LIBXML_DOTTED_VERSION;
Returns the version string of the libxml2 version XML::LibXML was compiled for. This
will be "2.6.2" for "libxml2 2.6.2".
XML::LibXML::LIBXML_VERSION
$Version_ID = XML::LibXML::LIBXML_VERSION;
Returns the version id of the libxml2 version XML::LibXML was compiled for. This will
be "20602" for "libxml2 2.6.2". Don't mix this version id with $XML::LibXML::VERSION.
The latter contains the version of XML::LibXML itself while the first contains the
version of libxml2 XML::LibXML was compiled for.
XML::LibXML::LIBXML_RUNTIME_VERSION
$DLL_Version = XML::LibXML::LIBXML_RUNTIME_VERSION;
Returns a version string of the libxml2 which is (usually dynamically) linked by
XML::LibXML. This will be "20602" for libxml2 released as "2.6.2" and something like
"20602-CVS2032" for a CVS build of libxml2.
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.
EXPORTS
By default the module exports all constants and functions listed in the :all tag,
described below.
EXPORT TAGS
:all
Includes the tags ":libxml", ":encoding", and ":ns" described below.
:libxml
Exports integer constants for DOM node types (defined in a separately distributed
XML::LibXML::Common module).
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
:encoding
Exports two encoding conversion functions from the (separate) module
XML::LibXML::Common.
encodeToUTF8()
decodeFromUTF8()
:libxml
Exports two convenience constants: the implicit namespace of the reserved "xml:"
prefix, and the implicit namespace for the reserved "xmlns:" prefix.
XML_XML_NS => 'http://www.w3.org/XML/1998/namespace'
XML_XMLNS_NS => 'http://www.w3.org/2000/xmlns/'
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.
XML::LibXSLT
XSLT 1.0 Processor using libxslt and XML::LibXML
XML::LibXML::Common
Common functions for XML::LibXML related Classes
XML::LibXML::Iterator
XML::LibXML Implementation of the DOM Traversal Specification
XML::LIBXML AND XML::GDOME
Note: THE FUNCTIONS DESCRIBED HERE ARE STILL EXPERIMENTAL
Although both modules make use of libxml2's XML capabilities, the DOM implementation of
both modules are not compatible. But still it is possible to exchange nodes from one DOM
to the other. The concept of this exchange is pretty similar to the function cloneNode():
The particular node is copied on the low-level to the opposite DOM implementation.
Since the DOM 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.
XML::LibXML provides two functions to export or import GDOME nodes: import_GDOME() and
export_GDOME(). Both function have two parameters: the node and a flag for recursive
import. The flag works as in cloneNode().
The two functions allow to export and import XML::GDOME nodes explicitly, however,
XML::LibXML allows also the transparent import of XML::GDOME nodes in functions such as
appendChild(), insertAfter() and so on. While native nodes are automatically adopted in
most functions XML::GDOME 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.
import_GDOME
$libxmlnode = XML::LibXML->import_GDOME( $node, $deep );
This clones an XML::GDOME node to a XML::LibXML node explicitly.
export_GDOME
$gdomenode = XML::LibXML->export_GDOME( $node, $deep );
Allows to clone an XML::LibXML node into a XML::GDOME node.
CONTACTS
For bug reports, please use the CPAN request tracker on
http://rt.cpan.org/NoAuth/Bugs.html?Dist=XML-LibXML
For suggestions etc., and other issues related to XML::LibXML you may use the perl XML
mailing list ("perl-xml AT listserv.com"), 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|http://aspn.activestate.com/ASPN/Mail/Browse/Threaded/perl-xml>.
AUTHORS
Matt Sergeant, Christian Glahn, Petr Pajas
VERSION
1.66
COPYRIGHT
2001-2007, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006-2008 Petr Pajas, All rights
reserved.
perl v5.10.0 2008-01-29 LibXML(3pm)
Generated by $Id: phpMan.php,v 4.49 2006/02/26 13:18:18 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2012-05-25 10:52 @38.107.179.239 Crawled by CCBot/1.0 (+http://www.commoncrawl.org/bot.html)