0
# YAML Parsing
1

2
Comprehensive YAML parsing functionality that converts YAML documents from various sources into Groovy data structures, providing the same ease of use as JsonSlurper for JSON processing.
3

4
## Capabilities
5

6
### YamlSlurper Class
7

8
Creates a YAML parser instance that can parse YAML from multiple input sources.
9

10
```java { .api }
11
/**
12
 * Represents a YAML parser that converts YAML documents into Groovy data structures.
13
 * Similar to JsonSlurper but for YAML format.
14
 */
15
public class YamlSlurper {
16
    /**
17
     * Creates a new YAML parser instance.
18
     * Initializes internal JsonSlurper for processing converted data.
19
     */
20
    public YamlSlurper();
21
}
22
```
23

24
### Parse from String
25

26
Parse YAML content directly from a string.
27

28
```java { .api }
29
/**
30
 * Parse the content of the specified yaml string into a tree of Nodes.
31
 * @param yaml the content of yaml as a string
32
 * @return the root node of the parsed tree of Nodes
33
 */
34
public Object parseText(String yaml);
35
```
36

37
**Usage Example:**
38

39
```java
40
import groovy.yaml.YamlSlurper;
41

42
YamlSlurper yamlSlurper = new YamlSlurper();
43
Object result = yamlSlurper.parseText("""
44
language: groovy
45
sudo: required
46
dist: trusty
47
matrix:
48
  include:
49
    - jdk: openjdk10
50
    - jdk: oraclejdk9
51
    - jdk: oraclejdk8
52
before_script:
53
  - unset _JAVA_OPTIONS
54
""");
55

56
// Access parsed data using Groovy's dynamic syntax
57
assert "groovy".equals(result.language);
58
assert "required".equals(result.sudo);
59
assert "trusty".equals(result.dist);
60
```
61

62
### Parse from Reader
63

64
Parse YAML content from a Reader instance.
65

66
```java { .api }
67
/**
68
 * Parse the content of the specified reader into a tree of Nodes.
69
 * @param reader the reader of yaml content
70
 * @return the root node of the parsed tree of Nodes
71
 */
72
public Object parse(Reader reader);
73
```
74

75
**Usage Example:**
76

77
```java
78
import groovy.yaml.YamlSlurper;
79
import java.io.StringReader;
80

81
YamlSlurper yamlSlurper = new YamlSlurper();
82
String yamlContent = "name: example\nversion: 1.0.0";
83
Object result = yamlSlurper.parse(new StringReader(yamlContent));
84
```
85

86
### Parse from InputStream
87

88
Parse YAML content from an InputStream.
89

90
```java { .api }
91
/**
92
 * Parse the content of the specified input stream into a tree of Nodes.
93
 * @param stream the input stream of yaml content
94
 * @return the root node of the parsed tree of Nodes
95
 */
96
public Object parse(InputStream stream);
97
```
98

99
**Usage Example:**
100

101
```java
102
import groovy.yaml.YamlSlurper;
103
import java.io.ByteArrayInputStream;
104
import java.nio.charset.StandardCharsets;
105

106
YamlSlurper yamlSlurper = new YamlSlurper();
107
String yamlContent = "name: example\nversion: 1.0.0";
108
InputStream stream = new ByteArrayInputStream(yamlContent.getBytes(StandardCharsets.UTF_8));
109
Object result = yamlSlurper.parse(stream);
110
```
111

112
### Parse from File
113

114
Parse YAML content from a File object.
115

116
```java { .api }
117
/**
118
 * Parse the content of the specified file into a tree of Nodes.
119
 * @param file the file containing yaml content
120
 * @return the root node of the parsed tree of Nodes
121
 * @throws IOException if file cannot be read
122
 */
123
public Object parse(java.io.File file) throws IOException;
124
```
125

126
**Usage Example:**
127

128
```java
129
import groovy.yaml.YamlSlurper;
130
import java.io.File;
131
import java.io.IOException;
132

133
YamlSlurper yamlSlurper = new YamlSlurper();
134
try {
135
    Object result = yamlSlurper.parse(new File("config.yaml"));
136
    // Process parsed YAML data
137
} catch (IOException e) {
138
    // Handle file reading errors
139
}
140
```
141

142
### Parse from Path
143

144
Parse YAML content from a Path object (Java NIO).
145

146
```java { .api }
147
/**
148
 * Parse the content of the specified path into a tree of Nodes.
149
 * @param path the path to the file containing yaml content
150
 * @return the root node of the parsed tree of Nodes
151
 * @throws IOException if file cannot be read
152
 */
153
public Object parse(Path path) throws IOException;
154
```
155

156
**Usage Example:**
157

158
```java
159
import groovy.yaml.YamlSlurper;
160
import java.nio.file.Path;
161
import java.nio.file.Paths;
162
import java.io.IOException;
163

164
YamlSlurper yamlSlurper = new YamlSlurper();
165
try {
166
    Path configPath = Paths.get("config.yaml");
167
    Object result = yamlSlurper.parse(configPath);
168
    // Process parsed YAML data
169
} catch (IOException e) {
170
    // Handle file reading errors
171
}
172
```
173

174
## Error Handling
175

176
All parsing methods may throw `YamlRuntimeException` if the YAML content is malformed or cannot be processed:
177

178
```java { .api }
179
public class YamlRuntimeException extends GroovyRuntimeException {
180
    public YamlRuntimeException(String msg);
181
    public YamlRuntimeException(Throwable cause);
182
    public YamlRuntimeException(String msg, Throwable cause);
183
}
184
```
185

186
**Example Error Handling:**
187

188
```java
189
import groovy.yaml.YamlSlurper;
190
import groovy.yaml.YamlRuntimeException;
191

192
YamlSlurper yamlSlurper = new YamlSlurper();
193
try {
194
    Object result = yamlSlurper.parseText("invalid: yaml: content: [");
195
} catch (YamlRuntimeException e) {
196
    System.err.println("YAML parsing failed: " + e.getMessage());
197
}
198
```