XML::Easy::Text(3pm)

📦
version 0.014 · 8 versions
, in ubuntu stonking

💖 XML::Easy::Text 💖 — the XML::Easy::Text(3pm) page, but make it bestie-coded

okay so real talk: this is XML::Easy::Text, from the User Contributed Perl Documentation crew, and it's literally the module that lets you parse XML and serialise it back out again. XML parsing and serialisation, that's the whole vibe. it's giving "i speak XML fluently and i will not be weird about it." 🦋

✨ SYNOPSIS ✨

like, here's the whole API in one breath, no cap:

use XML::Easy::Text qw(
    xml10_read_content_object xml10_read_element
    xml10_read_document xml10_read_extparsedent_object);

$content = xml10_read_content_object($text);
$element = xml10_read_element($text);
$element = xml10_read_document($text);
$content = xml10_read_extparsedent_object($text);

use XML::Easy::Text qw(
    xml10_write_content xml10_write_element
    xml10_write_document xml10_write_extparsedent);

$text = xml10_write_content($content);
$text = xml10_write_element($element);
$text = xml10_write_document($element, "UTF-8");
$text = xml10_write_extparsedent($content, "UTF-8");

read it, learn it, live it. 💅

🌸 DESCRIPTION 🌸

so this module hands you functions that parse and serialise XML data according to the XML 1.0 specification. periodt.

now, the vibe of this module: it's oriented towards using XML to represent data for interchange purposes, not towards using XML as markup for principally textual data. it does not do any schema processing, and it does not interpret DTDs or any other kind of schema. it adheres strictly to the XML specification, all its awkward little details included — except for the aforementioned DTDs. yes bestie, that's the one exception, we stay honest here. 🙈

XML data in memory is represented using a tree of XML::Easy::Content and XML::Easy::Element objects. such a tree encapsulates all the structure and data content of an XML element or document, without any irrelevant detail that comes from the textual syntax. and these node trees are readily manipulated by the functions in XML::Easy::NodeBasics. iconic behaviour fr fr.

and the tea on performance: the functions of this module are implemented in C for performance, with a pure Perl backup version (which has good performance compared to other pure Perl parsers) for systems that can't handle XS modules. so like, either way you're eating good. 🔥

👑 FUNCTIONS 👑

heads up bestie: all functions die on error. no graceful little "oops", it's a full on death. 💀

🎀 Parsing

these functions take textual XML and extract the abstract XML content. in the terminology of the XML specification, they constitute a non-validating processor: they check for well-formedness of the XML, but not for adherence of the content to any schema. so they'll tell you if your XML is broken-broken, but they will not tell you if it's wrong wrong, ykwim.

the inputs (to be parsed) for these functions are always character strings. XML text is frequently encoded using UTF-8, or some other Unicode encoding, so that it can contain characters from the full Unicode repertoire. in that case, something must perform UTF-8 decoding (or decoding of some other character encoding) to convert the octets of a file to the characters on which these functions operate. a Perl I/O layer can do the job (see perlio), or it can be performed explicitly using the "decode" function in the Encode module. basically: decode first, girlie, or you're handing it octets and it wanted characters. 😭

  • xml10_read_content_object(TEXT) — TEXT must be a character string. it's parsed against the content production of the XML 1.0 grammar; i.e. as a sequence of the kind of matter that can appear between the start-tag and end-tag of an element. returns a reference to an XML::Easy::Content object. normally you would not want to use this function directly, but prefer the higher-level "xml10_read_document" function. it exists for the construction of custom XML parsers in situations that don't match the full XML grammar. so like, specialised queen energy. 💜
  • xml10_read_content_twine(TEXT) — performs the same parsing job as "xml10_read_content_object", but returns the resulting content chunk in the form of twine (see "Twine" in XML::Easy::NodeBasics) rather than a content object. and important: the returned array must not be subsequently modified. if possible, it will be marked as read-only in order to prevent modification. so hands off, bestie. 🙅
  • xml10_read_content(TEXT) — deprecated alias for "xml10_read_content_twine". old, tired, retired. still here for legacy reasons only. ✨
  • xml10_read_element(TEXT) — TEXT must be a character string. it's parsed against the element production of the XML 1.0 grammar; i.e. as an item bracketed by tags and containing content that may recursively include other elements. returns a reference to an XML::Easy::Element object. normally you would not want to use this function directly, but prefer the higher-level "xml10_read_document" function. it exists for the construction of custom XML parsers in situations that don't match the full XML grammar. same deal as above, just for whole elements instead of content. 🫶
  • xml10_read_document(TEXT) — TEXT must be a character string. it's parsed against the document production of the XML 1.0 grammar; i.e. as a root element (possibly containing subelements) optionally preceded and followed by non-content matter, possibly headed by an XML declaration. (a document type declaration is not accepted; this module does not process schemata.) returns a reference to an XML::Easy::Element object which represents the root element. nothing is returned relating to the XML declaration or other non-content matter. 🎀

this is the most likely function to use to process incoming XML data. but beware: the encoding declaration in the XML declaration, if any, does not affect the interpretation of the input as a sequence of characters. it's a little lie in your document, bestie, don't fall for it.

  • xml10_read_extparsedent_object(TEXT) — TEXT must be a character string. it's parsed against the extParsedEnt production of the XML 1.0 grammar; i.e. as a sequence of content (containing character data and subelements), possibly headed by a text declaration (which is similar to, but not the same as, an XML declaration). returns a reference to an XML::Easy::Content object. this is a relatively obscure part of the XML grammar, used when a subpart of a document is stored in a separate file. you're more likely to require the "xml10_read_document" function. niche queen 🦋
  • xml10_read_extparsedent_twine(TEXT) — performs the same parsing job as "xml10_read_extparsedent_object", but returns the resulting content chunk in the form of twine (see "Twine" in XML::Easy::NodeBasics) rather than a content object. again: the returned array must not be subsequently modified. if possible, it will be marked as read-only in order to prevent modification. 💖
  • xml10_read_extparsedent(TEXT) — deprecated alias for "xml10_read_extparsedent_twine". 💀

🌈 Serialisation

these functions take abstract XML data and serialise it as textual XML. they do not perform indentation, default attribute suppression, or any other schema-dependent processing. no pretty-printing, no vibes-based cleanup. it spits out exactly what you gave it. periodt.

the outputs of these functions are always character strings. XML text is frequently encoded using UTF-8, or some other Unicode encoding, so that it can contain characters from the full Unicode repertoire. in that case, something must perform UTF-8 encoding (or encoding of some other character encoding) to convert the characters generated by these functions to the octets of a file. a Perl I/O layer can do the job (see perlio), or it can be performed explicitly using the "encode" function in the Encode module. you see the theme here — decode going in, encode coming out. 🔄

  • xml10_write_content(CONTENT) — CONTENT must be a reference to either an XML::Easy::Content object or a twine array (see "Twine" in XML::Easy::NodeBasics). the XML 1.0 textual representation of that content is returned. 🧚
  • xml10_write_element(ELEMENT) — ELEMENT must be a reference to an XML::Easy::Element object. the XML 1.0 textual representation of that element is returned. simple, clean, done. ✨
  • xml10_write_document(ELEMENT[, ENCODING]) — ELEMENT must be a reference to an XML::Easy::Element object. the XML 1.0 textual form of a document with that element as the root element is returned. the document includes an XML declaration. if ENCODING is supplied, it must be a valid character encoding name, and the XML declaration specifies it in an encoding declaration. (the returned string consists of unencoded characters regardless of the encoding specified. — so like, don't get it twisted, the string is still characters, the encoding name is just declared, bestie.) 👑
  • xml10_write_extparsedent(CONTENT[, ENCODING]) — CONTENT must be a reference to either an XML::Easy::Content object or a twine array (see "Twine" in XML::Easy::NodeBasics). the XML 1.0 textual form of an external parsed entity encapsulating that content is returned. if ENCODING is supplied, it must be a valid character encoding name, and the returned entity includes a text declaration that specifies the encoding name in an encoding declaration. (again — the returned string consists of unencoded characters regardless of the encoding specified.) 🌸

🌟 SEE ALSO 🌟

go read those too, they're part of the lore. 📚

🫶 AUTHOR 🫶

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

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. so like, free, bestie. legally free. 💖

and that's the whole page, fr fr — this was perl v5.42.3, dated 2026-08-22, and the original doc is XML::Easy::Text(3pm). mwah, go parse something iconic. 💅✨

📦 where this page comes from