This document is a Mac OS X manual page. Manual pages are a command-line technology for providing documentation. You can view these manual pages locally using the man(1) command. These manual pages come from many different sources, and thus, have a variety of writing styles.

For more information about the manual page format, see the manual page for manpages(5).

XML::LibXML::DOM(3)                  User Contributed Perl Documentation                 XML::LibXML::DOM(3)



NAME
       XML::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 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 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 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 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.

       More recent versions of perl (e.g. 5.6.1 or higher) support special flags to disinguish between UTF-8
       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 UTF-8 all strings that are not
       already in UTF-8 are implicitly encoded from the document encoding to UTF-8. On output these strings
       are commonly returned as UTF-8 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 UTF-8 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 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 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
       setAttributeNode() but setAttributeNodeNS().

AUTHORS
       Matt Sergeant, Christian Glahn, Petr Pajas,

VERSION
       1.60

COPYRIGHT
       2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas, All rights reserved.



perl v5.8.8                                      2006-08-26                              XML::LibXML::DOM(3)