groovy.xml

## Class MarkupBuilder

- java.lang.Object
- - groovy.lang.GroovyObjectSupport
  - - groovy.util.BuilderSupport
    - - groovy.xml.MarkupBuilder

- All Implemented Interfaces:
    GroovyObject

      public class MarkupBuilder
      extends BuilderSupport

  A helper class for creating XML or HTML markup. The builder supports various 'pretty printed' formats.

  Example:

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

  Will print the following to System.out:

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

  Notes:
  - `mkp` is a special namespace used to escape away from the normal building mode of the builder and get access to helper markup methods such as 'yield' and 'yieldUnescaped'. See the javadoc for `getMkp()` for further details.
  - Note that tab, newline and carriage return characters are escaped within attributes, i.e. will become &#09;, &#10; and &#13; respectively
  Author:
    James Strachan, Stefan Matthias Aust, Scott Stirling, Paul King

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `MarkupBuilder()` Prints markup to System.out
    `MarkupBuilder(IndentPrinter out)` Sends markup to the given IndentPrinter.
    `MarkupBuilder(java.io.PrintWriter pw)` Sends markup to the given PrintWriter
    `MarkupBuilder(java.io.Writer writer)` Sends markup to the given Writer but first wrapping it in a PrintWriter

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected java.lang.Object` | `createNode(java.lang.Object name)`
    `protected java.lang.Object` | `createNode(java.lang.Object name, java.util.Map attributes)`
    `protected java.lang.Object` | `createNode(java.lang.Object name, java.util.Map attributes, java.lang.Object value)`
    `protected java.lang.Object` | `createNode(java.lang.Object name, java.lang.Object value)`
    `boolean` | `getDoubleQuotes()` Returns `true` if attribute values are output with double quotes; `false` if single quotes are used.
    `MarkupBuilderHelper` | `getMkp()` Property that may be called from within your builder closure to access helper methods, namely `MarkupBuilderHelper.yield(String)`, `MarkupBuilderHelper.yieldUnescaped(String)`, `MarkupBuilderHelper.pi(Map)`, `MarkupBuilderHelper.xmlDeclaration(Map)` and `MarkupBuilderHelper.comment(String)`.
    `protected java.lang.Object` | `getName(java.lang.String methodName)` A hook to allow names to be converted into some other object such as a QName in XML or ObjectName in JMX.
    `protected IndentPrinter` | `getPrinter()`
    `boolean` | `isEscapeAttributes()` Returns the escapeAttributes property value.
    `boolean` | `isExpandEmptyElements()` Whether empty elements are expanded from <tagName/> to <tagName></tagName>.
    `boolean` | `isOmitEmptyAttributes()` Determine whether empty attributes will appear in the produced markup.
    `boolean` | `isOmitNullAttributes()` Determine whether null attributes will appear in the produced markup.
    `protected void` | `nodeCompleted(java.lang.Object parent, java.lang.Object node)` A hook to allow nodes to be processed once they have had all of their children applied.
    `protected void` | `print(java.lang.Object node)`
    `void` | `setDoubleQuotes(boolean useDoubleQuotes)` Sets whether the builder outputs attribute values in double quotes or single quotes.
    `void` | `setEscapeAttributes(boolean escapeAttributes)` Defaults to true. If set to false then you must escape any special characters within attribute values such as '&', '<', CR/LF, single and double quotes etc. manually as needed.
    `void` | `setExpandEmptyElements(boolean expandEmptyElements)` Whether empty elements are expanded from <tagName/> to <tagName></tagName>.
    `void` | `setOmitEmptyAttributes(boolean omitEmptyAttributes)` Allows empty attributes to be removed from the generated markup.
    `void` | `setOmitNullAttributes(boolean omitNullAttributes)` Allows null attributes to be removed from the generated markup.
    `protected void` | `setParent(java.lang.Object parent, java.lang.Object child)`

    - ### Methods inherited from class groovy.util.BuilderSupport

      `doInvokeMethod, getCurrent, invokeMethod, invokeMethod, postNodeCompletion, setClosureDelegate, setCurrent`

    - ### Methods inherited from class groovy.lang.GroovyObjectSupport

      `getMetaClass, getProperty, setMetaClass, setProperty`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### MarkupBuilder

          public MarkupBuilder()

      Prints markup to System.out
      See Also:
        `IndentPrinter.IndentPrinter()`

    - #### MarkupBuilder

          public MarkupBuilder(java.io.PrintWriter pw)

      Sends markup to the given PrintWriter
      Parameters:
        `pw` - the PrintWriter to use
      See Also:
        `IndentPrinter.IndentPrinter(Writer)`

    - #### MarkupBuilder

          public MarkupBuilder(java.io.Writer writer)

      Sends markup to the given Writer but first wrapping it in a PrintWriter
      Parameters:
        `writer` - the writer to use
      See Also:
        `IndentPrinter.IndentPrinter(Writer)`

    - #### MarkupBuilder

          public MarkupBuilder(IndentPrinter out)

      Sends markup to the given IndentPrinter. Use this option if you want to customize the indent used or provide your own IndentPrinter.
      Parameters:
        `out` - the IndentPrinter to use

  - ### Method Detail

    - #### isEscapeAttributes

          public boolean isEscapeAttributes()

      Returns the escapeAttributes property value.
      Returns:
        the escapeAttributes property value
      See Also:
        `setEscapeAttributes(boolean)`

    - #### setEscapeAttributes

          public void setEscapeAttributes(boolean escapeAttributes)

      Defaults to true. If set to false then you must escape any special characters within attribute values such as '&', '<', CR/LF, single and double quotes etc. manually as needed. The builder will not guard against producing invalid XML when in this mode and the output may not be able to be parsed/round-tripped but it does give you full control when producing for instance HTML output.
      Parameters:
        `escapeAttributes` - the new value

    - #### getDoubleQuotes

          public boolean getDoubleQuotes()

      Returns `true` if attribute values are output with double quotes; `false` if single quotes are used. By default, single quotes are used.
      Returns:
        true if double quotes are used for attributes

    - #### setDoubleQuotes

          public void setDoubleQuotes(boolean useDoubleQuotes)

      Sets whether the builder outputs attribute values in double quotes or single quotes.
      Parameters:
        `useDoubleQuotes` - If this parameter is `true`, double quotes are used; otherwise, single quotes are.

    - #### isOmitNullAttributes

          public boolean isOmitNullAttributes()

      Determine whether null attributes will appear in the produced markup.
      Returns:
        `true`, if null attributes will be removed from the resulting markup.

    - #### setOmitNullAttributes

          public void setOmitNullAttributes(boolean omitNullAttributes)

      Allows null attributes to be removed from the generated markup.
      Parameters:
        `omitNullAttributes` - if `true`, null attributes will not be included in the resulting markup. If `false` null attributes will be included in the markup as empty strings regardless of the omitEmptyAttribute setting. Defaults to `false`.

    - #### isOmitEmptyAttributes

          public boolean isOmitEmptyAttributes()

      Determine whether empty attributes will appear in the produced markup.
      Returns:
        `true`, if empty attributes will be removed from the resulting markup.

    - #### setOmitEmptyAttributes

          public void setOmitEmptyAttributes(boolean omitEmptyAttributes)

      Allows empty attributes to be removed from the generated markup.
      Parameters:
        `omitEmptyAttributes` - if `true`, empty attributes will not be included in the resulting markup. Defaults to `false`.

    - #### isExpandEmptyElements

          public boolean isExpandEmptyElements()

      Whether empty elements are expanded from <tagName/> to <tagName></tagName>.
      Returns:
        `true`, if empty elements will be represented by an opening tag followed immediately by a closing tag.

    - #### setExpandEmptyElements

          public void setExpandEmptyElements(boolean expandEmptyElements)

      Whether empty elements are expanded from <tagName/> to <tagName></tagName>.
      Parameters:
        `expandEmptyElements` - if `true`, empty elements will be represented by an opening tag followed immediately by a closing tag. Defaults to `false`.

    - #### getPrinter

          protected IndentPrinter getPrinter()

    - #### setParent

          protected void setParent(java.lang.Object parent,
                                   java.lang.Object child)

      Specified by:
        `setParent` in class `BuilderSupport`

    - #### getMkp

          public MarkupBuilderHelper getMkp()

      Property that may be called from within your builder closure to access helper methods, namely `MarkupBuilderHelper.yield(String)`, `MarkupBuilderHelper.yieldUnescaped(String)`, `MarkupBuilderHelper.pi(Map)`, `MarkupBuilderHelper.xmlDeclaration(Map)` and `MarkupBuilderHelper.comment(String)`.
      Returns:
        this MarkupBuilder

    - #### createNode

          protected java.lang.Object createNode(java.lang.Object name)

      Specified by:
        `createNode` in class `BuilderSupport`

    - #### createNode

          protected java.lang.Object createNode(java.lang.Object name,
                                                java.lang.Object value)

      Specified by:
        `createNode` in class `BuilderSupport`

    - #### createNode

          protected java.lang.Object createNode(java.lang.Object name,
                                                java.util.Map attributes,
                                                java.lang.Object value)

      Specified by:
        `createNode` in class `BuilderSupport`

    - #### createNode

          protected java.lang.Object createNode(java.lang.Object name,
                                                java.util.Map attributes)

      Specified by:
        `createNode` in class `BuilderSupport`

    - #### nodeCompleted

          protected void nodeCompleted(java.lang.Object parent,
                                       java.lang.Object node)

      Description copied from class: `BuilderSupport`
      A hook to allow nodes to be processed once they have had all of their children applied.
      Overrides:
        `nodeCompleted` in class `BuilderSupport`
      Parameters:
        `parent` - the parent of the node being processed
        `node` - the current node being processed

    - #### print

          protected void print(java.lang.Object node)

    - #### getName

          protected java.lang.Object getName(java.lang.String methodName)

      Description copied from class: `BuilderSupport`
      A hook to allow names to be converted into some other object such as a QName in XML or ObjectName in JMX.
      Overrides:
        `getName` in class `BuilderSupport`
      Parameters:
        `methodName` - the name of the desired method
      Returns:
        the object representing the name