NAME¶

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

VERSION¶

version 0.23

SYNOPSIS¶

    use XML::Struct::Writer;
    # 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>
    # serialize
    XML::Struct::Writer->new(
        attributes => 0,
        pretty => 1,
        to => \*STDOUT,
    )->write( [
        doc => [ 
            [ name => [ "alice" ] ],
            [ name => [ "bob" ] ],
        ] 
    ] );
    # <?xml version="1.0" encoding="UTF-8"?>
    # <doc>
    #  <name>alice</name>
    #  <name>bob</name>
    # </doc>

DESCRIPTION¶

This module writes an XML document, given as XML::Struct data structure. XML::Struct::Writer can act as SAX event generator that sequentially sends "SAX EVENTS" to a SAX handler. The default handler XML::LibXML::SAX::Builder creates XML::LibXML::Document that can be used to serialize the XML document as string.

METHODS¶

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

Write an XML document, given in form of its root element as array reference (MicroXML) or in simple format as hash reference with an optional root element name (simpleXML). The handler's "result" method, if implemented, is used to get a return value. For most applications this is the only method one needs to care about. If the XML document to be written is not fully given as root element, one has to directly call the following methods. This method is basically equivalent to:

    $writer->writeStart;
    $writer->writeElement($root);
    $writer->writeEnd;
    $writer->result if $writer->can('result');

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);

writeElement( $element [, @more_elements ] )¶

Write one or more XML elements, including their child elements, to the handler.

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;

CONFIGURATION¶

attributes

Set to true by default to expect attribute hashes in the XML::Struct input format. If set to false, XML elements must be passed as

    [ $name => \@children ]
    

instead of

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

Do not set this to false when serializing simple xml in form of hashes!

encoding

Sets the encoding for handlers that support an explicit encoding. Set to UTF-8 by default.

version

Sets the XML version (1.0 by default).

xmldecl

Include XML declaration on serialization. Enabled by default.

standalone

Add standalone flag in the XML declaration.

to

Filename, IO::Handle, or other kind of stream to serialize XML to.

handler

Specify a SAX handler that "SAX EVENTS" are send to. Automatically set to an instance of XML::Struct::Writer::Stream if option "to" has been specified or to an instance of XML::LibXML::SAX::Builder otherwise.

SAX EVENTS¶

A SAX handler, as used by this module, 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.

SEE ALSO¶

Using a streaming SAX handler, such as XML::SAX::Writer, XML::Genx::SAXWriter, XML::Handler::YAWriter, and possibly XML::Writer should be more performant for serialization. Examples of other modules that receive SAX events include XML::STX, XML::SAX::SimpleDispatcher, and XML::SAX::Machines,

AUTHOR¶

Jakob Voss

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.