0
# YAML Building
1

2
Programmatic YAML construction using Groovy's builder pattern with support for closures, maps, lists, and dynamic method calls. Provides a fluent API for creating YAML documents from Groovy data structures.
3

4
## Capabilities
5

6
### YamlBuilder Class
7

8
Creates a YAML builder instance that supports Groovy's builder pattern with various construction methods.
9

10
```java { .api }
11
/**
12
 * A builder for creating YAML payloads using Groovy's builder pattern.
13
 * Extends GroovyObjectSupport for dynamic method support and implements Writable for output.
14
 */
15
public class YamlBuilder extends GroovyObjectSupport implements Writable {
16
    /**
17
     * Creates a new YAML builder instance.
18
     * Initializes internal JsonBuilder for processing.
19
     */
20
    public YamlBuilder();
21
    
22
    /**
23
     * Get the internal content object built by the builder.
24
     * @return the content object
25
     */
26
    public Object getContent();
27
}
28
```
29

30
### Build from Map
31

32
Create a root YAML object from a Map using named arguments.
33

34
```java { .api }
35
/**
36
 * Named arguments can be passed to the YAML builder instance to create a root YAML object.
37
 * @param m a map of key / value pairs
38
 * @return a map of key / value pairs
39
 */
40
public Object call(Map m);
41
```
42

43
**Usage Example:**
44

45
```java
46
import groovy.yaml.YamlBuilder;
47
import java.util.Map;
48

49
YamlBuilder yaml = new YamlBuilder();
50
yaml.call(Map.of("name", "Guillaume", "age", 33));
51

52
assert yaml.toString().equals("""---
53
name: "Guillaume"
54
age: 33
55
""");
56
```
57

58
### Build from List
59

60
Create a root YAML array from a List.
61

62
```java { .api }
63
/**
64
 * A list of elements as arguments to the YAML builder creates a root YAML array.
65
 * @param l a list of values
66
 * @return a list of values
67
 */
68
public Object call(List l);
69
```
70

71
**Usage Example:**
72

73
```java
74
import groovy.yaml.YamlBuilder;
75
import java.util.List;
76

77
YamlBuilder yaml = new YamlBuilder();
78
Object result = yaml.call(List.of(1, 2, 3));
79

80
assert result instanceof List;
81
assert yaml.toString().equals("""---
82
- 1
83
- 2
84
- 3
85
""");
86
```
87

88
### Build from Varargs
89

90
Create a root YAML array from variable arguments.
91

92
```java { .api }
93
/**
94
 * Varargs elements as arguments to the YAML builder create a root YAML array.
95
 * @param args an array of values
96
 * @return a list of values
97
 */
98
public Object call(Object... args);
99
```
100

101
**Usage Example:**
102

103
```java
104
import groovy.yaml.YamlBuilder;
105

106
YamlBuilder yaml = new YamlBuilder();
107
Object result = yaml.call(1, 2, 3);
108

109
assert result instanceof List;
110
assert yaml.toString().equals("""---
111
- 1
112
- 2
113
- 3
114
""");
115
```
116

117
### Build from Collection with Closure
118

119
Create a root YAML array from a collection, applying a closure to each object.
120

121
```java { .api }
122
/**
123
 * A collection and closure passed to a YAML builder will create a root YAML array applying
124
 * the closure to each object in the collection.
125
 * @param coll a collection
126
 * @param c a closure used to convert the objects of coll
127
 * @return a list of values
128
 */
129
public Object call(Iterable coll, Closure c);
130

131
/**
132
 * Delegates to the Iterable version.
133
 * @param coll a collection
134
 * @param c a closure used to convert the objects of coll
135
 * @return a list of values
136
 */
137
public Object call(Collection coll, Closure c);
138
```
139

140
**Usage Example:**
141

142
```groovy
143
import groovy.yaml.YamlBuilder
144

145
class Author {
146
    String name
147
}
148
def authors = [new Author(name: "Guillaume"), new Author(name: "Jochen"), new Author(name: "Paul")]
149

150
def yaml = new YamlBuilder()
151
yaml.call(authors) { Author author ->
152
    name author.name
153
}
154

155
assert yaml.toString() == '''---
156
- name: "Guillaume"
157
- name: "Jochen"  
158
- name: "Paul"
159
'''
160
```
161

162
### Build from Closure
163

164
Create a root YAML object from a closure using builder pattern.
165

166
```java { .api }
167
/**
168
 * A closure passed to a YAML builder will create a root YAML object.
169
 * @param c a closure whose method call statements represent key / values of a YAML object
170
 * @return a map of key / value pairs
171
 */
172
public Object call(Closure c);
173
```
174

175
**Usage Example:**
176

177
```groovy
178
import groovy.yaml.YamlBuilder
179

180
def yaml = new YamlBuilder()
181
def result = yaml {
182
    name "Guillaume"
183
    age 33
184
}
185

186
assert result instanceof Map
187
assert yaml.toString() == '''---
188
name: "Guillaume"
189
age: 33
190
'''
191
```
192

193
### Dynamic Method Calls
194

195
Create YAML structure using dynamic method calls following the builder pattern.
196

197
```java { .api }
198
/**
199
 * A method call on the YAML builder instance will create a root object with only one key
200
 * whose name is the name of the method being called.
201
 * This method takes various argument types including closures, maps, or no arguments.
202
 * @param name the single key
203
 * @param args the value associated with the key
204
 * @return a map with a single key
205
 */
206
@Override
207
public Object invokeMethod(String name, Object args);
208
```
209

210
**Usage Examples:**
211

212
```groovy
213
import groovy.yaml.YamlBuilder
214

215
// Builder-style with closure
216
def yaml = new YamlBuilder()
217
def result = yaml.person {
218
    name "Guillaume"
219
    age 33
220
}
221

222
assert yaml.toString() == '''---
223
person:
224
  name: "Guillaume"
225
  age: 33
226
'''
227

228
// Named arguments
229
yaml = new YamlBuilder()
230
yaml.person(name: "Guillaume", age: 33)
231

232
assert yaml.toString() == '''---
233
person:
234
  name: "Guillaume"
235
  age: 33
236
'''
237

238
// Mixed named arguments and closure
239
yaml = new YamlBuilder()
240
yaml.person(name: "Guillaume", age: 33) { town "Paris" }
241

242
assert yaml.toString() == '''---
243
person:
244
  name: "Guillaume"
245
  age: 33
246
  town: "Paris"
247
'''
248

249
// Empty args create empty object
250
yaml = new YamlBuilder()
251
yaml.person()
252

253
assert yaml.toString() == '''---
254
person: {}
255
'''
256
```
257

258
### Output Generation
259

260
Convert the built structure to YAML string format.
261

262
```java { .api }
263
/**
264
 * Serializes the internal data structure built with the builder to a conformant YAML payload string.
265
 * @return a YAML output string
266
 */
267
@Override
268
public String toString();
269
```
270

271
**Usage Example:**
272

273
```groovy
274
import groovy.yaml.YamlBuilder
275

276
def yaml = new YamlBuilder()
277
yaml { temperature 37 }
278

279
assert yaml.toString() == '''---
280
temperature: 37
281
'''
282
```
283

284
### Write to Writer
285

286
Write the YAML output to a Writer instance (Writable interface).
287

288
```java { .api }
289
/**
290
 * The YAML builder implements the Writable interface,
291
 * so that you can have the builder serialize itself the YAML payload to a writer.
292
 * @param out a writer on which to serialize the YAML payload
293
 * @return the writer
294
 * @throws IOException if writing fails
295
 */
296
@Override
297
public Writer writeTo(Writer out) throws IOException;
298
```
299

300
**Usage Example:**
301

302
```groovy
303
import groovy.yaml.YamlBuilder
304
import java.io.StringWriter
305

306
def yaml = new YamlBuilder()
307
yaml { temperature 37 }
308

309
def out = new StringWriter()
310
out << yaml
311

312
assert out.toString() == '''---
313
temperature: 37
314
'''
315
```
316

317
## Error Handling
318

319
YAML building methods may throw `YamlRuntimeException` if the structure cannot be converted to valid YAML:
320

321
```java { .api }
322
public class YamlRuntimeException extends GroovyRuntimeException {
323
    public YamlRuntimeException(String msg);
324
    public YamlRuntimeException(Throwable cause);
325
    public YamlRuntimeException(String msg, Throwable cause);
326
}
327
```