XML::LibXML::DOM(3)

💖 XML::LibXML::DOM 💖

okay bestie, so this is XML::LibXML::DOM from the User Contributed Perl Documentation, and it's basically the whole vibe guide for how XML::LibXML does DOM. pull up a chair 🫶

---

✨ NAME ✨

XML::LibXML::DOM — the XML::LibXML DOM Implementation, periodt.

---

🌸 DESCRIPTION 🌸

So XML::LibXML gives you a lightweight interface to mess with a node of the document tree that the XML::LibXML parser built. It follows the DOM Level 3 specification as far as it possibly can, no cap. And on top of the specified functions, XML::LibXML also ships some functions that are just way more handy to use in the perl environment. iykyk 💅

One thing you gotta remember though: XML::LibXML is an interface to libxml2 nodes, and those actually live on the C-Level of XML::LibXML. Translation? Every node is a reference to a structure, and that structure is not a perl hash or array. The only way to access these structures' values is through the DOM interface provided by XML::LibXML. Which also means… you literally cannot just inherit an XML::LibXML node and add new member variables as if they were hash keys. not me finding that out the hard way 😭

The DOM interface of XML::LibXML does not intend to implement a full DOM interface like XML::GDOME does and like full featured applications use. Instead, it offers a simple way to build or modify documents that are created by XML::LibXML's parser. iconic behavior honestly.

Another target of the XML::LibXML interface is to make the interfaces of libxml2 available to the perl community. That includes some workarounds for features where libxml2 assumes more control over the C-Level than most perl users have. so yeah, we're bridging worlds here 🌈

One of the most important parts of the XML::LibXML DOM interface: the interfaces try to follow the DOM Level 3 specification (<http://www.w3.org/TR/DOM-Level-3-Core/>) rather strictly. Which means the interface functions are named exactly as the DOM specification says, and not what widespread Java interfaces claim to be the standard. now, there are several functions that have only a singular interface that conforms to the DOM spec, and for those XML::LibXML provides an additional Java style alias interface. best of both worlds, slay.

Moreover — and this is the part where I hold your hand — there are some function interfaces left over from early stages of XML::LibXML for compatibility reasons. These interfaces exist 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. so like, please migrate bestie, don't be the last one at the party 🎀

---

🧚 Encodings and XML::LibXML's DOM implementation 🧚

See the section on Encodings in the XML::LibXML manual page. (go read it, it's good for you ✨)

---

🦋 Namespaces and XML::LibXML's DOM implementation 🦋

XML::LibXML's DOM implementation is limited by the DOM implementation of libxml2, and libxml2 treats namespaces slightly differently than what the DOM Level 2 specification requires. messy, I know.

According to the DOM Level 2 specification, namespaces of elements and attributes should be persistent, and nodes should be permanently bound to namespace URIs as they get created. It should be possible to manipulate the special attributes used for declaring XML namespaces just as other attributes without affecting the namespaces of other nodes. In DOM Level 2, the application is the one responsible for creating the special attributes consistently and/or for correct serialization of the document. that's a lot of responsibility ngl 🙈

This is both inconvenient, causes problems in serialization of DOM to XML, and most importantly, seems almost impossible to implement over libxml2.

In libxml2, the namespace URI and prefix of a node is provided by a pointer to a namespace declaration (which shows up as a special xmlns attribute in the XML document). If the prefix or namespace URI of the declaration changes, the prefix and namespace URI of all nodes that point to it changes as well. Moreover, in contrast to DOM, a node (element or attribute) can only be bound to a namespace URI if there is some namespace declaration in the document to point to. no declaration, no binding. those are the rules 💀

Therefore the current DOM implementation in XML::LibXML tries to treat namespace declarations as a compromise between reason, common sense, limitations of libxml2, and the DOM Level 2 specification. a whole group project fr fr.

In XML::LibXML, special attributes declaring XML namespaces are often created automatically, usually when a namespaced node is attached to a document and no existing declaration of the namespace and prefix is in the scope to be reused. In this respect, the XML::LibXML DOM implementation differs from the DOM Level 2 specification, according to which special attributes for declaring the appropriate XML namespaces should not be added when a node with a namespace prefix and namespace URI is created.

Namespace declarations are also created when XML::LibXML::Document's createElementNS() or createAttributeNS() function are used. If the namespace is not declared on the documentElement, the namespace will be locally declared for the newly created node. In the case of Attributes this may look a bit confusing, since these nodes cannot have namespace declarations itself. In this case the namespace is internally applied to the attribute and later declared on the node the attribute is appended to (if required). 🫶

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"/>

The namespace is declared on the document element during the setAttributeNodeNS() call. see? it all comes together ✨

Namespaces can also be declared explicitly by the use of XML::LibXML::Element's setNamespace() function. Since 1.61, they can also be manipulated with the functions setNamespaceDeclPrefix() and setNamespaceDeclURI() (not available in DOM, fyi). Changing a URI or prefix of an existing namespace declaration affects the namespace URI and prefix of all nodes which point to it (that is, the nodes in its scope). so like… be careful, that ripples 👑

It is also 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 setAttribute() but setAttributeNS(). write that on your mirror bestie 💅

⚠️ real talk: that last one is not a suggestion, it's the spec. namespace aware functions only.

---

👑 AUTHORS 👑

Matt Sergeant, Christian Glahn, Petr Pajas

---

⭐ VERSION ⭐

2.0213

---

🎀 COPYRIGHT 🎀

2001-2007, AxKit.com Ltd.

2002-2006, Christian Glahn.

2006-2009, Petr Pajas.

---

🌈 LICENSE 🌈

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

and that's the whole page, bestie 💜 this was perl v5.42.2, dated 2026-05-25, and it's the XML::LibXML::DOM(3) manpage — go forth and namespace responsibly 🌸🦋✨