Package: groovy.xml

## [Groovy] Class StreamingMarkupBuilder

- groovy.xml.StreamingMarkupBuilder

-     @SuppressWarnings(value="Instanceof")
      class StreamingMarkupBuilder
      extends AbstractStreamingBuilder

  A builder class for creating XML markup. This implementation uses a StreamingMarkupWriter to handle output.

  Example:

      System.out << new StreamingMarkupBuilder().bind {
         root {
           a( a1:'one' ) {
             b { mkp.yield( '3 < 5' ) }
             c( a2:'two', 'blah' )
           }
         }
       }

  Will output the following String, without newlines or indentation:

      <root>
         <a a1='one'>
           <b>3 &lt; 5</b>
           <c a2='two'>blah</c>
         </a>
       </root>

  Notes:
  - that `mkp` is a special namespace used to escape away from the normal building mode of the builder and get access to helper markup methods 'yield', 'pi', 'comment', 'out', 'namespaces', 'xmlDeclaration' and 'yieldUnescaped'.
  - Note that tab, newline and carriage return characters are escaped within attributes, i.e. will become , and respectively

- - ### Properties Summary

    Properties
    Type | Name and description
    --- | ---
    `Object` | `builder` Backing namespace-aware builder reused for each bind(Closure) call.
    `Object` | `commentClosure` Invoked by calling `mkp.comment`
    `Object` | `declarationClosure` Invoked by calling `mkp.xmlDeclaration`
    `Object` | `encoding` Optional encoding snapshot applied when bound markup is later written.
    `boolean` | `expandEmptyElements` Whether empty elements are rendered as explicit start/end pairs instead of empty-element tags.
    `Object` | `noopClosure` Invoked by calling `mkp.yield`.
    `Object` | `pendingStack` Stack of namespace declarations suspended while nested elements are rendered.
    `Object` | `piClosure` Invoked by calling `mkp.pi`
    `Object` | `tagClosure` Default element-emitting closure used for ordinary builder nodes.
    `Object` | `unescapedClosure` Invoked by calling `mkp.yieldUnescaped`.
    `boolean` | `useDoubleQuotes` Whether generated XML prefers double quotes when quoting attributes and declarations.

  - Inherited properties
    Properties inherited from class | Properties
    --- | ---
    `class AbstractStreamingBuilder` | `aliasSetupClosure, badTagClosure, builder, checkCommentText, checkProcessingInstruction, getNamespaceClosure, namespaceSetupClosure, specialTags, toMapStringClosure`

  - ### Constructor Summary

    Constructors
    Constructor and description
    `StreamingMarkupBuilder()` Creates a streaming markup builder with the standard `mkp` helper tags installed.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `Object` | `bind(Object closure)` Returns a Writable object, which may be used to render the markup directly to a String, or send the output to a stream.
    `` | `Object` | `bindNode(Object node)` Convenience method for binding a single node.
    `` | `Object` | `getQt()` Returns the quote character currently preferred for generated XML.

- - ### Property Detail

    - #### Object builder

      Backing namespace-aware builder reused for each bind(Closure) call.

    - #### Object commentClosure

      Invoked by calling `mkp.comment`

    - #### Object declarationClosure

      Invoked by calling `mkp.xmlDeclaration`

    - #### Object encoding

      Optional encoding snapshot applied when bound markup is later written.

    - #### boolean expandEmptyElements

      Whether empty elements are rendered as explicit start/end pairs instead of empty-element tags.

    - #### Object noopClosure

      Invoked by calling `mkp.yield`. Used to render text to the output stream. Any XML reserved characters will be escaped to ensure well-formedness.

    - #### Object pendingStack

      Stack of namespace declarations suspended while nested elements are rendered.

    - #### Object piClosure

      Invoked by calling `mkp.pi`

    - #### Object tagClosure

      Default element-emitting closure used for ordinary builder nodes.

    - #### Object unescapedClosure

      Invoked by calling `mkp.yieldUnescaped`. Used to render literal text or markup to the output stream. No escaping is done on the output.

    - #### boolean useDoubleQuotes

      Whether generated XML prefers double quotes when quoting attributes and declarations.

  - ### Constructor Detail

    - #### StreamingMarkupBuilder()

      Creates a streaming markup builder with the standard `mkp` helper tags installed.

  - ### Method Detail

    - #### Object bind(Object closure)

      Returns a Writable object, which may be used to render the markup directly to a String, or send the output to a stream.

      Examples:

           // get the markup as a string:
           new StreamingMarkupBuilder().bind { div { out << 'hello world' } }.toString()

           // send the output directly to a file:
           new StreamingMarkupBuilder().bind {
               div { out << 'hello world' }
           }.writeTo( new File('myFile.xml').newWriter() )

      Parameters:
        `closure` - closure describing the XML to generate
      Returns:
        a Writable to render the markup

    - #### Object bindNode(Object node)

      Convenience method for binding a single node. The call `bindNode(node)` is equivalent to `bind{ out << node }`. Returns a Writable object, which may be used to render the markup directly to a String, or send the output to a stream.

      See Also:
        bind(Closure)
      Parameters:
        `node` - node or value to write through the builder
      Returns:
        a Writable to render the markup

    - #### Object getQt()

      Returns the quote character currently preferred for generated XML.

      Returns:
        the quote character string