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

✨ NAME ✨

XML::Struct::Writer — bestie, this lil module writes XML data structures out to XML streams 💖 (it's the <pink>XML::Struct::Writer</pink> page from the User Contributed Perl Documentation, hey queen 👑)

---

🌸 SYNOPSIS 🌸

use XML::Struct::Writer;

# serialize
XML::Struct::Writer->new(
    to => \*STDOUT,
    attributes => 0,
    pretty => 1,
)->write( [
    doc => [
        [ name => [ "alice" ] ],
        [ name => [ "bob" ] ],
    ]
] );

# <?xml version="1.0" encoding="UTF-8"?>
# <doc>
#  <name>alice</name>
#  <name>bob</name>
# </doc>

# create DOM
my $xml = XML::Struct::Writer->new->write( [
    greet => { }, [
        "Hello, ",
        [ emph => { color => "blue" } , [ "World" ] ],
        "!"
    ]
] );
$xml->toFile("greet.xml");

# <?xml version="1.0" encoding="UTF-8"?>
# <greet>Hello, <emph color="blue">World</emph>!</greet>

---

💅 DESCRIPTION 💅

So basically ✨ this module takes an XML document (handed to it as an XML::Struct data structure) and writes it out as a stream of "SAX EVENTS". The default handler catches all those events with XML::LibXML::SAX::Builder and builds you a DOM tree, which you can then use to serialize the XML document as a string. Obsessed. And if you want, the writer can also serialize XML directly with XML::Struct::Writer::Stream 🦋

XML::Struct is out here providing the shortcut function writeXML to this module, iykyk.

XML elements can be passed in any of these forms and combos of them, no cap:

# MicroXML:

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

 [ $name => \%attributes ]

 [ $name ]

# lax MicroXML also:

 [ $name => \@children ]

# SimpleXML:

 { $name => \@children, $name => $content,  ... }

---

🎀 CONFIGURATION 🎀

A XML::Struct::Writer can be configured with the following options, bestie, take notes 📝:

• to — a filename, an IO::Handle, a string reference, or literally any other kind of stream you wanna serialize XML directly into with XML::Struct::Writer::Stream. Heads up tho: this option gets ignored if "handler" is explicitly set. Periodt.
• handler — a SAX handler to send those "SAX EVENTS" to. If you don't explicitly set this option or "to", then an instance of XML::LibXML::SAX::Builder is used to build a DOM. Default behavior, slay.
• attributes — ignore XML attributes if this is set to false. It's set to true by default 💖
• xmldecl — include the XML declaration on serialization. Enabled by default ✨
• encoding — an encoding, for handlers that support an explicit encoding. Set to UTF-8 by default 🌈
• version — the XML version. Set to 1.0 by default.
• standalone — add the standalone flag in the XML declaration.
• pretty — pretty-print XML. Disabled by default. (Turn it on and watch it eat 💅)

---

👑 METHODS 👑

write( $root [, $name ] ) == writeDocument( $root [, $name ] )

Write an XML document, given as an array reference (lax MicroXML), a hash reference (SimpleXML), or both mixed together like a lil smoothie 🍓 If it's given as a hash reference, you can choose the name of a root tag, or else it just gets set to "root". This method is basically equivalent to:

$writer->writeStart;
$writer->writeElement(
    $writer->microXML($root, $name // 'root')
);
$writer->writeEnd;
$writer->result if $writer->can('result');

⚠️ The remaining methods expect XML in MicroXML format only. No SimpleXML up in here, bestie.

---

writeElement( $element [, @more_elements ] )

Write one or more XML elements, plus their child elements, to the handler. Go off ✨

---

writeStart( [ $root [, $name ] ] )

Call the handler's "start_document" and "xml_decl" methods. You can pass an optional root element too, so "$writer->writeStart($root)" is equivalent to:

$writer->writeStart;
$writer->writeStartElement($root);

---

writeStartElement( $element )

Directly call the handler's "start_element" method. No middleman, we love efficiency 💜

---

writeEndElement( $element )

Directly call the handler's "end_element" method. Bye bestie 👋

---

writeCharacters( $string )

Directy call the handler's "characters" method. (Yes, the original says "Directy" — iconic typo, we keep it, no cap.)

---

writeEnd( [ $root ] )

Directly call the handler's "end_document" method. You can pass an optional root element, so "$writer->writeEnd($root)" is equivalent to:

$writer->writeEndElement($root);
$writer->writeEnd;

---

microXML( $element [, $name ] )

Convert an XML element — given as an array reference (lax MicroXML) or as a hash reference (SimpleXML) — into a list of MicroXML elements, and optionally remove attributes. It does not touch child elements. Leave the kids alone fr fr 🙈

---

🦋 SAX EVENTS 🦋

A SAX handler, set with the option "handler", is expected to implement the following methods — and listen, two of them are optional so don't stress:

• xml_decl( { Version => $version, Encoding => $encoding } ) — optionally called once at the start of an XML document, but only if the handler supports this method. Optional girly ✨
• start_document() — called once at the start of an XML document.
• start_element( { Name => $name, Attributes => \%attributes } ) — called at the start of an XML element to emit an XML start tag.
• end_element( { Name => $name } ) — called at the end of an XML element to emit an XML end tag.
• characters( { Data => $characters } ) — called for character data. Character entities and CDATA sections are expanded to strings. 💖
• end_document() — called once at the end of an XML document.
• result() — optionally called at the end of "write"/"writeDocument" to return a value from this method. Handlers do not need to implement this method. Optional again, we stay flexible 😌

---

🌈 SEE ALSO 🌈

Using a streaming SAX handler — like XML::SAX::Writer, XML::Genx::SAXWriter, XML::Handler::YAWriter, and possibly XML::Writer — should be more performant for serialization. Main character energy, honestly. And if you wanna see examples of other modules that receive SAX events, go check out XML::STX, XML::SAX::SimpleDispatcher, and XML::SAX::Machines, (yes the comma is in the original, we're keeping it, it's canon 🎀).

---

Okay that's the whole page bestie, you ate it up 💅 This lil baddie is perl v5.28.1, dated 2019-02-21, and it lives in XML::Struct::Writer(3pm) — go forth and serialize, queen 👑💖