=head1 NAME

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

=head1 DESCRIPTION




XML::LibXML provides an lightwight interface to B<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 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 B<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. More 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 rather strict. This means
the interface 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 singular interface
that is conform 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 B<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)
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 functions.





B<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.





B<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 implicitly by
using XML::LibXML::Document's createElementNS() 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 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 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 B<never> use
setAttributeNode() but setAttributeNodeNS().




=head1 AUTHOR

Matt Sergeant, Christian Glahn

=head1 SEE ALSO

XML::LibXML::Document, XML::LibXML::Element, XML::LibXML::Node, XML::LibXML::Text, XML::LibXML::Comment, XML::LibXML::CDATASection, XML::LibXML::Attr, XML::LibXML::DocumentFragment

=head1 VERSION

1.53

