0
# Groovy XML
1

2
A comprehensive Groovy library for XML processing providing powerful and idiomatic APIs for parsing, generating, and manipulating XML documents. The library offers multiple processing approaches from simple parsing to advanced streaming operations, all designed to leverage Groovy's dynamic features for intuitive XML handling.
3

4
## Package Information
5

6
- **Package Name**: org.apache.groovy:groovy-xml
7
- **Package Type**: maven
8
- **Language**: Groovy/Java
9
- **Installation**: Add to Gradle: `implementation 'org.apache.groovy:groovy-xml:5.0.0'`
10

11
## Core Imports
12

13
```groovy
14
import groovy.xml.*
15
```
16

17
Specific imports for common use cases:
18

19
```groovy
20
import groovy.xml.XmlParser
21
import groovy.xml.XmlSlurper
22
import groovy.xml.MarkupBuilder
23
import groovy.xml.DOMBuilder
24
import groovy.xml.XmlUtil
25
```
26

27
## Basic Usage
28

29
```groovy
30
import groovy.xml.*
31

32
// Parse XML with XmlParser
33
def parser = new XmlParser()
34
def root = parser.parseText('''
35
    <books>
36
        <book id="1" title="Groovy in Action"/>
37
        <book id="2" title="Programming Groovy"/>
38
    </books>
39
''')
40

41
// Access parsed data
42
println root.book[0].@title  // "Groovy in Action"
43
println root.book.size()     // 2
44

45
// Generate XML with MarkupBuilder
46
def writer = new StringWriter()
47
def xml = new MarkupBuilder(writer)
48
xml.books {
49
    book(id: "1", title: "Groovy in Action")
50
    book(id: "2", title: "Programming Groovy")
51
}
52
println writer.toString()
53

54
// Parse with XmlSlurper for GPath navigation
55
def slurper = new XmlSlurper()
56
def doc = slurper.parseText('''<catalog><book price="12.99">Title</book></catalog>''')
57
println doc.book.@price      // "12.99"
58
println doc.book.text()      // "Title"
59
```
60

61
## Architecture
62

63
The Groovy XML library is built around several key processing paradigms:
64

65
- **Tree-based Parsing**: `XmlParser` creates mutable DOM-like trees using `groovy.util.Node`
66
- **GPath Navigation**: `XmlSlurper` provides lazy-evaluated GPath expressions for XML traversal
67
- **Builder Pattern**: Multiple builders (`MarkupBuilder`, `DOMBuilder`, `StreamingMarkupBuilder`) for XML generation
68
- **DOM Integration**: Enhanced DOM processing with Groovy category methods
69
- **Streaming Support**: Memory-efficient streaming builders for large XML documents
70
- **Namespace Awareness**: Full XML namespace support across all processing modes
71

72
## Capabilities
73

74
### XML Parsing
75

76
Two primary parsing approaches: tree-based parsing with XmlParser for mutable document trees, and GPath-based parsing with XmlSlurper for lazy evaluation and XPath-like navigation.
77

78
```groovy { .api }
79
class XmlParser {
80
    XmlParser()
81
    XmlParser(boolean validating, boolean namespaceAware)
82
    Node parse(File file)
83
    Node parse(String uri)
84
    Node parseText(String text)
85
}
86

87
class XmlSlurper {
88
    XmlSlurper()
89
    XmlSlurper(boolean validating, boolean namespaceAware)
90
    GPathResult parse(File file)
91
    GPathResult parse(String uri) 
92
    GPathResult parseText(String text)
93
}
94
```
95

96
[XML Parsing](./xml-parsing.md)
97

98
### XML Generation
99

100
Comprehensive XML building capabilities including markup builders for formatted output, DOM builders for W3C DOM integration, and streaming builders for memory-efficient large document generation.
101

102
```groovy { .api }
103
class MarkupBuilder {
104
    MarkupBuilder()
105
    MarkupBuilder(Writer writer)
106
    MarkupBuilderHelper getMkp()
107
}
108

109
class DOMBuilder {
110
    static DOMBuilder newInstance()
111
    Document parseText(String text)
112
}
113

114
class StreamingMarkupBuilder {
115
    def bind(Closure closure)
116
    def bindNode(Node node)
117
}
118

119
class Entity {
120
    Entity(String name)
121
    Entity(int code)
122
    // Comprehensive XML entity constants (nbsp, copy, lt, gt, etc.)
123
}
124
```
125

126
[XML Generation](./xml-generation.md)
127

128
### DOM Processing
129

130
Enhanced DOM processing with Groovy category methods providing GPath-style navigation and manipulation for standard W3C DOM objects.
131

132
```groovy { .api }
133
class DOMCategory {
134
    static Object get(Element element, String elementName)
135
    static String text(Node node)
136
    static Element appendNode(Element self, Object name)
137
    static NodeList depthFirst(Element self)
138
    static String xpath(Node self, String expression)
139
}
140
```
141

142
[DOM Processing](./dom-processing.md)
143

144
### XML Utilities
145

146
Utility functions for XML serialization, pretty printing, escaping, and advanced parser configuration with schema validation support.
147

148
```groovy { .api }
149
class XmlUtil {
150
    static String serialize(Element element)
151
    static String serialize(Node node)
152
    static String serialize(GPathResult node)
153
    static String escapeXml(String text)
154
    static SAXParser newSAXParser(String schemaLanguage, Source... schemas)
155
}
156
```
157

158
[XML Utilities](./xml-utilities.md)
159

160
### Namespace Support
161

162
Comprehensive XML namespace support including namespace builders, QName factories, and namespace-aware parsing and generation across all processing modes.
163

164
```groovy { .api }
165
class Namespace {
166
    Namespace(String uri)
167
    Namespace(String uri, String prefix)
168
    QName get(String localName)
169
}
170

171
class NamespaceBuilder {
172
    NamespaceBuilderSupport namespace(String uri)
173
    NamespaceBuilderSupport declareNamespace(Map ns)
174
}
175
```
176

177
[Namespace Support](./namespace-support.md)
178

179
## Types
180

181
```groovy { .api }
182
// Core result types
183
class Node {
184
    String name()
185
    Object value()
186
    List children()
187
    Map attributes()
188
    Node parent()
189
}
190

191
abstract class GPathResult {
192
    String name()
193
    String text()
194
    int size()
195
    boolean isEmpty()
196
    GPathResult parent()
197
    Iterator iterator()
198
}
199

200
// Builder helper types
201
class MarkupBuilderHelper {
202
    void yield(Object value)
203
    void comment(String value)
204
    void xmlDeclaration(Map<String, Object> args)
205
}
206

207
// Exception types
208
class SAXException extends Exception
209
class ParserConfigurationException extends Exception
210
```