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