NAME

XML::Struct::Writer - Process ordered XML as stream, for instance to write XML

VERSION

version 0.05

SYNOPSIS

    use XML::Struct::Writer;

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

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

    my $writer = XML::Struct::Writer->new( attributes => 0 );
    $writer->writeDocument( [
        doc => [ 
            [ name => [ "alice" ] ],
            [ name => [ "bob" ] ],
        ] 
    ] )->serialize(1);

    # <?xml version="1.0"?>
    # <doc>
    #  <name>alice</name>
    #  <name>bob</name>
    # </doc>

DESCRIPTION

This module transforms an XML document, given as in form of a data structure as described in XML::Struct, into a stream of SAX events. By default, the stream is used to build a XML::LibXML::Document that can be used for instance to write the XML document to a file.

METHODS

write( $root ) == writeDocument( $root )

Write an XML document, given in form of its root element, to the handler. Returns the handler's result, if it support a result method.

writeElement( $element [, @more_elements ] )

Write an XML element to the handler. Note that the default handler requires to also call writeStart and writeEnd when using this method:

    $writer->writeStart( [ "root", { some => "attribute" } ] );
    $writer->writeElement( $element1 );
    $writer->writeElement( $element2, $element3 );
    ...
    $writer->writeEnd( [ "root" ] );

writeStartElement( $element )

writeEndElement( $element )

writeCharacters( $string )

writeStart( [ $root ] )

Call the handler's start_document and optionally start_element. Calling $writer->writeStart($root) is equivalent to:

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

writeEnd( [ $root ] )

Call the handler's end_document and optionally end_element. Calling $writer->writeEnd($root) is equivalent to:

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

CONFIGURATION

The handler property can be used to specify a SAX handler that XML stream events are send to. By default XML::LibXML::SAX::Builder is used to build a DOM that is serialized afterwards. Using another handler should be more performant for serialization. See XML::Writer, XML::Handler::YAWriter (and possibly XML::SAX::Writer combined with XML::Filter::SAX1toSAX2) for stream-based XML writers.

Handlers do not need to support all features of SAX. A handler is expected to implement the following methods:

start_document()

start_element( { Name => $name, Attributes => \%attributes } )

end_element( { Name => $name } )

characters( { Data => $characters } )

end_document()

If the handler further implements a result() method, it is called at the end of writeDocument.

If attributes property is set to a false value (true by default), elements are expected to be passed without attributes hash as implemented in XML::Struct::Reader.

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