DOMCategory (Groovy 6.0.0-alpha-1)

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

Summary:
Method

| Detail:
Method

[Java] Class DOMCategory

Methods Summary

Inherited Methods Summary

Method Detail

public static Element appendNode(Element self, Object name)

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

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

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

public static NamedNodeMap attributes(Element element)

public static NodeList breadthFirst(Element self)

public static NodeList children(Element self)

public static NodeList depthFirst(Element self)

public static Object get(Element element, String elementName)

public static Object get(NodeList nodeList, String elementName)

public static Object get(NamedNodeMap nodeMap, String elementName)

public static Node getAt(Node o, int i)

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

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

public static NodeList getAt(Node o, IntRange r)

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

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

public static boolean isEmpty(NodeList self)

public static boolean isGlobalKeepIgnorableWhitespace()

public static boolean isGlobalTrimWhitespace()

public static List<Node> list(NodeList self)

public static List<String> localText(Element self)

public static String name(Node node)

public static Node parent(Node node)

public static void plus(Element self, Closure c)

public static void plus(NodeList self, Closure c)

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

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

public static Node replaceNode(Node self, Closure c)

public static void setGlobalKeepIgnorableWhitespace(boolean keepIgnorableWhitespace)

public static void setGlobalTrimWhitespace(boolean trimWhitespace)

public static void setValue(Element self, String value)

public static int size(NamedNodeMap namedNodeMap)

public static int size(NodeList self)

public static String text(Node node)

public static String text(NodeList nodeList)

public static String toString(Object o)

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

public static String xpath(Node self, String expression)