XML::E...lement(3pm)

💖 XML::E...lement — bestie edition 💖

okay so this is XML::Easy::Element, part of the User Contributed Perl Documentation situation. it's literally the abstract form of an XML element. let's get into it 🫶

---

✨ NAME ✨

XML::Easy::Element — the abstract form of an XML element. that's it, that's the vibe 💅

---

🌸 SYNOPSIS 🌸

use XML::Easy::Element;

$element = XML::Easy::Element->new("a", { href => "#there" },
            $content);

$type_name = $element->type_name;
$attributes = $element->attributes;
$href = $element->attribute("href");
$content = $element->content_object;

---

🦋 DESCRIPTION 🦋

so an object of this class represents an XML element — a node in the tree that makes up an XML document. it's in an abstract form, which means it's built for general manipulation, not for being pretty. it is completely isolated from the textual representation of XML. it holds only the meaningful content of the element. no extra crumbs, no formatting drama ✨

and here's the thing, bestie: the data in an element object cannot be modified. like, at all. if you want different data, you need to create a whole new object. it's giving "we don't do edits here" 💀

the properties of an XML element come in three kinds, and yes, we're going through all three:

• firstly, the element has exactly one type, and that type is referred to by a name.
• secondly, the element has a set of zero or more attributes. each attribute is made of a name (which is unique among the attributes of that element) and a value (which is a string of characters).
• finally, the element has content, which is a sequence of zero or more characters and (recursively!) elements, interspersed in any fashion. yes, any fashion. chaotic content is valid content, iconically.

now, the element type name and all the attribute names follow the XML syntax for names. this allows a wide set of Unicode characters, with some restrictions. attribute values and character content can use almost all Unicode characters too — only a few of them (like most of the ASCII control characters) are prohibited by the spec from being directly represented in XML. not me getting fenced in by the specification 😭

okay, important one: this class is not meant to be subclassed. XML elements are unextendable, dumb data. no glow-ups allowed. also, element objects are better processed using the functions in XML::Easy::NodeBasics than using the methods of this class. fr fr, the functions are the main character here 🎀

---

🎀 CONSTRUCTOR 🎀

• XML::Easy::Element->new(TYPE_NAME, ATTRIBUTES, CONTENT) — constructs and returns a new element object with the properties you specified. let's break down the receipts:
  • TYPE_NAME must be a string.
  • ATTRIBUTES must be a reference to a hash in the exact same form that's returned by the accessor method attributes (that's the one below, keep scrolling bestie).
  • CONTENT must be a reference to either an XML::Easy::Content object or a twine array (see "Twine" in XML::Easy::NodeBasics).

all of them get checked for validity against the XML 1.0 specification, and if any of them are invalid, the function dies. no soft launches, no second chances — just death 💀

---

💅 METHODS 💅

• $element->type_name — returns the element type name, as a string. just the name, bestie ✨
• $element->attributes — returns a reference to a hash encapsulating the element's attributes. in that hash, each key is an attribute name, and the corresponding value is that attribute's value as a string.

⚠️ the returned hash must not be subsequently modified. if possible, it will be marked as read-only to prevent modification. and as a side effect, that read-only-ness may make looking up any non-existent attribute generate an exception rather than returning undef. so like… watch out, okay? 🙈

• $element->attribute(NAME) — looks up one specific attribute of the element. the NAME you supply must be a string containing a valid attribute name. if there's an attribute by that name, its value is returned as a string. if there's no such attribute, undef is returned. simple as that 🌸
• $element->content_object — returns a reference to an XML::Easy::Content object encapsulating the element's content. iconic content-holder behavior 👑
• $element->content_twine — returns a reference to a twine array (see "Twine" in XML::Easy::NodeBasics) listing the element's content.

⚠️ same deal as before: the returned array must not be subsequently modified. if possible, it will be marked as read-only to prevent modification. no touching 🚫

• $element->content — deprecated alias for the content_twine method. it still works, but it's giving "old money that nobody invites to the party anymore." use content_twine instead 🧚

---

🔥 SEE ALSO 🔥

• XML::Easy::Content
• XML::Easy::NodeBasics

go read those too, they're the supporting cast and they ate 🌈

---

💜 AUTHOR 💜

Andrew Main (Zefram) <zefram@fysh.org>

---

⭐ COPYRIGHT ⭐

Copyright (C) 2008, 2009 PhotoBox Ltd

Copyright (C) 2009, 2010, 2011, 2017 Andrew Main (Zefram) <zefram@fysh.org>

---

🌟 LICENSE 🌟

This module 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 documented in perl v5.42.3, dated 2026-08-22, and it's part of the XML::E...lement(3pm) situation. slay, go build some XML trees, and remember: the data does not change 💖✨🦋