1XML::LibXML::DOM(3) User Contributed Perl Documentation XML::LibXML::DOM(3)
2
6 XML::LibXML::DOM - XML::LibXML DOM Implementation
7
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 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 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 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 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 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 Encodings and XML::LibXML's DOM implementation
49 See the section on Encodings in the XML::LibXML manual page.
50 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 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 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 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 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 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 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 The following example may explain this a bit:
100 my $doc = XML::LibXML->createDocument;
102 my $root = $doc->createElementNS( "", "foo" );
103 $doc->setDocumentElement( $root );
104 my $attr = $doc->createAttributeNS( "bar", "bar:foo", "test" );
106 $root->setAttributeNodeNS( $attr );
107 This piece of code will result in the following document:
109 <?xml version="1.0"?>
111 <foo xmlns:bar="bar" bar:foo="test"/>
112 The namespace is declared on the document element during the
114 setAttributeNodeNS() call.
115 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 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
129 Matt Sergeant, Christian Glahn, Petr Pajas
130
132 2.0207
133
135 2001-2007, AxKit.com Ltd.
136 2002-2006, Christian Glahn.
138 2006-2009, Petr Pajas.
140
142 This program is free software; you can redistribute it and/or modify it
143 under the same terms as Perl itself.
144perl v5.34.0 2021-07-23 XML::LibXML::DOM(3)