XML::S...:Reader(3pm)

🦋 NAME 🦋

okay bestie, welcome to XML::Struct::Reader — she reads XML streams into XML data structures, and she does it flawlessly. that's it, that's the whole job, and she's iconic at it. 💅

(this is the manual page for XML::S...:Reader(3pm), from the User Contributed Perl Documentation section — yes the name got squished in the header, we don't talk about it 😭)

---

✨ SYNOPSIS ✨

my $reader = XML::Struct::Reader->new( from => "file.xml" );
my $data   = $reader->read;

look at that. three seconds. done. 🎀

---

💖 DESCRIPTION 💖

so this module takes an XML stream — and it does that via XML::LibXML::Reader, no cap — and turns it into XML::Struct / MicroXML data structures. that's the vibe. that's the whole vibe. 🫶

---

🌸 METHODS 🌸

read = readNext ( [ $stream ] [, $path ] )

read the next XML element from a stream. 🦋 if you don't pass a path option, she just uses the reader's own path option — which is "*" by default — and that means: first it matches the root, then every other element. she's generous like that.

readDocument( [ $stream ] [, $path ] )

read an entire XML document. and here's the difference from read/readNext, bestie, pay attention: this one always reads the entire stream. periodt.

the return value is the first element — which by default is the root element — in scalar context, and a list of elements in array context. you can get multiple elements back, like, for instance when a path was specified to select document fragments. 👑

readElement( [ $stream ] )

read an XML element from a stream and hand it back as an array reference: element name, attributes, and child elements. the glow-up here versus read is that this method expects the stream to already be sitting at an element node ($stream->nodeType == 1) — otherwise bad things might happed (their spelling, not mine 💀) and we do not want that energy.

readAttributes( [ $stream ] )

read all XML attributes from a stream and return a hash reference — possibly empty, she's not gonna lie to you. 💜

readContent( [ $stream ] )

read all child elements of an XML element and return the result as an array reference (possibly empty again, lowkey). significant whitespace is only included if the whitespace option is enabled. 🙈

---

🎀 CONFIGURATION 🎀

from

a source to read from. and the possible values are, like, a whole menu:

• a string or string reference with XML data
• a filename
• an URL
• a file handle
• instances of XML::LibXML::Document or XML::LibXML::Element
• a hash reference with options passed to XML::LibXML::Reader

so many options and she ate every single one. 🔥

stream

a XML::LibXML::Reader to read from. if no stream has been defined, you must pass a stream parameter to the read... methods. setting a source with the from option automatically sets a stream. convenient? yes. slay? also yes.

attributes

include attributes (enabled by default, she's helpful). if you disable it, the representation of an XML element becomes this:

[ $name => \@children ]

instead of this:

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

pick your fighter. ✨

path

optional path expression, used as the default value when you call read. pathes must either be absolute (starting with "/") or consist of a single element name. the special name "*" matches all element names. 💫

a path is a very reduced form of an XPath expression — no axes, no "..", no node tests, and "//" only at the start... namespaces are not supported yet. it's giving XPath's little sister who's still in middle school. 🧚

whitespace

include ignorable whitespace as text elements. disabled by default, so if you want it, you gotta ask for it. 🌸

ns

define how XML namespaces should be processed.

by default (value "keep"), this document:

<doc>
  <x:foo xmlns:x="http://example.org/" bar="doz" />
</doc>

is transformed to this structure, keeping namespace prefixes and declarations as unprocessed element names and attributes:

[ 'doc', {}, [
    [
      'x:foo', {
          'bar' => 'doz',
          'xmlns:x' => 'http://example.org/'
      }
    ]
]

setting this option to "strip" will remove all namespace prefixes and namespace declaration attributes, so the result would be:

[ 'doc', {}, [
    [
      'foo', {
          'bar' => 'doz'
      }
    ]
]

setting this option to "disallow" results in an error when namespace prefixes or declarations are read. 🚨 so like, don't unless you mean it.

expanding namespace URIs ("expand") is not supported yet. someday maybe. not today. 💅

simple

convert XML to a simple key-value structure (SimpleXML) with XML::Struct::Simple. cute and compact, love that for you. 🍓

depth

only transform to a given depth, starting at 0 for the root node. negative values, non-numeric values, or undef are all ignored (unlimited depth is the default, she has no chill).

XML elements below the depth are converted to SimpleXML by default — or to MicroXML if the simple option is enabled. and you can configure that with the deep option. ⭐

this option is useful for instance to access document-oriented XML embedded in data oriented XML. very niche, very powerful, main character energy.

deep

how to transform elements below the given depth. heads up bestie: this option is experimental. 🔬 handle with care.

root

include the root element when converting to SimpleXML. disabled by default. 🎀

content

name of text content when converting to SimpleXML. 💖

---

and that's the whole page, bestie!! go forth and parse, you absolute icon 👑

this was perl v5.28.1, dated 2019-02-21, and it's the XML::S...:Reader(3pm) page — mwah, take care of her 💜✨