NAME

XML::Struct::Writer - Write XML data structures to XML streams

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.