Package groovy.xml

Class MarkupBuilder

  • All Implemented Interfaces:
    groovy.lang.GroovyObject
    public class MarkupBuilder
extends groovy.util.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

    • Constructor Summary

      Constructors 
      Constructor Description
      MarkupBuilder()
      Prints markup to System.out
      MarkupBuilder​(groovy.util.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 Description
      protected java.lang.Object createNode​(java.lang.Object name)  
      protected java.lang.Object createNode​(java.lang.Object name, java.lang.Object value)  
      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)  
      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)  
      protected groovy.util.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)  
      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()

      • MarkupBuilder

        public MarkupBuilder​(java.io.PrintWriter pw)
        Sends markup to the given PrintWriter
        Parameters:
        pw - the PrintWriter to use
        See Also:
        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(Writer)

      • MarkupBuilder

        public MarkupBuilder​(groovy.util.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 groovy.util.IndentPrinter getPrinter()

      • setParent

        protected void setParent​(java.lang.Object parent,
                         java.lang.Object child)
        Specified by:
        setParent in class groovy.util.BuilderSupport

      • createNode

        protected java.lang.Object createNode​(java.lang.Object name)
        Specified by:
        createNode in class groovy.util.BuilderSupport

      • createNode

        protected java.lang.Object createNode​(java.lang.Object name,
                                      java.lang.Object value)
        Specified by:
        createNode in class groovy.util.BuilderSupport

      • createNode

        protected java.lang.Object createNode​(java.lang.Object name,
                                      java.util.Map attributes,
                                      java.lang.Object value)
        Specified by:
        createNode in class groovy.util.BuilderSupport

      • createNode

        protected java.lang.Object createNode​(java.lang.Object name,
                                      java.util.Map attributes)
        Specified by:
        createNode in class groovy.util.BuilderSupport

      • nodeCompleted

        protected void nodeCompleted​(java.lang.Object parent,
                             java.lang.Object node)
        Overrides:
        nodeCompleted in class groovy.util.BuilderSupport

      • print

        protected void print​(java.lang.Object node)

      • getName

        protected java.lang.Object getName​(java.lang.String methodName)
        Overrides:
        getName in class groovy.util.BuilderSupport