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 an lightwight interface to modify a node of the
10       document tree generated by the XML::LibXML parser. This interface fol‐
11       lows as far as possible the DOM Level 3 specification. Additionally to
12       the specified functions the 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 different than a perl hash or
18       array. The only way to access these structure's values is through the
19       DOM interface provided by XML::LibXML. This also means, that one can't
20       simply inherit a XML::LibXML node and add new member variables as they
21       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 doc‐
26       uments 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 do follow the DOM Level 3 specification rather
35       strictly. This means the interface functions are named as the DOM spec‐
36       ification says and not what widespread Java interfaces claim to be
37       standard. Although there are several functions that have only a singu‐
38       lar interface that conforms to the DOM spec XML::LibXML provides an
39       additional Java style alias interface.
40
41       Also there are some function interfaces left over from early stages of
42       XML::LibXML for compatibility reasons. These interfaces are for compat‐
43       ibility reasons only. They might disappear in one of the future ver‐
44       sions of XML::LibXML, so a user is requested to switch over to the
45       official functions.
46
47       More recent versions of perl (e.g. 5.6.1 or higher) support special
48       flags to disinguish between UTF-8 and so called binary data.
49       XML::LibXML provides for these versions functionality to make efficient
50       use of these flags: If a document has set an encoding other than UTF-8
51       all strings that are not already in UTF-8 are implicitly encoded from
52       the document encoding to UTF-8. On output these strings are commonly
53       returned as UTF-8 unless a user does request explicitly the original
54       (aka. document) encoding.
55
56       Older version of perl (such as 5.00503 or less) do not support these
57       flags. If XML::LibXML is build for these versions, all strings have to
58       get encoded to UTF-8 manualy before they are passed to any DOM func‐
59       tions.
60
61       NOTE: XML::LibXML's magic encoding may not work on all plattforms. Some
62       platforms are known to have a broken iconv(), which is partly used by
63       libxml2.  To test if your platform works correctly with your language
64       encoding, build a simple document in the particular encoding and try to
65       parse it with XML::LibXML. If your document gets parsed with out caus‐
66       ing any segmentation faults, bus errors or whatever your OS throws. An
67       example for such a test can be found in test 19encoding.t of the dis‐
68       tribution.
69
70       Namespaces and XML::LibXML's DOM implementation
71
72       XML::LibXML's DOM implementation is limitted by the DOM implementation
73       of libxml2 which treats namespaces slightly differently than required
74       by the DOM Level 2 specification.
75
76       According to the DOM Level 2 specification, namespaces of elements and
77       attributes should be persistent, and nodes should be permanently bound
78       to namespace URIs as they get created; it should be possible to manipu‐
79       late the special attributes used for declaring XML namespaces just as
80       other attributes without affecting the namespaces of other nodes. In
81       DOM Level 2, the application is responsible for creating the special
82       attributes consistently and/or for correct serialization of the docu‐
83       ment.
84
85       This is both unconvenient, causes problems in serialization of DOM to
86       XML, and most importantly, seems almost impossible to implement over
87       libxml2.
88
89       In libxml2, namespace URI and prefix of a node is provided by a pointer
90       to a namespace declaration (appearing as a special xmlns attribute in
91       the XML document). If the prefix or namespace URI of the declaration
92       changes, the prefix and namespace URI of all nodes that point to it
93       changes as well.  Moreover, in contrast to DOM, a node (element or
94       attribute) can only be bound to a namespace URI if there is some names‐
95       pace declaration in the document to point to.
96
97       Therefore current DOM implementation in XML::LibXML tries to treat
98       namespace declarations in a compromise between reason, common sense,
99       limitations of libxml2, and the DOM Level 2 specification.
100
101       In XML::LibXML, special attributes declaring XML namespaces are often
102       created automatically, usually when a namespaced node is attached to a
103       document and no existing declaration of the namespace and prefix is in
104       the scope to be reused.  In this respect, XML::LibXML DOM implementa‐
105       tion differs from the DOM Level 2 specification according to which spe‐
106       cial attributes for declaring the appropriate XML namespaces should not
107       be added when a node with a namespace prefix and namespace URI is cre‐
108       ated.
109
110       Namespace declarations are also created when XML::LibXML::Document's
111       createElementNS() or createAttributeNS() function are used. If the a
112       namespace is not declared on the documentElement, the namespace will be
113       localy declared for the newly created node. In case of Attributes this
114       may look a bit confusing, since these nodes cannot have namespace dec‐
115       larations itself. In this case the namespace is internally applied to
116       the attribute and later declared on the node the attribute is appended
117       to (if required).
118
119       The following example may explain this a bit:
120
121          my $doc = XML::LibXML->createDocument;
122          my $root = $doc->createElementNS( "", "foo" );
123          $doc->setDocumentElement( $root );
124
125          my $attr = $doc->createAttributeNS( "bar", "bar:foo", "test" );
126          $root->setAttributeNodeNS( $attr );
127
128       This piece of code will result in the following document:
129
130          <?xml version="1.0"?>
131          <foo xmlns:bar="bar" bar:foo="test"/>
132
133       The namespace is declared on the document element during the setAt‐
134       tributeNodeNS() call.
135
136       Namespaces can be also declared explicitly by the use of
137       XML::LibXML:Element's setNamespace() function. Since 1.61, they can
138       also be manipulated with functions setNamespaceDeclPrefix() and set‐
139       NamespaceDeclURI() (not available in DOM). Changing an URI or prefix of
140       an existing namespace declaration affects the namespace URI and prefix
141       of all nodes which point to it (that is the nodes in its scope).
142
143       It is also important to repeat the specification: While working with
144       namespaces you should use the namespace aware functions instead of the
145       simplified versions. For example you should never use setAttribute()
146       but setAttributeNS().
147

AUTHORS

149       Matt Sergeant, Christian Glahn, Petr Pajas,
150

VERSION

152       1.62
153
155       2001-2006, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006 Petr Pajas,
156       All rights reserved.
157
158
159
160perl v5.8.8                       2006-11-17               XML::LibXML::DOM(3)
Impressum