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>

  Note 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 such as 'yield' and 'yieldUnescaped'. See the javadoc for `getMkp()` for further details.
  Version:
    $Revision: 21453 $
  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(PrintWriter pw)` Sends markup to the given PrintWriter
    `MarkupBuilder(Writer writer)` Sends markup to the given Writer but first wrapping it in a PrintWriter

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected Object` | `createNode(Object name)`
    `protected Object` | `createNode(Object name, Map attributes)`
    `protected Object` | `createNode(Object name, Map attributes, Object value)`
    `protected Object` | `createNode(Object name, Object value)`
    `boolean` | `getDoubleQuotes()` Returns `true` if attribute values are output with double quotes; `false` if single quotes are used.
    `Object` | `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 Object` | `getName(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` | `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(Object parent, Object node)` A hook to allow nodes to be processed once they have had all of their children applied.
    `protected void` | `print(Object node)`
    `void` | `setDoubleQuotes(boolean useDoubleQuotes)` Sets whether the builder outputs attribute values in double quotes or single quotes.
    `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(Object parent, Object child)`
    `protected String` | `transformValue(String value)` Deprecated.

    - ### 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(PrintWriter pw)

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

    - #### MarkupBuilder

          public MarkupBuilder(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

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

    - #### getPrinter

          protected IndentPrinter getPrinter()

    - #### setParent

          protected void setParent(Object parent,
                       Object child)

      Specified by:
        `setParent` in class `BuilderSupport`

    - #### getMkp

          public Object 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 Object createNode(Object name)

      Specified by:
        `createNode` in class `BuilderSupport`

    - #### createNode

          protected Object createNode(Object name,
                          Object value)

      Specified by:
        `createNode` in class `BuilderSupport`

    - #### createNode

          protected Object createNode(Object name,
                          Map attributes,
                          Object value)

      Specified by:
        `createNode` in class `BuilderSupport`

    - #### createNode

          protected Object createNode(Object name,
                          Map attributes)

      Specified by:
        `createNode` in class `BuilderSupport`

    - #### nodeCompleted

          protected void nodeCompleted(Object parent,
                           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(Object node)

    - #### getName

          protected Object getName(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

    - #### transformValue

          protected String transformValue(String value)

      Deprecated.
      Returns a String with special XML characters escaped as entities so that output XML is valid. Escapes the following characters as corresponding entities:
      - \' as &apos;
      - & as &amp;
      - < as &lt;
      - > as &gt;
      Parameters:
        `value` - to be searched and replaced for XML special characters.
      Returns:
        value with XML characters escaped
      See Also:
        `escapeXmlValue(String, boolean)`