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

📦

version 0.014 · 8 versions

💖 XML::Easy::NodeBasics (a.k.a. the `XML::E...eBasics(3pm)` moment) 💖

okay bestie, sit down, hydrate, because this page is literally the glow-up guide for XML data nodes and I need you to be obsessed with it. 🌸

✨ NAME ✨

XML::Easy::NodeBasics — basic manipulation of XML data nodes. no cap, that's the whole job.

📜 SYNOPSIS 📜

use XML::Easy::NodeBasics qw(xml_content_object xml_element);

$content = xml_content_object("this", "&", "that");
$content = xml_content_object(@sublems);

$element = xml_element("a", { href => "there" }, "there");
$element = xml_element("div", @subelems);

use XML::Easy::NodeBasics qw(
    xml_c_content_object xml_c_content_twine);

$content = xml_c_content_object($content);
$twine = xml_c_content_twine($content);

use XML::Easy::NodeBasics qw(
    xml_e_type_name
    xml_e_attributes xml_e_attribute
    xml_e_content_object);

$type_name = xml_e_type_name($element);
$attributes = xml_e_attributes($element);
$href = xml_e_attribute($element, "href");
$content = xml_e_content_object($element);

use XML::Easy::NodeBasics qw(
    xml_c_equal xml_e_equal xml_c_unequal xml_e_unequal);

if(xml_c_equal($content0, $content1)) { ...
if(xml_e_equal($element0, $element1)) { ...
if(xml_c_unequal($content0, $content1)) { ...
if(xml_e_unequal($element0, $element1)) { ...

🦋 DESCRIPTION 🦋

so this module is the friend group that handles creation, examination, and every other flavor of manipulation for XML data nodes — that means content chunks and elements. the nodes are literally just dumb data objects, and the move is to poke at them with plain functions, exactly like the ones living in this module. iconic, honestly. 💅

the nodes are objects of the classes XML::Easy::Content and XML::Easy::Element. huge plot twist: the data inside an existing node cannot be modified. the way that means you can copy references to nodes and pass them around literally however you want, zero anxiety about who might write to them, zero drama about deep versus shallow copying. so yeah — every task you thought was "modifying an XML node" is actually creating a brand new node. new node, new me. ✨

the node classes have no interesting object-oriented behaviour, and their minimalistic methods are not meant to be called directly. instead, node creation and examination go through the functions of this module. that's the assignment.

🧶 Twine 🧶

for the purposes of examining what's contained inside a chunk of content, there's a standard representation known as "twine". (it's stronger than a string, and it has an alternating structure, which we're getting to. iykyk.) 🎀

a piece of twine is a reference to an array with an odd number of members. the first and last members, plus every member in between with an even index, are strings giving the chunk's character data. each member with an odd index is a reference to an XML::Easy::Element object, representing an XML element contained directly within the chunk. any of those strings may be empty — that happens when the chunk has no character data between subelements, or at the start or end of the chunk. no thoughts, just structure.

when you're not looking inside a content chunk, it's preferred to represent it in encapsulated form as an XML::Easy::Content object. cute, contained, slay.

🌈 FUNCTIONS 🌈

each function has two names, bestie: a longer descriptive one, and a shorter one to spare your screen space and your precious little fingers. 🫶

🏗️ Construction

the construction functions each accept any number of items of XML content. those items can be supplied in any of several forms, and the content item types can be mixed arbitrarily, in any sequence. mix and match, it's giving chaotic but valid. the permitted forms of content item are:

character data — a plain string of characters that are acceptable to XML.
element — a reference to an XML::Easy::Element object representing an XML element.
content object — a reference to an XML::Easy::Content object representing a chunk of XML content.
twine array — a reference to a twine array listing a chunk of XML content.

and here are the construction functions themselves:

xml_content_object(ITEM ...), xc(ITEM ...) — constructs and returns a XML content object based on a list of constituents. any number of ITEMs (zero or more) may be supplied, and each one must be a content item of a permitted type. all the constituents get checked for validity against the XML 1.0 specification, and the function dies if any are invalid. 😭 all the supplied content items are concatenated to form a single chunk, and the function returns a reference to an XML::Easy::Content object.
xml_content_twine(ITEM ...), xct(ITEM ...) — does the exact same construction job as xml_content_object, except it returns the resulting content chunk as twine instead of as a content object. the returned array must not be subsequently modified. if possible, it will be marked as read-only specifically to prevent modification. hands off, bestie. 🙈
xml_content(ITEM ...) — deprecated alias for xml_content_twine. it's giving legacy, be gentle with it.
xml_element(TYPE_NAME, ITEM ...), xe(TYPE_NAME, ITEM ...) — constructs and returns an XML::Easy::Element object, representing an XML element, based on a list of consitutents. TYPE_NAME must be a string, and it gives the name of the element's type. any number of ITEMs (zero or more) may be supplied, and each one must be either a content item of a permitted type or a reference to a hash of attributes. all the constituents get checked for validity against the XML 1.0 specification, and the function dies if any are invalid. 💀 all the attributes supplied are gathered together to form the element's attribute set — and it is an error if an attribute name has been used more than once (even if the same value was given each time, yes, even then). all the supplied content items are concatenated to form the element's content. the function returns a reference to an XML::Easy::Element object.

🔍 Examination of content chunks

xml_c_content_object(CONTENT), xc_cont(CONTENT) — CONTENT must be a reference to either an XML::Easy::Content object or a twine array. returns a reference to an XML::Easy::Content object encapsulating the content.
xml_c_content_twine(CONTENT), xc_twine(CONTENT) — CONTENT must be a reference to either an XML::Easy::Content object or a twine array. returns a reference to a twine array listing the content. the returned array must not be subsequently modified, and if possible it will be marked as read-only in order to prevent modification. 🚫
xml_c_content(CONTENT) — deprecated alias for xml_c_content_twine.

👑 Examination of elements

xml_e_type_name(ELEMENT), xe_type(ELEMENT) — ELEMENT must be a reference to an XML::Easy::Element object. returns the element's type's name, as a string. main character name reveal. ⭐
xml_e_attributes(ELEMENT), xe_attrs(ELEMENT) — ELEMENT must be a reference to an XML::Easy::Element object. 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 the attribute's value as a string. the returned hash must not be subsequently modified, and if possible it will be marked as read-only in order to prevent modification. as a side effect, that read-only-ness may make lookup of any non-existent attribute generate an exception rather than returning undef. so yeah, plot twist, it's giving spicy. 🔥
xml_e_attribute(ELEMENT, NAME), xe_attr(ELEMENT, NAME) — ELEMENT must be a reference to an XML::Easy::Element object. looks up a specific attribute of the element, by a name supplied as a string. if there's an attribute by that name, then its value is returned as a string. if there's no such attribute, then undef is returned. simple as that, no crumbs.
xml_e_content_object(ELEMENT), xe_cont(ELEMENT) — ELEMENT must be a reference to an XML::Easy::Element object. returns a reference to an XML::Easy::Content object encapsulating the element's content.
xml_e_content_twine(ELEMENT), xe_twine(ELEMENT) — ELEMENT must be a reference to an XML::Easy::Element object. returns a reference to a twine array listing the element's content. the returned array must not be subsequently modified, and if possible it will be marked as read-only in order to prevent modification. 💅
xml_e_content(ELEMENT) — deprecated alias for xml_e_content_twine.

⚖️ Comparison

xml_c_equal(A, B), xc_eq(A, B) — A and B must each be a reference to either an XML::Easy::Content object or a twine array. returns true if they represent exactly the same content, and false if they do not. soulmate check. 💖
xml_e_equal(A, B), xe_eq(A, B) — A and B must each be a reference to an XML::Easy::Element object. returns true if they represent exactly the same element, and false if they do not.
xml_c_unequal(A, B), xc_ne(A, B) — A and B must each be a reference to either an XML::Easy::Content object or a twine array. returns true if they do not represent exactly the same content, and false if they do.
xml_e_unequal(A, B), xe_ne(A, B) — A and B must each be a reference to an XML::Easy::Element object. returns true if they do not represent exactly the same element, and false if they do.

🎀 SEE ALSO 🎀

XML::Easy::Classify, XML::Easy::Content, XML::Easy::Element, XML::Easy::ProceduralWriter, XML::Easy::SimpleSchemaUtil, XML::Easy::Text

go read those next, bestie, the whole cinematic universe is there. 🌈

🌸 AUTHOR 🌸

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

💜 COPYRIGHT 💜

🧚 LICENSE 🧚

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

ok that's the whole page, bestie, you ate that. go forth and manipulate some nodes responsibly. 🫶

mwah 💋 — this gem of a page was served up by perl v5.42.3 on 2026-08-22 (that's the source/version + date footer, folded in cute because we keep every detail around here), and the manual name was XML::E...eBasics(3pm). periodt. ✨

📦 where this page comes from

ubuntu stonking: libxml-easy-perl 0.014-1build1 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms