oracular (3) XML::Struct::Writer.3pm.gz

NAME

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

SYNOPSIS

           use XML::Struct::Writer;

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

           # <?xml version="1.0" encoding="UTF-8"?>
           # <doc>
           #  <name>alice</name>
           #  <name>bob</name>
           # </doc>

           # 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>

DESCRIPTION

       This module writes an XML document, given as XML::Struct data structure, as stream of "SAX EVENTS". The
       default handler receives these events with XML::LibXML::SAX::Builder to build a DOM tree which can then
       be used to serialize the XML document as string.  The writer can also be used to directly serialize XML
       with XML::Struct::Writer::Stream.

       XML::Struct provides the shortcut function "writeXML" to this module.

       XML elements can be passed in any of these forms and its combinations:

           # MicroXML:

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

            [ $name => \%attributes ]

            [ $name ]

           # lax MicroXML also:

            [ $name => \@children ]

           # SimpleXML:

            { $name => \@children, $name => $content,  ... }

CONFIGURATION

       A XML::Struct::Writer can be configured with the following options:

       to  Filename, IO::Handle, string reference, or other kind of stream to directly serialize XML to with
           XML::Struct::Writer::Stream. This option is ignored if "handler" is explicitly set.

       handler
           A SAX handler to send "SAX EVENTS" to. If neither this option nor "to" is explicitly set, an instance
           of XML::LibXML::SAX::Builder is used to build a DOM.

       attributes
           Ignore XML attributes if set to false. Set to true by default.

       xmldecl
           Include XML declaration on serialization. Enabled by default.

       encoding
           An encoding (for handlers that support an explicit encoding). Set to UTF-8 by default.

       version
           The XML version. Set to 1.0 by default.

       standalone
           Add standalone flag in the XML declaration.

       pretty
           Pretty-print XML. Disabled by default.

METHODS

   write( $root [, $name ] ) == writeDocument( $root [, $name ] )
       Write an XML document, given as array reference (lax MicroXML), hash reference (SimpleXML), or both
       mixed. If given as hash reference, the name of a root tag can be chosen or it is set to "root". This
       method is basically equivalent to:

           $writer->writeStart;
           $writer->writeElement(
               $writer->microXML($root, $name // 'root')
           );
           $writer->writeEnd;
           $writer->result if $writer->can('result');

       The remaining methods expect XML in MicroXML format only.

   writeElement( $element [, @more_elements ] )
       Write one or more XML elements and their child elements to the handler.

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

   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;

   microXML( $element [, $name ] )
       Convert an XML element, given as array reference (lax MicroXML) or as hash reference (SimpleXML) to a
       list of MicroXML elements and optionally remove attributes. Does not affect child elements.

SAX EVENTS

       A SAX handler, set with option "handler", 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,