XML::LibXML::DOM(3) User Contributed Perl Documentation XML::LibXML::DOM(3)NAMEXML::LibXML::DOM - XML::LibXML DOM Implementation
DESCRIPTION
XML::LibXML provides an lightwight interface to modify a node of the
document tree generated by the XML::LibXML parser. This interface fol‐
lows as far as possible the DOM Level 3 specification. Additionally to
the specified functions the XML::LibXML supports some functions that
are more handy to use in the perl environment.
One also has to remember, that XML::LibXML is an interface to libxml2
nodes which actually reside on the C-Level of XML::LibXML. This means
each node is a reference to a structure different than a perl hash or
array. The only way to access these structure's values is through the
DOM interface provided by XML::LibXML. This also means, that one can't
simply inherit a XML::LibXML node and add new member variables as they
were hash keys.
The DOM interface of XML::LibXML does not intend to implement a full
DOM interface as it is done by XML::GDOME and used for full featured
application. Moreover, it offers an simple way to build or modify doc‐
uments that are created by XML::LibXML's parser.
Another target of the XML::LibXML interface is to make the interfaces
of libxml2 available to the perl community. This includes also some
workarounds to some features where libxml2 assumes more control over
the C-Level that most perl users don't have.
One of the most important parts of the XML::LibXML DOM interface is,
that the interfaces try do follow the DOM Level 3 specification rather
strictly. This means the interface functions are named as the DOM spec‐
ification says and not what widespread Java interfaces claim to be
standard. Although there are several functions that have only a singu‐
lar interface that conforms to the DOM spec XML::LibXML provides an
additional Java style alias interface.
Also there are some function interfaces left over from early stages of
XML::LibXML for compatibility reasons. These interfaces are for compat‐
ibility reasons only. They might disappear in one of the future ver‐
sions of XML::LibXML, so a user is requested to switch over to the
official functions.
More recent versions of perl (e.g. 5.6.1 or higher) support special
flags to disinguish between UTF8 and so called binary data. XML::LibXML
provides for these versions functionality to make efficient use of
these flags: If a document has set an encoding other than UTF8 all
strings that are not already in UTF8 are implicitly encoded from the
document encoding to UTF8. On output these strings are commonly
returned as UTF8 unless a user does request explicitly the original
(aka. document) encoding.
Older version of perl (such as 5.00503 or less) do not support these
flags. If XML::LibXML is build for these versions, all strings have to
get encoded to UTF8 manualy before they are passed to any DOM func‐
tions.
NOTE: XML::LibXML's magic encoding may not work on all plattforms. Some
platforms are known to have a broken iconv(), which is partly used by
libxml2. 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. If your document gets parsed with out caus‐
ing any segmentation faults, bus errors or whatever your OS throws. An
example for such a test can be found in test 19encoding.t of the dis‐
tribution.
Namespaces and XML::LibXML's DOM implementation
XML::LibXML's DOM implementation follows the DOM implementation of
libxml2. This is important to know if namespaces are used. Namespaces
cannot be declared on an document node. This is basicly because XPath
doesn't know about document nodes. Therefore namespaces have to be
declared on element nodes. This can happen explicitly by using
XML::LibXML:Element's setNamespace() function or more or less implic‐
itly by using XML::LibXML::Document's createElementNS() or createAt‐
tributeNS() function. If the a namespace is not declared on the docu‐
mentElement, the namespace will be localy declared for the newly cre‐
ated node. In case of Attributes this may look a bit confusing, since
these nodes cannot have namespace declarations itself. In this case the
namespace in internally applied to the attribute and later declared on
the node the attribute is appended to.
The following example may explain this a bit:
my $doc = XML::LibXML->createDocument;
my $root = $doc->createElementNS( "", "foo" );
$doc->setDocumentElement( $root );
my $attr = $doc->createAttributeNS( "bar", "bar:foo", "test" );
$root->setAttributeNodeNS( $attr );
This piece of code will result in the following document:
<?xml version="1.0"?>
<foo xmlns:bar="bar" bar:foo="test"/>
Note that the namespace is declared on the document element while the
setAttributeNodeNS() call.
Here it is important to repeat the specification: While working with
namespaces you should use the namespace aware functions instead of the
simplified versions. For example you should never use setAttributeN‐
ode() but setAttributeNodeNS().
AUTHORS
Matt Sergeant, Christian Glahn, =head1 VERSION
1.58
COPYRIGHT
2001-2004, AxKit.com Ltd; 2002-2004 Christian Glahn, All rights
reserved.
perl v5.8.8 2003-11-07 XML::LibXML::DOM(3)
