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
This module writes an XML document, given as XML::Struct data structure, as stream of ``SAX EVENTS''. The default handler receives these events with XML::LibXML::SAX::Builder to build a DOM tree which can then be used to serialize the XML document as string. The writer can also be used to directly serialize XML with XML::Struct::Writer::Stream.XML::Struct provides the shortcut function "writeXML" to this module.
XML elements can be passed in any of these forms and its combinations:
# 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:- to
- Filename, IO::Handle, string reference, or other kind of stream to directly serialize XML to with XML::Struct::Writer::Stream. This option is ignored if "handler" is explicitly set.
- handler
- A SAX handler to send ``SAX EVENTS'' to. If neither this option nor "to" is explicitly set, an instance of XML::LibXML::SAX::Builder is used to build a DOM.
- attributes
- Ignore XML attributes if set to false. Set to true by default.
- xmldecl
- Include 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 standalone flag in the XML declaration.
- pretty
- Pretty-print XML. Disabled by default.
METHODS
write( $root [, $name ] ) == writeDocument( $root [, $name ] )
Write an XML document, given as array reference (lax MicroXML), hash reference (SimpleXML), or both mixed. If given as hash reference, the name of a root tag can be chosen or it is 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.
writeElement( $element [, @more_elements ] )
Write one or more XML elements and their child elements to the handler.writeStart( [ $root [, $name ] ] )
Call the handler's "start_document" and "xml_decl" methods. An optional root element can be passed, so "$writer->writeStart($root)" is equivalent to:
$writer->writeStart; $writer->writeStartElement($root);
writeStartElement( $element )
Directly call the handler's "start_element" method.writeEndElement( $element )
Directly call the handler's "end_element" method.writeCharacters( $string )
Directy call the handler's "characters" method.writeEnd( [ $root ] )
Directly call the handler's "end_document" method. An optional root element can be passed, so "$writer->writeEnd($root)" is equivalent to:
$writer->writeEndElement($root); $writer->writeEnd;
microXML( $element [, $name ] )
Convert an XML element, given as array reference (lax MicroXML) or as hash reference (SimpleXML) to a list of MicroXML elements and optionally remove attributes. Does not affect child elements.SAX EVENTS
A SAX handler, set with option "handler", is expected to implement the following methods (two of them are optional):- xml_decl( { Version => $version, Encoding => $encoding } )
- Optionally called once at the start of an XML document, if the handler supports this method.
- 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 section 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 methods. Handlers do not need to implement this method.