NAME

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

VERSION

version 0.14

SYNOPSIS

    use XML::Struct::Writer;

    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>

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

    # <?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 ) == writeDocument( $root )

Write an XML document, given in form of its root element, to the handler. If the handler implements a result() method, it 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 ] )

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

handler

Specify a SAX handler that "SAX EVENTS" are send to.

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 ]

encoding

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

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 Voß

COPYRIGHT AND LICENSE

This software is copyright (c) 2013 by Jakob Voß.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm XML::Struct

perl -MCPAN -e shell
install XML::Struct