Package 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

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static enum`
  `MarkupBuilder.CharFilter`
  Identifiers for built-in character filtering strategies.
  `static class`
  `MarkupBuilder.DefaultXmlEscapingFunction`
  Default character replacement function used for XML content and attribute escaping.

- ## Constructor Summary

  Constructors
  Constructor
  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

  Modifier and Type
  Method
  Description
  `protected Object`
  `createNode(Object name)`
  Builder lifecycle callback that starts an element with no attributes or body text.
  `protected Object`
  `createNode(Object name, Object value)`
  Builder lifecycle callback that starts an element and writes an immediate text body.
  `protected Object`
  `createNode(Object name, Map attributes)`
  Builder lifecycle callback that starts an element and emits attributes without body text.
  `protected Object`
  `createNode(Object name, Map attributes, Object value)`
  Builder lifecycle callback that starts an element, emits attributes and optionally writes text.
  `List<Function<Character,Optional<String>>>`
  `getAdditionalFilters()`
  Returns extra character replacement filters consulted after the default XML escaping rules.
  `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 Object`
  `getName(String methodName)`
  Resolves a builder method name to the element name that should be emitted.
  `protected IndentPrinter`
  `getPrinter()`
  Returns the printer used to emit markup.
  `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(Object parent, Object node)`
  Builder lifecycle callback invoked when the current node is complete.
  `protected void`
  `print(Object node)`
  Writes raw markup fragments or names to the output stream.
  `void`
  `setAdditionalFilters(List<Function<Character,Optional<String>>> additionalFilters)`
  Sets extra character replacement filters consulted after the default XML escaping rules.
  `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(Object parent, Object child)`
  Builder lifecycle callback invoked after a child node has been created.

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

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

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

  `getMetaClass, setMetaClass`

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

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

  ### Methods inherited from interface groovy.lang.GroovyObject

  `getProperty, setProperty`

- ## Constructor Details

  - ### MarkupBuilder

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

  - ### MarkupBuilder

    public MarkupBuilder(PrintWriter pw)
    Sends markup to the given PrintWriter
    Parameters:
      `pw` - the PrintWriter to use
    See Also:
      - `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(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 Details

  - ### getAdditionalFilters

    public List<Function<Character,Optional<String>>> getAdditionalFilters()
    Returns extra character replacement filters consulted after the default XML escaping rules.
    Returns:
      the additional escaping filters, or `null` if none are configured

  - ### setAdditionalFilters

    public void setAdditionalFilters(List<Function<Character,Optional<String>>> additionalFilters)
    Sets extra character replacement filters consulted after the default XML escaping rules.
    Parameters:
      `additionalFilters` - the additional escaping filters to apply

  - ### 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()
    Returns the printer used to emit markup. Subclasses may override to provide a custom output sink.
    Returns:
      the printer backing this builder

  - ### setParent

    protected void setParent(Object parent, Object child)
    Builder lifecycle callback invoked after a child node has been created. This implementation is a no-op because markup is streamed directly to the printer.
    Specified by:
      `setParent` in class `BuilderSupport`
    Parameters:
      `parent` - the current parent node marker
      `child` - the newly created child node marker

  - ### 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 Object createNode(Object name)
    Builder lifecycle callback that starts an element with no attributes or body text.
    Specified by:
      `createNode` in class `BuilderSupport`
    Parameters:
      `name` - the node name requested by the builder
    Returns:
      the normalized node name used for subsequent callbacks

  - ### createNode

    protected Object createNode(Object name, Object value)
    Builder lifecycle callback that starts an element and writes an immediate text body.
    Specified by:
      `createNode` in class `BuilderSupport`
    Parameters:
      `name` - the node name requested by the builder
      `value` - the text body to emit, or `null` to leave the element empty
    Returns:
      the normalized node name used for subsequent callbacks

  - ### createNode

    protected Object createNode(Object name, Map attributes, Object value)
    Builder lifecycle callback that starts an element, emits attributes and optionally writes text.
    Specified by:
      `createNode` in class `BuilderSupport`
    Parameters:
      `name` - the node name requested by the builder
      `attributes` - the attributes to emit
      `value` - the optional text body to emit
    Returns:
      the normalized node name used for subsequent callbacks

  - ### createNode

    protected Object createNode(Object name, Map attributes)
    Builder lifecycle callback that starts an element and emits attributes without body text.
    Specified by:
      `createNode` in class `BuilderSupport`
    Parameters:
      `name` - the node name requested by the builder
      `attributes` - the attributes to emit
    Returns:
      the normalized node name used for subsequent callbacks

  - ### nodeCompleted

    protected void nodeCompleted(Object parent, Object node)
    Builder lifecycle callback invoked when the current node is complete.
    Overrides:
      `nodeCompleted` in class `BuilderSupport`
    Parameters:
      `parent` - the parent node marker
      `node` - the completed node marker

  - ### print

    protected void print(Object node)
    Writes raw markup fragments or names to the output stream. Subclasses may override to customize low-level emission.
    Parameters:
      `node` - the value to print

  - ### getName

    protected Object getName(String methodName)
    Resolves a builder method name to the element name that should be emitted. Subclasses may override to translate method names into alternate node names.
    Overrides:
      `getName` in class `BuilderSupport`
    Parameters:
      `methodName` - the method name invoked on the builder
    Returns:
      the node name to use for output