dom(3)

NAME

XML::LibXML::DOM - XML::LibXML DOM implementation

DESCRIPTION

XML::LibXML provides an lightwight interface to modify
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 func
tions 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 imple
ment a full DOM interface as it is done by XML::GDOME and
used for full featured application. More it offers an sim
ple 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 rather strict. This means the inter
face functions are names as the DOM specification says and
not what widespread Java interfaces claim to be standard.
Although there are several functions that have only a sin
gular interface that is conform to the DOM spec
XML::LibXML provides an additional Java style alias inter
face.

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 the
official functions.

More recent versions of perl (e.g. 5.6.1 or higher) sup
port special flags to disinguish between UTF8 and so
called binary data. XML::LibXML provides for these ver
sions 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 functions.

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 causing 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 distribution.

Namespaces and XML::LibXML's DOM implementation

XML::LibXML's DOM implementation follows the DOM implemen
tation 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 implicitly by using XML::LibXML::Document's cre_
ateElementNS() or createAttributeNS() function. If the a namespace is not declared on the documentElement, the
namespace will be localy declared for the newly created
node. In case of Attributes this may look a bit confus
ing, 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 the following document:: <?xml version="1.0"?>
<foo xmlns:bar="bar" bar:foo="test"/>
Note that the namespace is declared on the document ele ment 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 setAttributeNode() but setAttributeN_ odeNS().

AUTHOR

Matt Sergeant, Christian Glahn

docs.sk

comprehensive documentation repository

In section

dom(3)

NAME

DESCRIPTION

AUTHOR

SEE ALSO

VERSION