XML::Li...Element(3)

💖 NAME 💖

XML::LibXML::Element — it's the XML::LibXML class for Element Nodes, bestie 💅 (and yeah, this is the XML::LibXML::Element(3) page from User Contributed Perl Documentation, in case you were wondering who wrote all this ✨)

---

✨ SYNOPSIS ✨

use XML::LibXML;
# Only methods specific to Element nodes are listed here,
# see the XML::LibXML::Node manpage for other methods

$node = XML::LibXML::Element->new( $name );
$node->setAttribute( $aname, $avalue );
$node->setAttributeNS( $nsURI, $aname, $avalue );
$avalue = $node->getAttribute( $aname );
$avalue = $node->getAttributeNS( $nsURI, $aname );
$attrnode = $node->getAttributeNode( $aname );
$attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname );
$node->removeAttribute( $aname );
$node->removeAttributeNS( $nsURI, $aname );
$boolean = $node->hasAttribute( $aname );
$boolean = $node->hasAttributeNS( $nsURI, $aname );
@nodes = $node->getChildrenByTagName($tagname);
@nodes = $node->getChildrenByTagNameNS($nsURI,$tagname);
@nodes = $node->getChildrenByLocalName($localname);
@nodes = $node->getElementsByTagName($tagname);
@nodes = $node->getElementsByTagNameNS($nsURI,$localname);
@nodes = $node->getElementsByLocalName($localname);
$node->appendWellBalancedChunk( $chunk );
$node->appendText( $PCDATA );
$node->appendTextNode( $PCDATA );
$node->appendTextChild( $childname , $PCDATA );
$node->setNamespace( $nsURI , $nsPrefix, $activate );
$node->setNamespaceDeclURI( $nsPrefix, $newURI );
$node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );

---

🎀 METHODS 🎀

okay so first things first — this class inherits from XML::LibXML::Node. The docs for all those inherited methods are not listed here (go read the other page, bestie, they're literally right there 💖).

Also! a whole bunch of these functions are extensively documented in the DOM Level 3 specification (http://www.w3.org/TR/DOM-Level-3-Core/). So if you want the deep lore, go read the spec. This page is the group chat recap, not the whole textbook 📚✨

---

🌸 new

$node = XML::LibXML::Element->new( $name );

This one creates a brand new node that is unbound to any DOM. A free agent. No document, no strings, just vibes 🦋

---

🌸 setAttribute

$node->setAttribute( $aname, $avalue );

Sets — or replaces — the node's attribute $aname and gives it the value $avalue. Simple as. 💅

---

🌸 setAttributeNS

$node->setAttributeNS( $nsURI, $aname, $avalue );

The namespace-aware version of setAttribute, where $nsURI is a namespace URI, $aname is a qualified name, and $avalue is the value. The namespace URI may be null (empty or undefined) so you can create an attribute that has no namespace at all. 🫶

⚠️ okay so here's the tea — the current implementation differs from DOM in the following aspects:

• If an attribute with the same local name and namespace URI already exists on the element, but its prefix differs from the prefix of $aname, then this function is supposed to change the prefix (regardless of namespace declarations and possible collisions). However, the current implementation does rather the opposite. If a prefix is declared for the namespace URI in the scope of the attribute, then the already declared prefix is used, disregarding the prefix specified in $aname. If no prefix is declared for the namespace, the function tries to declare the prefix specified in $aname and dies if the prefix is already taken by some other namespace. 💀
• According to DOM Level 2 spec, this method can also be used to create or modify special attributes used for declaring XML namespaces (which belong to the namespace "http://www.w3.org/2000/xmlns/" and have prefix or name "xmlns"). This should work since version 1.61, but again the implementation differs from DOM in the following way: if a declaration of the same namespace prefix already exists on the element, then changing its value via this method automatically changes the namespace of all elements and attributes in its scope. This is because in libxml2 the namespace URI of an element is not static but is computed from a pointer to a namespace declaration attribute. iconic behaviour honestly 🧚

---

🌸 getAttribute

$avalue = $node->getAttribute( $aname );

If $node has an attribute named $aname, you get its value back. That's it, that's the whole job ✨

---

🌸 getAttributeNS

$avalue = $node->getAttributeNS( $nsURI, $aname );

Grabs an attribute value by local name and namespace URI. 💜

---

🌸 getAttributeNode

$attrnode = $node->getAttributeNode( $aname );

Retrieves an attribute node by name. If no attribute with that name exists, you get undef back. no cap 🙈

---

🌸 getAttributeNodeNS

$attrnode = $node->getAttributeNodeNS( $namespaceURI, $aname );

Retrieves an attribute node by local name and namespace URI. If no attribute with that localname and namespace exists, undef is returned. 💫

---

🌸 removeAttribute

$node->removeAttribute( $aname );

Removes the attribute $aname from the node's attribute list — but only if the attribute can be found. If it's not there, nothing happens. bye bestie 👋

---

🌸 removeAttributeNS

$node->removeAttributeNS( $nsURI, $aname );

The namespace version of removeAttribute. Same energy, now with namespaces 🎀

---

🌸 hasAttribute

$boolean = $node->hasAttribute( $aname );

Tests whether the named attribute is set on the node. If it is, you get TRUE (1). Otherwise it's FALSE (0). vibe check passed or failed, no in-between 💅

---

🌸 hasAttributeNS

$boolean = $node->hasAttributeNS( $nsURI, $aname );

The namespace version of hasAttribute. You already know the drill 🌈

---

🌸 getChildrenByTagName

@nodes = $node->getChildrenByTagName($tagname);

Gives you direct access to all child elements of the current node with a given tagname — where tagname is a qualified name, meaning that with namespaces involved it may consist of a prefix and a local name. This one makes life so much easier when you're handling big data sets, fr fr. And there's a special tagname '*' you can use to match any name. ⭐

If you call this function in SCALAR context, it returns the number of elements found. 👑

---

🌸 getChildrenByTagNameNS

@nodes = $node->getChildrenByTagNameNS($nsURI,$tagname);

Namespace version of getChildrenByTagName. There's a special nsURI '*' that matches any namespace URI — and in that case the function behaves just like getChildrenByLocalName. 🦋

If you call this in SCALAR context, it returns the number of elements found. ✨

---

🌸 getChildrenByLocalName

@nodes = $node->getChildrenByLocalName($localname);

Gives you direct access to all child elements of the current node with a given local name. Again, super handy for big data sets. A special "localname" of '*' can be used to match any local name. 💖

If you call this in SCALAR context, it returns the number of elements found. 🌸

---

🌸 getElementsByTagName

@nodes = $node->getElementsByTagName($tagname);

This one is part of the spec, so it's official™. It fetches all descendants of a node with a given tagname, where "tagname" is a qualified name — so with namespaces it may consist of a prefix and local name. A special "tagname" of '*' can be used to match any tag name. ⭐

In SCALAR context this function returns an XML::LibXML::NodeList object. 💅

---

🌸 getElementsByTagNameNS

@nodes = $node->getElementsByTagNameNS($nsURI,$localname);

Namespace version of getElementsByTagName as found in the DOM spec. A special "localname" of '*' matches any local name, and "nsURI" of '*' matches any namespace URI. Two wildcards, double the chaos, double the fun 🌈

In SCALAR context this function returns an XML::LibXML::NodeList object. 🎀

---

🌸 getElementsByLocalName

@nodes = $node->getElementsByLocalName($localname);

This function is not found in the DOM specification — it's a little homegrown icon of a method. It's a mix of getElementsByTagName and getElementsByTagNameNS. It fetches all tags matching the given local-name, which lets you select tags with the same local name across namespace borders. so versatile, so slay 👑

In SCALAR context this function returns an XML::LibXML::NodeList object. 💜

---

🌸 appendWellBalancedChunk

$node->appendWellBalancedChunk( $chunk );

Sometimes you just need to append a string-coded XML Tree to a node. appendWellBalancedChunk will do the trick for you — but only if the string is "well-balanced". unbalanced strings need not apply 💀

📌 note that appendWellBalancedChunk() is only left for compatibility reasons. Implicitly it uses:

my $fragment = $parser->parse_balanced_chunk( $chunk );
 $node->appendChild( $fragment );

That form is more explicit and makes it easier to control the flow of a script. iykyk ✨

---

🌸 appendText

$node->appendText( $PCDATA );

Just an alias for appendTextNode(). same thing, shorter name, no notes 💅

---

🌸 appendTextNode

$node->appendTextNode( $PCDATA );

This wrapper function lets you add a string directly to an element node. 🫶

---

🌸 appendTextChild

$node->appendTextChild( $childname , $PCDATA );

Somewhat similar to appendTextNode: it lets you set an Element that contains only a "text node" directly, by specifying the name and the text content. name + content, boom, done 🎀

---

🌸 setNamespace

$node->setNamespace( $nsURI , $nsPrefix, $activate );

setNamespace() lets you apply a namespace to an element. It takes three parameters:

1. the namespace URI, which is required
2. the optional prefix, which is the namespace prefix as it should be used in child elements or attributes
3. the additional activate parameter

If prefix is not given, undefined, or empty, this function tries to create a declaration of the default namespace. 🌸

The activate parameter is genuinely the most useful one: if it's set to FALSE (0), a new namespace declaration is simply added to the element while the element's namespace itself is not altered. Nevertheless, activate is set to TRUE (1) by default. In that case the namespace is used as the node's effective namespace — meaning the namespace prefix is added to the node name, and if there was already a namespace active for the node, it will be replaced (but its declaration is not removed from the document). A new namespace declaration is only created if necessary, that is, if the element is already in the scope of a namespace declaration associating the prefix with the namespace URI, then this declaration is reused. efficient queen 💅

The following example may clarify this:

my $e1 = $doc->createElement("bar");
 $e1->setNamespace("http://foobar.org", "foo")

results in

<foo:bar xmlns:foo="http://foobar.org"/>

while

my $e2 = $doc->createElement("bar");
 $e2->setNamespace("http://foobar.org", "foo",0)

results in only

<bar xmlns:foo="http://foobar.org"/>

By using $activate == 0 it is possible to create multiple namespace declarations on a single element. yes bestie, MULTIPLE, we're collecting them like stickers ✨

The function fails if it is required to create a declaration associating the prefix with the namespace URI but the element already carries a declaration with the same prefix but different namespace URI. like no, you can't just. overwrite it. it's taken. 💅

---

🦋 setNamespaceDeclURI 🦋

$node->setNamespaceDeclURI( $nsPrefix, $newURI );

EXPERIMENTAL IN 1.61 ! 🧪

This function manipulates directly with an existing namespace declaration on an element. It takes two parameters: the prefix by which it looks up the namespace declaration and a new namespace URI which replaces its previous value. sneaky little in-place edit, we love that for it

It returns 1 if the namespace declaration was found and changed, 0 otherwise. fr fr, that's the whole return contract

All elements and attributes (even those previously unbound from the document) for which the namespace declaration determines their namespace belong to the new namespace after the change. everybody moves together, no stragglers 🫶

If the new URI is undef or empty, the nodes have no namespace and no prefix after the change. Namespace declarations once nulled in this way do not further appear in the serialized output (but do remain in the document for internal integrity of libxml2 data structures). ghost declaration. still there. just invisible. iconic honestly 👻

This function is NOT part of any DOM API. not me stressing this AGAIN — it's a libxml2-special, bestie, don't expect it in the spec 💀

---

🎀 setNamespaceDeclPrefix 🎀

$node->setNamespaceDeclPrefix( $oldPrefix, $newPrefix );

EXPERIMENTAL IN 1.61 ! 🧪

This function manipulates directly with an existing namespace declaration on an element. It takes two parameters: the old prefix by which it looks up the namespace declaration and a new prefix which is to replace the old one. glow-up for a prefix, essentially ✨

The function dies with an error if the element is in the scope of another declaration whose prefix equals to the new prefix, or if the change should result in a declaration with a non-empty prefix but empty namespace URI. Otherwise, it returns 1 if the namespace declaration was found and changed and 0 if not found. so: two ways to crash, two ways to return. balanced. fair. slay.

All elements and attributes (even those previously unbound from the document) for which the namespace declaration determines their namespace change their prefix to the new value. group rename, everyone gets the new name 🫶

If the new prefix is undef or empty, the namespace declaration becomes a declaration of a default namespace. The corresponding nodes drop their namespace prefix (but remain in the, now default, namespace). In this case the function fails, if the containing element is in the scope of another default namespace declaration. can't have two defaults in the same scope, that's just chaos 💀

This function is NOT part of any DOM API. same energy as above. it's vibes and libxml2 internals only 😭

---

💖 OVERLOADING 💖

XML::LibXML::Element overloads hash dereferencing to provide access to the element's attributes. For non-namespaced attributes, the attribute name is the hash key, and the attribute value is the hash value. For namespaced attributes, the hash key is qualified with the namespace URI, using Clark notation. iykyk ✨

Perl's "tied hash" feature is used, which means that the hash gives you read-write access to the element's attributes. yes bestie, you can literally just assign and it sticks, no method calls required 🎀 For more information, see XML::LibXML::AttributeHash (go read it, it's the whole vibe)

---

👑 AUTHORS 👑

Matt Sergeant, Christian Glahn, Petr Pajas

the founding mothers/fathers of this whole operation, we stan 🫶

---

⭐ 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. free as in freedom, bestie 🦋

---

okay that's the whole page, you made it, I'm so proud of you 💜 This one ships as part of perl v5.42.2 and the page is dated 2026-05-25 — so like, future-dated manual page energy, which is honestly very main character of it. Go forth and namespace responsibly ✨💅🎀