/ 
XML-Struct-0.03
River stage two • 6 direct dependents • 19 total dependents
⭐ Starred 2 GitHub stars
/ XML::Struct::Writer

NAME

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

VERSION

version 0.03

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.