1XML::LibXML::DOM(3)   User Contributed Perl Documentation  XML::LibXML::DOM(3)
2
3
4

NAME

6       XML::LibXML::DOM - XML::LibXML DOM Implementation
7

DESCRIPTION

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

AUTHORS

129       Matt Sergeant, Christian Glahn, Petr Pajas
130

VERSION

132       2.0208
133
135       2001-2007, AxKit.com Ltd.
136
137       2002-2006, Christian Glahn.
138
139       2006-2009, Petr Pajas.
140

LICENSE

142       This program is free software; you can redistribute it and/or modify it
143       under the same terms as Perl itself.
144
145
146
147perl v5.36.0                      2022-09-30               XML::LibXML::DOM(3)
Impressum