Package: groovy.xml.dom

## [Java] Class DOMCategory

- groovy.xml.dom.DOMCategory

-     public class DOMCategory
      extends Object

  Category class which adds GPath style operations to Java's DOM classes. These helpers provide property access, traversal, mutation, and XPath support for W3C DOM nodes in a style similar to Groovy's XML slurper APIs.

- - ### Methods Summary

    Methods
    Type Params | Return Type | Name and description
    --- | --- | ---
    `` | `public static Element` | `appendNode(Element self, Object name)` Appends a child element with the given name.
    `` | `public static Element` | `appendNode(Element self, Object name, Map attributes)` Appends a child element with the given name and attributes.
    `` | `public static Element` | `appendNode(Element self, Object name, String value)` Appends a child element with the given name and optional text value.
    `` | `public static Element` | `appendNode(Element self, Object name, Map attributes, String value)` Appends a child element with attributes and optional text content.
    `` | `public static NamedNodeMap` | `attributes(Element element)` Returns the attributes belonging to the supplied element.
    `` | `public static NodeList` | `breadthFirst(Element self)` Returns a breadth-first traversal view containing the element and its descendants level by level.
    `` | `public static NodeList` | `children(Element self)` Returns the child nodes visible to DOMCategory navigation.
    `` | `public static NodeList` | `depthFirst(Element self)` Returns a depth-first traversal view containing the element itself followed by descendant elements.
    `` | `public static Object` | `get(Element element, String elementName)` Resolves a GPath-style property lookup against a DOM element.
    `` | `public static Object` | `get(NodeList nodeList, String elementName)` Resolves a GPath-style property lookup against every element in a node list.
    `` | `public static Object` | `get(NamedNodeMap nodeMap, String elementName)` Returns the value of a named attribute from a DOM attribute map.
    `` | `public static Node` | `getAt(Node o, int i)` Returns the indexed child visible through DOMCategory navigation.
    `` | `public static Node` | `getAt(DOMCategory.NodeListsHolder o, int i)` Returns the indexed node from an aggregated node-list view.
    `` | `public static Node` | `getAt(DOMCategory.NodesHolder o, int i)` Returns the indexed node from a simple node-list view.
    `` | `public static NodeList` | `getAt(Node o, IntRange r)` Returns a range of child nodes visible through DOMCategory navigation.
    `` | `public static NodeList` | `getAt(DOMCategory.NodeListsHolder o, IntRange r)` Returns a range of nodes from an aggregated node-list view.
    `` | `public static NodeList` | `getAt(DOMCategory.NodesHolder o, IntRange r)` Returns a range of nodes from a simple node-list view.
    `` | `public static boolean` | `isEmpty(NodeList self)` Determines whether the supplied node list is empty.
    `` | `public static boolean` | `isGlobalKeepIgnorableWhitespace()` Returns: true if ignorable whitespace (e.g. whitespace between elements) is kept; default false
    `` | `public static boolean` | `isGlobalTrimWhitespace()` Returns: true if text elements are trimmed before returning; default false
    `` | `public static List<Node>` | `list(NodeList self)` Copies a NodeList into a mutable List.
    `` | `public static List<String>` | `localText(Element self)` Returns the list of any direct String nodes of this node.
    `` | `public static String` | `name(Node node)` Returns the DOM node name used for GPath name lookups.
    `` | `public static Node` | `parent(Node node)` Returns the parent DOM node.
    `` | `public static void` | `plus(Element self, Closure c)` Adds sibling nodes after the supplied element using the builder closure.
    `` | `public static void` | `plus(NodeList self, Closure c)` Adds sibling nodes after every element in the supplied node list.
    `` | `public static void` | `putAt(Element self, String property, Object value)` Performs a GPath-style property assignment on an element.
    `` | `public static Node` | `replaceNode(DOMCategory.NodesHolder self, Closure c)` Replaces a single selected node with the nodes produced by the supplied builder closure.
    `` | `public static Node` | `replaceNode(Node self, Closure c)` Replaces a node with the nodes produced by the supplied builder closure.
    `` | `public static void` | `setGlobalKeepIgnorableWhitespace(boolean keepIgnorableWhitespace)` Whether ignorable whitespace (e.g. whitespace between elements) is kept (default false).
    `` | `public static void` | `setGlobalTrimWhitespace(boolean trimWhitespace)` Whether text content is trimmed (removing leading and trailing whitespace); default false.
    `` | `public static void` | `setValue(Element self, String value)` Sets the value of the first child text node, creating one if the element has no children.
    `` | `public static int` | `size(NamedNodeMap namedNodeMap)` Returns the number of attributes in a DOM attribute map.
    `` | `public static int` | `size(NodeList self)` Returns the number of nodes in the supplied node list.
    `` | `public static String` | `text(Node node)` Returns the text visible from a DOM node.
    `` | `public static String` | `text(NodeList nodeList)` Concatenates the text visible from every node in the list.
    `` | `public static String` | `toString(Object o)` Renders a DOMCategory value in a GPath-friendly string form.
    `` | `public static Object` | `xpath(Node self, String expression, QName returnType)` Evaluates an XPath expression against the supplied node.
    `` | `public static String` | `xpath(Node self, String expression)` Evaluates an XPath expression against the supplied node and returns the string result.

  - ### Inherited Methods Summary

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

- - ### Method Detail

    - #### public static Element appendNode(Element self, Object name)

      Appends a child element with the given name.

      Parameters:
        `self` - the parent element
        `name` - the child element name, optionally a QName
      Returns:
        the appended child element

    - #### public static Element appendNode(Element self, Object name, Map attributes)

      Appends a child element with the given name and attributes.

      Parameters:
        `self` - the parent element
        `name` - the child element name, optionally a QName
        `attributes` - the attributes to apply to the new child
      Returns:
        the appended child element

    - #### public static Element appendNode(Element self, Object name, String value)

      Appends a child element with the given name and optional text value.

      Parameters:
        `self` - the parent element
        `name` - the child element name, optionally a QName
        `value` - the text value to append inside the new child, or `null`
      Returns:
        the appended child element

    - #### public static Element appendNode(Element self, Object name, Map attributes, String value)

      Appends a child element with attributes and optional text content.

      Parameters:
        `self` - the parent element
        `name` - the child element name, optionally a QName
        `attributes` - the attributes to apply to the new child
        `value` - the text value to append inside the new child, or `null`
      Returns:
        the appended child element

    - #### public static NamedNodeMap attributes(Element element)

      Returns the attributes belonging to the supplied element.

      Parameters:
        `element` - the element whose attributes should be returned
      Returns:
        the element's attribute map

    - #### public static NodeList breadthFirst(Element self)

      Returns a breadth-first traversal view containing the element and its descendants level by level.

      Parameters:
        `self` - the root element for traversal
      Returns:
        a node-list view in breadth-first order

    - #### public static NodeList children(Element self)

      Returns the child nodes visible to DOMCategory navigation. Child elements are always included, and retained text nodes are included when they are not discarded as ignorable whitespace.

      Parameters:
        `self` - the parent element
      Returns:
        a node-list view of the visible children

    - #### public static NodeList depthFirst(Element self)

      Returns a depth-first traversal view containing the element itself followed by descendant elements.

      Parameters:
        `self` - the root element for traversal
      Returns:
        a node-list view in depth-first order

    - #### public static Object get(Element element, String elementName)

      Resolves a GPath-style property lookup against a DOM element. Supports child element lookup, attribute access using `@name`, parent lookup using `..`, and depth-first traversal using `**`.

      Parameters:
        `element` - the element to query
        `elementName` - the property or selector name
      Returns:
        the matching child nodes, attribute value, parent node, or traversal view

    - #### public static Object get(NodeList nodeList, String elementName)

      Resolves a GPath-style property lookup against every element in a node list.

      Parameters:
        `nodeList` - the nodes to query
        `elementName` - the property or selector name
      Returns:
        an aggregated result for the supplied selector

    - #### public static Object get(NamedNodeMap nodeMap, String elementName)

      Returns the value of a named attribute from a DOM attribute map.

      Parameters:
        `nodeMap` - the attributes to query
        `elementName` - the attribute name
      Returns:
        the attribute value

    - #### public static Node getAt(Node o, int i)

      Returns the indexed child visible through DOMCategory navigation. Negative indices count backward from the end of the result.

      Parameters:
        `o` - the node or element to index
        `i` - the zero-based index
      Returns:
        the selected node, or `null` if the index is out of range

    - #### public static Node getAt(DOMCategory.NodeListsHolder o, int i)

      Returns the indexed node from an aggregated node-list view. Negative indices count backward from the end of the result.

      Parameters:
        `o` - the aggregated node-list view
        `i` - the zero-based index
      Returns:
        the selected node, or `null` if the index is out of range

    - #### public static Node getAt(DOMCategory.NodesHolder o, int i)

      Returns the indexed node from a simple node-list view. Negative indices count backward from the end of the result.

      Parameters:
        `o` - the node-list view
        `i` - the zero-based index
      Returns:
        the selected node, or `null` if the index is out of range

    - #### public static NodeList getAt(Node o, IntRange r)

      Returns a range of child nodes visible through DOMCategory navigation. Negative bounds count backward from the end of the result.

      Parameters:
        `o` - the node or element to slice
        `r` - the range of indices to select
      Returns:
        a node-list view containing the selected nodes

    - #### public static NodeList getAt(DOMCategory.NodeListsHolder o, IntRange r)

      Returns a range of nodes from an aggregated node-list view.

      Parameters:
        `o` - the aggregated node-list view
        `r` - the range of indices to select
      Returns:
        a node-list view containing the selected nodes

    - #### public static NodeList getAt(DOMCategory.NodesHolder o, IntRange r)

      Returns a range of nodes from a simple node-list view.

      Parameters:
        `o` - the node-list view
        `r` - the range of indices to select
      Returns:
        a node-list view containing the selected nodes

    - #### public static boolean isEmpty(NodeList self)

      Determines whether the supplied node list is empty.

      Parameters:
        `self` - the node list to inspect
      Returns:
        `true` if the node list contains no nodes

    - #### public static boolean isGlobalKeepIgnorableWhitespace()

      Returns:
        true if ignorable whitespace (e.g. whitespace between elements) is kept; default false

    - #### public static boolean isGlobalTrimWhitespace()

      Returns:
        true if text elements are trimmed before returning; default false

    - #### public static List<Node> list(NodeList self)

      Copies a NodeList into a mutable List.

      Parameters:
        `self` - the node list to copy
      Returns:
        a list containing the nodes from the node list

    - #### public static List<String> localText(Element self)

      Returns the list of any direct String nodes of this node.

      Returns:
        the list of String values from this node
      Since:
        2.3.0

    - #### public static String name(Node node)

      Returns the DOM node name used for GPath name lookups.

      Parameters:
        `node` - the node to inspect
      Returns:
        the node name

    - #### public static Node parent(Node node)

      Returns the parent DOM node.

      Parameters:
        `node` - the node whose parent should be returned
      Returns:
        the parent node, or `null` for a root node

    - #### public static void plus(Element self, Closure c)

      Adds sibling nodes after the supplied element using the builder closure.

      throws:
        UnsupportedOperationException if `self` is the document root
      Parameters:
        `self` - the element after which new siblings should be inserted
        `c` - the builder closure creating the sibling nodes

    - #### public static void plus(NodeList self, Closure c)

      Adds sibling nodes after every element in the supplied node list.

      Parameters:
        `self` - the elements after which new siblings should be inserted
        `c` - the builder closure creating the sibling nodes

    - #### public static void putAt(Element self, String property, Object value)

      Performs a GPath-style property assignment on an element. Attribute assignments use the `@name` form; all other properties are delegated to Groovy property handling.

      Parameters:
        `self` - the element to update
        `property` - the property or attribute selector
        `value` - the value to assign

    - #### public static Node replaceNode(DOMCategory.NodesHolder self, Closure c)

      Replaces a single selected node with the nodes produced by the supplied builder closure.

      throws:
        GroovyRuntimeException if the selection does not contain exactly one node
      Parameters:
        `self` - the node selection to replace; it must contain exactly one node
        `c` - the builder closure creating replacement nodes
      Returns:
        the removed node

    - #### public static Node replaceNode(Node self, Closure c)

      Replaces a node with the nodes produced by the supplied builder closure.

      throws:
        UnsupportedOperationException if `self` is the document root
      Parameters:
        `self` - the node to replace
        `c` - the builder closure creating replacement nodes
      Returns:
        the removed node

    - #### public static void setGlobalKeepIgnorableWhitespace(boolean keepIgnorableWhitespace)

      Whether ignorable whitespace (e.g. whitespace between elements) is kept (default false). WARNING: this is a global setting. Altering it will affect all DOMCategory usage within the current Java process.

      Parameters:
        `keepIgnorableWhitespace` - the new value

    - #### public static void setGlobalTrimWhitespace(boolean trimWhitespace)

      Whether text content is trimmed (removing leading and trailing whitespace); default false. WARNING: this is a global setting. Altering it will affect all DOMCategory usage within the current Java process. It is not recommended that this is altered; instead call the trim() method on the returned text, but the flag is available to support legacy Groovy behavior.

      Parameters:
        `trimWhitespace` - the new value

    - #### public static void setValue(Element self, String value)

      Sets the value of the first child text node, creating one if the element has no children.

      Parameters:
        `self` - the element to update
        `value` - the text value to set

    - #### public static int size(NamedNodeMap namedNodeMap)

      Returns the number of attributes in a DOM attribute map.

      Parameters:
        `namedNodeMap` - the attributes to inspect
      Returns:
        the number of attributes

    - #### public static int size(NodeList self)

      Returns the number of nodes in the supplied node list.

      Parameters:
        `self` - the node list to inspect
      Returns:
        the number of nodes

    - #### public static String text(Node node)

      Returns the text visible from a DOM node. Text and CDATA nodes return their value directly; other nodes concatenate descendant text.

      Parameters:
        `node` - the node to inspect
      Returns:
        the concatenated text for the node

    - #### public static String text(NodeList nodeList)

      Concatenates the text visible from every node in the list.

      Parameters:
        `nodeList` - the nodes to inspect
      Returns:
        the concatenated text for all nodes in document order

    - #### public static String toString(Object o)

      Renders a DOMCategory value in a GPath-friendly string form.

      Parameters:
        `o` - the value to render
      Returns:
        text for text nodes, list-style output for node lists, or `o.toString()`

    - #### public static Object xpath(Node self, String expression, QName returnType)

      Evaluates an XPath expression against the supplied node.

      throws:
        GroovyRuntimeException if the expression cannot be evaluated
      Parameters:
        `self` - the context node
        `expression` - the XPath expression to evaluate
        `returnType` - the desired XPath return type
      Returns:
        the XPath evaluation result

    - #### public static String xpath(Node self, String expression)

      Evaluates an XPath expression against the supplied node and returns the string result.

      throws:
        GroovyRuntimeException if the expression cannot be evaluated
      Parameters:
        `self` - the context node
        `expression` - the XPath expression to evaluate
      Returns:
        the string result of the XPath evaluation