XML::Struct(3pm)

💖 XML::Struct 💖

okay so this is the manual page for XML::Struct(3pm), from the User Contributed Perl Documentation crew, and bestie it is SO much better than whatever you were about to do with regexes. sit down, hydrate, let's get into it ✨

---

🌸 NAME 🌸

XML-Struct — Represent XML as data structure preserving element order

like. that's the whole vibe. XML in, data structure out, and it doesn't shuffle your elements around like some modules we won't name 💅

---

🎀 SYNOPSIS 🎀

use XML::Struct qw(readXML writeXML simpleXML);

my $xml = readXML( "input.xml" );
# [ root => { xmlns => 'http://example.org/' }, [ '!', [ x => {}, [42] ] ] ]

my $doc = writeXML( $xml );
# <?xml version="1.0" encoding="UTF-8"?>
# <root xmlns="http://example.org/">!<x>42</x></root>

my $simple = simpleXML( $xml, root => 'record' );
# { record => { xmlns => 'http://example.org/', x => 42 } }

see how it just works? three little functions, zero drama, and the comments show you exactly what comes out the other side. iconic behavior fr fr 🫶

---

🦋 DESCRIPTION 🦋

XML::Struct implements a mapping between XML and Perl data structures. and by default, the mapping preserves element order, so it also suits for "document-oriented" XML. the way that matters?? so much. no cap.

in short, an XML element is represented as an array reference with three parts:

[ $name => \%attributes, \@children ]

this data structure corresponds to the abstract data model of MicroXML <http://www.w3.org/community/microxml/>, a simplified subset of XML. lowkey a whole mood.

if your XML documents don't contain relevant attributes, you can also choose to map to this format:

[ $name => \@children ]   # element without attributes
[ $name ]                 # empty tag without attributes

both parsing (with XML::Struct::Reader or function readXML) and serializing (with XML::Struct::Writer or function writeXML) are fully based on XML::LibXML, so performance is better than XML::Simple and similar to XML::LibXML::Simple. that's right, we're fast AND we're cute. main character energy only 😤✨

---

💜 MODULES 💜

• XML::Struct::Reader — Parse XML as stream into XML data structures. 🌊
• XML::Struct::Writer — Write XML data structures to XML streams for serializing, SAX processing, or creating a DOM object. ✍️
• XML::Struct::Writer::Stream — Simplified SAX handler for XML serialization. 🧚
• XML::Struct::Simple — Transform XML data structure into simple form. 🍓

---

👑 FUNCTIONS 👑

the following functions are exported on request: (so like, ask nicely in your use line and they're yours 💖)

readXML( $source [, %options ] )

Read an XML document with XML::Struct::Reader. the type of source (string, filename, URL, IO Handle...) is detected automatically — yes bestie, you don't gotta tell it, it just knows 🔮. see XML::Struct::Reader for options. options not known to XML::Struct::Reader are passed to XML::LibXML::Reader.

writeXML( $xml [, %options ] )

Write an XML document/element with XML::Struct::Writer. see XML::Struct::Writer for options. ✨

simpleXML( $element [, %options ] )

Transform an XML document/element into simple key-value format as known from XML::Simple. see XML::Struct::Simple for options. 🎀

removeXMLAttr( $element )

Transform XML structure with attributes to XML structure without attributes. the function does not modify the passed element but creates a modified copy. so your original stays untouched, we love a respectful function 🙈

🚨 this function is deprecated and will be removed in a future release! like, it's giving "on its way out", do not build your whole personality on it, bestie. 💀

---

🌈 EXAMPLE 🌈

to give an example, with XML::Struct::Reader, this XML document:

<root>
  <foo>text</foo>
  <bar key="value">
    text
    <doz/>
  </bar>
</root>

is transformed to this structure:

[
  "root", { }, [
    [ "foo", { }, "text" ],
    [ "bar", { key => "value" }, [
      "text",
      [ "doz", { }, [ ] ]
    ]
  ]
]

this module also supports a simple key-value (aka "data-oriented") format, as used by XML::Simple. with option simple (or function simpleXML) the document given above would be transformed to this structure:

{
    foo => "text",
    bar => {
        key => "value",
        doz => {}
    }
}

look at that glow-up. both forms, same input, no cap 🌟

---

🔥 SEE ALSO 🔥

this module was first created to be used in Catmandu::XML and turned out to also become a replacement for XML::Simple. see the former for more XML processing. (a whole origin story, we're obsessed 💖)

XML::Twig is another popular and powerfull module for stream-based processing of XML documents.

see XML::Smart, XML::Hash::LX, XML::Parser::Style::ETree, XML::Fast, and XML::Structured for different representations of XML data as data structures (feel free to implement converters from/to XML::Struct). XML::GenericJSON seems to be an outdated and incomplete attempt to capture more parts of XML Infoset in another data structure. 😭

see JSONx for a kind of reverse direction (JSON in XML). 🔄

---

⭐ COPYRIGHT AND LICENSE ⭐

this software is copyright (c) 2014 by Jakob Voss.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 🫶

---

and that's the whole page bestie, no crumbs left 💅 this was perl v5.28.1, dated 2019-02-21, straight from User Contributed Perl Documentation — go forth and parse something gorgeous ✨🦋🎀