local-lib5/lib/perl5/i486-linux-gnu-thread-multi/XML/LibXML/DOM.pod

   1 =head1 NAME
   2
   3 XML::LibXML::DOM - XML::LibXML DOM Implementation
   4
   5 =head1 DESCRIPTION
   6
   7 XML::LibXML provides an light-wight interface to I<<<<<< modify >>>>>> a node of the document tree generated by the XML::LibXML parser. This interface
   8 follows as far as possible the DOM Level 3 specification. Additionally to the
   9 specified functions the XML::LibXML supports some functions that are more handy
  10 to use in the perl environment.
  11
  12 One also has to remember, that XML::LibXML is an interface to libxml2 nodes
  13 which actually reside on the C-Level of XML::LibXML. This means each node is a
  14 reference to a structure different than a perl hash or array. The only way to
  15 access these structure's values is through the DOM interface provided by
  16 XML::LibXML. This also means, that one I<<<<<< can't >>>>>> simply inherit a XML::LibXML node and add new member variables as they were
  17 hash keys.
  18
  19 The DOM interface of XML::LibXML does not intend to implement a full DOM
  20 interface as it is done by XML::GDOME and used for full featured application.
  21 Moreover, it offers an simple way to build or modify documents that are created
  22 by XML::LibXML's parser.
  23
  24 Another target of the XML::LibXML interface is to make the interfaces of
  25 libxml2 available to the perl community. This includes also some workarounds to
  26 some features where libxml2 assumes more control over the C-Level that most
  27 perl users don't have.
  28
  29 One of the most important parts of the XML::LibXML DOM interface is, that the
  30 interfaces try do follow the DOM Level 3 specification (L<<<<<< http://www.w3.org/TR/DOM-Level-3-Core/ >>>>>>) rather strictly. This means the interface functions are named as the DOM
  31 specification says and not what widespread Java interfaces claim to be
  32 standard. Although there are several functions that have only a singular
  33 interface that conforms to the DOM spec XML::LibXML provides an additional Java
  34 style alias interface.
  35
  36 Also there are some function interfaces left over from early stages of
  37 XML::LibXML for compatibility reasons. These interfaces are for compatibility
  38 reasons I<<<<<< only >>>>>>. They might disappear in one of the future versions of XML::LibXML, so a user
  39 is requested to switch over to the official functions.
  40
  41
  42 =head2 Encodings and XML::LibXML's DOM implementation
  43
  44 See the section on Encodings in the I<<<<<< XML::LibXML >>>>>> manual page.
  45
  46
  47 =head2 Namespaces and XML::LibXML's DOM implementation
  48
  49 XML::LibXML's DOM implementation is limited by the DOM implementation of
  50 libxml2 which treats namespaces slightly differently than required by the DOM
  51 Level 2 specification.
  52
  53 According to the DOM Level 2 specification, namespaces of elements and
  54 attributes should be persistent, and nodes should be permanently bound to
  55 namespace URIs as they get created; it should be possible to manipulate the
  56 special attributes used for declaring XML namespaces just as other attributes
  57 without affecting the namespaces of other nodes. In DOM Level 2, the
  58 application is responsible for creating the special attributes consistently
  59 and/or for correct serialization of the document.
  60
  61 This is both inconvenient, causes problems in serialization of DOM to XML, and
  62 most importantly, seems almost impossible to implement over libxml2.
  63
  64 In libxml2, namespace URI and prefix of a node is provided by a pointer to a
  65 namespace declaration (appearing as a special xmlns attribute in the XML
  66 document). If the prefix or namespace URI of the declaration changes, the
  67 prefix and namespace URI of all nodes that point to it changes as well.
  68 Moreover, in contrast to DOM, a node (element or attribute) can only be bound
  69 to a namespace URI if there is some namespace declaration in the document to
  70 point to.
  71
  72 Therefore current DOM implementation in XML::LibXML tries to treat namespace
  73 declarations in a compromise between reason, common sense, limitations of
  74 libxml2, and the DOM Level 2 specification.
  75
  76 In XML::LibXML, special attributes declaring XML namespaces are often created
  77 automatically, usually when a namespaced node is attached to a document and no
  78 existing declaration of the namespace and prefix is in the scope to be reused.
  79 In this respect, XML::LibXML DOM implementation differs from the DOM Level 2
  80 specification according to which special attributes for declaring the
  81 apropriate XML namespaces should not be added when a node with a namespace
  82 prefix and namespace URI is created.
  83
  84 Namespace declarations are also created when L<<<<<< XML::LibXML::Document >>>>>>'s createElementNS() or createAttributeNS() function are used. If the a
  85 namespace is not declared on the documentElement, the namespace will be locally
  86 declared for the newly created node. In case of Attributes this may look a bit
  87 confusing, since these nodes cannot have namespace declarations itself. In this
  88 case the namespace is internally applied to the attribute and later declared on
  89 the node the attribute is appended to (if required).
  90
  91 The following example may explain this a bit:
  92
  93
  94
  95   my $doc = XML::LibXML->createDocument;
  96   my $root = $doc->createElementNS( "", "foo" );
  97   $doc->setDocumentElement( $root );
  98
  99   my $attr = $doc->createAttributeNS( "bar", "bar:foo", "test" );
 100   $root->setAttributeNodeNS( $attr );
 101
 102 This piece of code will result in the following document:
 103
 104
 105
 106   <?xml version="1.0"?>
 107   <foo xmlns:bar="bar" bar:foo="test"/>
 108
 109 The namespace is declared on the document element during the
 110 setAttributeNodeNS() call.
 111
 112 Namespaces can be also declared explicitly by the use of XML::LibXML:Element's
 113 setNamespace() function. Since 1.61, they can also be manipulated with
 114 functions setNamespaceDeclPrefix() and setNamespaceDeclURI() (not available in
 115 DOM). Changing an URI or prefix of an existing namespace declaration affects
 116 the namespace URI and prefix of all nodes which point to it (that is the nodes
 117 in its scope).
 118
 119 It is also important to repeat the specification: While working with namespaces
 120 you should use the namespace aware functions instead of the simplified
 121 versions. For example you should I<<<<<< never >>>>>> use setAttribute() but setAttributeNS().
 122
 123 =head1 AUTHORS
 124
 125 Matt Sergeant,
 126 Christian Glahn,
 127 Petr Pajas
 128
 129
 130 =head1 VERSION
 131
 132 1.70
 133
 134 =head1 COPYRIGHT
 135
 136 2001-2007, AxKit.com Ltd.
 137
 138 2002-2006, Christian Glahn.
 139
 140 2006-2009, Petr Pajas.
 141
 142 =cut