NAME¶
XML::LibXML::DOM - XML::LibXML DOM Implementation
DESCRIPTION¶
XML::LibXML provides an light-wight interface to
modify a node of the
document tree generated by the XML::LibXML parser. This interface follows 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 an
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 documents 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
(<
http://www.w3.org/TR/DOM-Level-3-Core/>) rather strictly. This means
the interface functions are named as the DOM specification says and not what
widespread Java interfaces claim to be standard. Although there are several
functions that have only a singular 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 compatibility
reasons
only. They might disappear in one of the future versions of
XML::LibXML, so a user is requested to switch over to the official functions.
Encodings and XML::LibXML's DOM implementation¶
See the section on Encodings in the
XML::LibXML manual page.
Namespaces and XML::LibXML's DOM implementation¶
XML::LibXML's DOM implementation is limited by the DOM implementation of libxml2
which treats namespaces slightly differently than required by the DOM Level 2
specification.
According to the DOM Level 2 specification, namespaces of elements and
attributes should be persistent, and nodes should be permanently bound to
namespace URIs as they get created; it should be possible to manipulate the
special attributes used for declaring XML namespaces just as other attributes
without affecting the namespaces of other nodes. In DOM Level 2, the
application is responsible for creating the special attributes consistently
and/or for correct serialization of the document.
This is both inconvenient, causes problems in serialization of DOM to XML, and
most importantly, seems almost impossible to implement over libxml2.
In libxml2, namespace URI and prefix of a node is provided by a pointer to a
namespace declaration (appearing as a special xmlns attribute in the XML
document). If the prefix or namespace URI of the declaration changes, the
prefix and namespace URI of all nodes that point to it changes as well.
Moreover, in contrast to DOM, a node (element or attribute) can only be bound
to a namespace URI if there is some namespace declaration in the document to
point to.
Therefore current DOM implementation in XML::LibXML tries to treat namespace
declarations in a compromise between reason, common sense, limitations of
libxml2, and the DOM Level 2 specification.
In XML::LibXML, special attributes declaring XML namespaces are often created
automatically, usually when a namespaced node is attached to a document and no
existing declaration of the namespace and prefix is in the scope to be reused.
In this respect, XML::LibXML DOM implementation differs from the DOM Level 2
specification according to which special attributes for declaring the
appropriate XML namespaces should not be added when a node with a namespace
prefix and namespace URI is created.
Namespace declarations are also created when XML::LibXML::Document's
createElementNS() or
createAttributeNS() function are used. If
the a namespace is not declared on the documentElement, the namespace will be
locally declared for the newly created node. In case of Attributes this may
look a bit confusing, since these nodes cannot have namespace declarations
itself. In this case the namespace is internally applied to the attribute and
later declared on the node the attribute is appended to (if required).
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"/>
The namespace is declared on the document element during the
setAttributeNodeNS() call.
Namespaces can be also declared explicitly by the use of XML::LibXML::Element's
setNamespace() function. Since 1.61, they can also be manipulated with
functions
setNamespaceDeclPrefix() and
setNamespaceDeclURI()
(not available in DOM). Changing an URI or prefix of an existing namespace
declaration affects the namespace URI and prefix of all nodes which point to
it (that is the nodes in its scope).
It is also 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
setAttribute() but
setAttributeNS().
AUTHORS¶
Matt Sergeant, Christian Glahn, Petr Pajas
VERSION¶
2.0116
COPYRIGHT¶
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
LICENSE¶
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.