++ed by:
EGOR SSCAFFIDI TOBYINK

3 PAUSE user(s)
1 non-PAUSE user(s).

Jakob Voß

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

COPYRIGHT AND LICENSE

This software is copyright (c) 2014 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.




Hosting generously
sponsored by Bytemark