---
name: "XML::Struct::Writer"
section: "3pm"
platform: "linux"
package: "libxml-struct-perl"
version: "0.27-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/XML::Struct::Writer"
---

# XML::Struct::Writer(3pm)

Write XML data structures to XML streams

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