Package groovy.xml.dom

# Class DOMCategory

java.lang.Object
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.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DOMCategory()`

- ## Method Summary

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

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

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

- ## Constructor Details

  - ### DOMCategory

    public DOMCategory()

- ## Method Details

  - ### isGlobalTrimWhitespace

    public static boolean isGlobalTrimWhitespace()
    Returns:
      true if text elements are trimmed before returning; default false

  - ### setGlobalTrimWhitespace

    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

  - ### isGlobalKeepIgnorableWhitespace

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

  - ### setGlobalKeepIgnorableWhitespace

    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

  - ### get

    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

  - ### get

    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

  - ### get

    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

  - ### attributes

    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

  - ### size

    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

  - ### getAt

    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

  - ### getAt

    public static Node getAt(groovy.xml.dom.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

  - ### getAt

    public static Node getAt(groovy.xml.dom.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

  - ### getAt

    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

  - ### getAt

    public static NodeList getAt(groovy.xml.dom.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

  - ### getAt

    public static NodeList getAt(groovy.xml.dom.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

  - ### name

    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

  - ### parent

    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

  - ### text

    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

  - ### text

    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

  - ### list

    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

  - ### depthFirst

    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

  - ### setValue

    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

  - ### putAt

    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

  - ### appendNode

    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

  - ### appendNode

    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

  - ### appendNode

    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

  - ### appendNode

    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

  - ### replaceNode

    public static Node replaceNode(groovy.xml.dom.DOMCategory.NodesHolder self, Closure c)
    Replaces a single selected node with the nodes produced by the supplied builder closure.
    Parameters:
      `self` - the node selection to replace; it must contain exactly one node
      `c` - the builder closure creating replacement nodes
    Returns:
      the removed node
    Throws:
      `GroovyRuntimeException` - if the selection does not contain exactly one node

  - ### replaceNode

    public static Node replaceNode(Node self, Closure c)
    Replaces a node with the nodes produced by the supplied builder closure.
    Parameters:
      `self` - the node to replace
      `c` - the builder closure creating replacement nodes
    Returns:
      the removed node
    Throws:
      `UnsupportedOperationException` - if `self` is the document root

  - ### plus

    public static void plus(Element self, Closure c)
    Adds sibling nodes after the supplied element using the builder closure.
    Parameters:
      `self` - the element after which new siblings should be inserted
      `c` - the builder closure creating the sibling nodes
    Throws:
      `UnsupportedOperationException` - if `self` is the document root

  - ### localText

    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

  - ### plus

    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

  - ### breadthFirst

    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

  - ### children

    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

  - ### toString

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

  - ### xpath

    public static Object xpath(Node self, String expression, QName returnType)
    Evaluates an XPath expression against the supplied node.
    Parameters:
      `self` - the context node
      `expression` - the XPath expression to evaluate
      `returnType` - the desired XPath return type
    Returns:
      the XPath evaluation result
    Throws:
      `GroovyRuntimeException` - if the expression cannot be evaluated

  - ### xpath

    public static String xpath(Node self, String expression)
    Evaluates an XPath expression against the supplied node and returns the string result.
    Parameters:
      `self` - the context node
      `expression` - the XPath expression to evaluate
    Returns:
      the string result of the XPath evaluation
    Throws:
      `GroovyRuntimeException` - if the expression cannot be evaluated

  - ### size

    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

  - ### isEmpty

    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