Package: org.apache.groovy.xml.tools

## [Java] Class DomToGroovy

- org.apache.groovy.xml.tools.DomToGroovy

-     public class DomToGroovy
      extends Object

  Turns a DOM document into the MarkupBuilder calls that would produce it, as an aid to writing builder code by hand. The result is a starting point to edit rather than a finished script: names that are not valid Groovy identifiers are quoted, and the layout is meant to be read.

  The output is Groovy source. Generating it from a document and then evaluating it runs whatever that document produced, so generation belongs in authoring, not in a runtime path fed by documents the author does not control.

- - ### Field Summary

    Fields
    Modifiers | Name | Description
    --- | --- | ---
    `protected boolean` | `inMixed` | Whether the current element contains mixed text and element content.
    `protected Collection<String>` | `keywords` | Groovy keywords that must be quoted when emitted as method-style element names.
    `protected IndentPrinter` | `out` | Destination printer for the generated Groovy source.
    `protected String` | `qt` | Quote delimiter used for generated Groovy string literals.

  - ### Constructor Summary

    Constructors
    Constructor and description
    `DomToGroovy(PrintWriter out)` Creates a converter that writes generated Groovy code to the supplied writer.
    `DomToGroovy(IndentPrinter out)` Creates a converter that writes generated Groovy code with the supplied indent printer.

  - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `protected boolean` | `checkEscaping(String localName)` Returns whether a generated Groovy name must be quoted.
    `` | `protected void` | `defineNamespace(Map namespaces, String prefix, String uri)` Records a namespace mapping and emits `mkp.declareNamespace` when needed.
    `` | `protected Map` | `defineNamespaces(Element element, Map namespaces)` Returns the namespace map extended with any newly encountered element or attribute prefixes.
    `` | `protected String` | `escapeQuote(String text)` Escapes backslashes and the active quote delimiter for generated Groovy strings.
    `` | `protected String` | `escapeTripleQuote(String text)` Escapes text for a triple-quoted Groovy string literal.
    `` | `protected String` | `getAttributeValue(Attr attribute)` Returns the attribute value used when emitting the Groovy builder call.
    `` | `protected String` | `getLocalName(Node node)` Returns the trimmed local name for a DOM node, falling back to Node.getNodeName.
    `` | `protected String` | `getTextNodeData(Text node)` Returns the trimmed text content used when emitting a DOM text node.
    `` | `public static void` | `main(String[] args)` Command-line entry point that converts an XML file into a Groovy builder script.
    `` | `protected boolean` | `mixedContent(NodeList list)` Detects whether a node list contains both non-empty text and element children.
    `` | `protected static Document` | `parse(String fileName)` Parses the given XML file name into a DOM document.
    `` | `public static Document` | `parse(File file)` Parses the given XML file into a DOM document.
    `` | `public static Document` | `parse(Reader input)` Parses XML read from the supplied reader into a DOM document.
    `` | `public static Document` | `parse(InputStream input)` Parses XML read from the supplied stream into a DOM document.
    `` | `public void` | `print(Document document)` Writes the Groovy builder form of the supplied DOM document.
    `` | `protected void` | `print(Node node, Map namespaces, boolean endWithComma)` Dispatches a DOM node to the appropriate Groovy emission helper.
    `` | `protected void` | `print(String text)` Writes text through the configured indent printer.
    `` | `protected void` | `printAttributeWithPrefix(Attr attribute, StringBuffer buffer)` Appends a prefixed attribute representation to the deferred attribute buffer.
    `` | `protected boolean` | `printAttributeWithoutPrefix(Attr attribute, boolean hasAttribute)` Emits an unprefixed attribute and updates the separator state.
    `` | `protected boolean` | `printAttributes(Element element)` Emits the attributes for the supplied element.
    `` | `protected void` | `printChildren(Node parent, Map namespaces)` Emits all children of the supplied parent node.
    `` | `protected void` | `printComment(Comment comment, boolean endWithComma)` Emits a Groovy block comment for a non-empty DOM comment node.
    `` | `protected void` | `printElement(Element element, Map namespaces, boolean endWithComma)` Emits Groovy markup for a DOM element, including namespaces, attributes, and children.
    `` | `protected void` | `printEnd(String text, boolean endWithComma)` Finishes the current emitted fragment and optionally appends a comma.
    `` | `protected void` | `printIndent()` Writes the current indentation through the configured indent printer.
    `` | `protected void` | `printPI(ProcessingInstruction instruction, boolean endWithComma)` Emits a processing instruction as an `mkp.pi` call.
    `` | `protected void` | `printQuoted(String text)` Writes text as a Groovy string literal, using triple quotes for multi-line content.
    `` | `protected void` | `printText(Text node, boolean endWithComma)` Emits a text node, using `mkp.yield` when nested in mixed content.
    `` | `protected void` | `println(String text)` Writes a line through the configured indent printer.

  - ### Inherited Methods Summary

    Inherited Methods
    Methods inherited from class | Name
    --- | ---
    `class Object` | `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### protected boolean inMixed

      Whether the current element contains mixed text and element content.

    - #### protected Collection<String> keywords

      Groovy keywords that must be quoted when emitted as method-style element names.

    - #### protected IndentPrinter out

      Destination printer for the generated Groovy source.

    - #### protected String qt

      Quote delimiter used for generated Groovy string literals.

  - ### Constructor Detail

    - #### public DomToGroovy(PrintWriter out)

      Creates a converter that writes generated Groovy code to the supplied writer.

      Parameters:
        `out` - destination writer

    - #### public DomToGroovy(IndentPrinter out)

      Creates a converter that writes generated Groovy code with the supplied indent printer.

      Parameters:
        `out` - destination printer

  - ### Method Detail

    - #### protected boolean checkEscaping(String localName)

      Returns whether a generated Groovy name must be quoted.

      Parameters:
        `localName` - candidate element or attribute name
      Returns:
        `true` if the name requires quoting

    - #### protected void defineNamespace(Map namespaces, String prefix, String uri)

      Records a namespace mapping and emits `mkp.declareNamespace` when needed.

      Parameters:
        `namespaces` - mutable namespace map
        `prefix` - namespace prefix
        `uri` - namespace URI

    - #### protected Map defineNamespaces(Element element, Map namespaces)

      Returns the namespace map extended with any newly encountered element or attribute prefixes.

      Parameters:
        `element` - element whose namespaces should be inspected
        `namespaces` - namespaces currently in scope
      Returns:
        namespace map to use for the element and its children

    - #### protected String escapeQuote(String text)

      Escapes backslashes and the active quote delimiter for generated Groovy strings.

      Parameters:
        `text` - raw text
      Returns:
        escaped text

    - #### protected String escapeTripleQuote(String text)

      Escapes text for a triple-quoted Groovy string literal. A backslash always starts an escape sequence and so needs escaping; a quote needs it only where it would otherwise run into the closing delimiter, which leaves apostrophes in ordinary prose alone.

      Parameters:
        `text` - raw text
      Returns:
        escaped text

    - #### protected String getAttributeValue(Attr attribute)

      Returns the attribute value used when emitting the Groovy builder call.

      Parameters:
        `attribute` - attribute to inspect
      Returns:
        attribute value

    - #### protected String getLocalName(Node node)

      Returns the trimmed local name for a DOM node, falling back to Node.getNodeName.

      Parameters:
        `node` - DOM node
      Returns:
        trimmed local name

    - #### protected String getTextNodeData(Text node)

      Returns the trimmed text content used when emitting a DOM text node.

      Parameters:
        `node` - text node
      Returns:
        trimmed text content

    - #### public static void main(String[] args)

      Command-line entry point that converts an XML file into a Groovy builder script.

      Parameters:
        `args` - `infilename [outfilename]`

    - #### protected boolean mixedContent(NodeList list)

      Detects whether a node list contains both non-empty text and element children.

      Parameters:
        `list` - child nodes to inspect
      Returns:
        `true` for mixed content

    - #### protected static Document parse(String fileName)

      Parses the given XML file name into a DOM document.

      throws:
        Exception if parsing fails
      Parameters:
        `fileName` - XML file path
      Returns:
        parsed DOM document

    - #### public static Document parse(File file)

      Parses the given XML file into a DOM document.

      throws:
        Exception if parsing fails
      Parameters:
        `file` - XML file
      Returns:
        parsed DOM document

    - #### public static Document parse(Reader input)

      Parses XML read from the supplied reader into a DOM document.

      throws:
        Exception if parsing fails
      Parameters:
        `input` - XML reader
      Returns:
        parsed DOM document

    - #### public static Document parse(InputStream input)

      Parses XML read from the supplied stream into a DOM document.

      throws:
        Exception if parsing fails
      Parameters:
        `input` - XML stream
      Returns:
        parsed DOM document

    - #### public void print(Document document)

      Writes the Groovy builder form of the supplied DOM document.

      Parameters:
        `document` - source DOM document

    - #### protected void print(Node node, Map namespaces, boolean endWithComma)

      Dispatches a DOM node to the appropriate Groovy emission helper.

      Parameters:
        `node` - DOM node to emit
        `namespaces` - namespaces currently in scope
        `endWithComma` - whether to terminate the emitted fragment with a comma

    - #### protected void print(String text)

      Writes text through the configured indent printer.

      Parameters:
        `text` - text to print

    - #### protected void printAttributeWithPrefix(Attr attribute, StringBuffer buffer)

      Appends a prefixed attribute representation to the deferred attribute buffer.

      Parameters:
        `attribute` - attribute to render
        `buffer` - buffer collecting prefixed attributes

    - #### protected boolean printAttributeWithoutPrefix(Attr attribute, boolean hasAttribute)

      Emits an unprefixed attribute and updates the separator state.

      Parameters:
        `attribute` - attribute to render
        `hasAttribute` - whether a previous attribute has already been written
      Returns:
        updated attribute-written flag

    - #### protected boolean printAttributes(Element element)

      Emits the attributes for the supplied element.

      Parameters:
        `element` - element whose attributes should be emitted
      Returns:
        `true` if any attributes were written

    - #### protected void printChildren(Node parent, Map namespaces)

      Emits all children of the supplied parent node.

      Parameters:
        `parent` - DOM parent node
        `namespaces` - namespaces currently in scope

    - #### protected void printComment(Comment comment, boolean endWithComma)

      Emits a Groovy block comment for a non-empty DOM comment node.

      Parameters:
        `comment` - comment to emit
        `endWithComma` - whether to terminate the emitted fragment with a comma

    - #### protected void printElement(Element element, Map namespaces, boolean endWithComma)

      Emits Groovy markup for a DOM element, including namespaces, attributes, and children.

      Parameters:
        `element` - element to emit
        `namespaces` - namespaces currently in scope
        `endWithComma` - whether to terminate the emitted fragment with a comma

    - #### protected void printEnd(String text, boolean endWithComma)

      Finishes the current emitted fragment and optionally appends a comma.

      Parameters:
        `text` - trailing text to emit before line termination
        `endWithComma` - whether to append a comma

    - #### protected void printIndent()

      Writes the current indentation through the configured indent printer.

    - #### protected void printPI(ProcessingInstruction instruction, boolean endWithComma)

      Emits a processing instruction as an `mkp.pi` call.

      Parameters:
        `instruction` - processing instruction to emit
        `endWithComma` - whether to terminate the emitted fragment with a comma

    - #### protected void printQuoted(String text)

      Writes text as a Groovy string literal, using triple quotes for multi-line content.

      Parameters:
        `text` - text to quote

    - #### protected void printText(Text node, boolean endWithComma)

      Emits a text node, using `mkp.yield` when nested in mixed content.

      Parameters:
        `node` - text node to emit
        `endWithComma` - whether to terminate the emitted fragment with a comma

    - #### protected void println(String text)

      Writes a line through the configured indent printer.

      Parameters:
        `text` - line text