0
# Groovy YAML
1

2
Groovy YAML provides comprehensive YAML processing capabilities for the Apache Groovy programming language. It includes YamlSlurper for parsing YAML documents into Groovy data structures, YamlBuilder for programmatically constructing YAML documents using Groovy's builder pattern, and utility classes for converting between YAML and JSON formats.
3

4
## Package Information
5

6
- **Package Name**: org.apache.groovy:groovy-yaml
7
- **Package Type**: maven
8
- **Language**: Java/Groovy
9
- **Installation**: Add to your build.gradle or pom.xml:
10

11
Gradle:
12
```groovy
13
implementation 'org.apache.groovy:groovy-yaml:5.0.0'
14
```
15

16
Maven:
17
```xml
18
<dependency>
19
    <groupId>org.apache.groovy</groupId>
20
    <artifactId>groovy-yaml</artifactId>
21
    <version>5.0.0</version>
22
</dependency>
23
```
24

25
## Core Imports
26

27
```java
28
import groovy.yaml.YamlSlurper;
29
import groovy.yaml.YamlBuilder;
30
import groovy.yaml.YamlRuntimeException;
31
import org.apache.groovy.yaml.util.YamlConverter;
32
```
33

34
## Basic Usage
35

36
```java
37
import groovy.yaml.YamlSlurper;
38
import groovy.yaml.YamlBuilder;
39

40
// Parse YAML content
41
YamlSlurper yamlSlurper = new YamlSlurper();
42
Object result = yamlSlurper.parseText("""
43
language: groovy
44
version: 5.0.0
45
features:
46
  - yaml-parsing
47
  - yaml-building
48
""");
49

50
// Build YAML content
51
YamlBuilder yamlBuilder = new YamlBuilder();
52
yamlBuilder.call(Map.of(
53
    "language", "groovy",
54
    "version", "5.0.0",
55
    "features", List.of("yaml-parsing", "yaml-building")
56
));
57
String yamlOutput = yamlBuilder.toString();
58
```
59

60
## Architecture
61

62
Groovy YAML is built around several key components:
63

64
- **YamlSlurper**: YAML parser that converts YAML documents into Groovy data structures, similar to JsonSlurper
65
- **YamlBuilder**: YAML builder using Groovy's builder pattern with closure support for programmatic YAML construction
66
- **YamlConverter**: Utility for bidirectional YAML/JSON conversion leveraging Jackson libraries
67
- **YamlRuntimeException**: Specialized exception handling for YAML processing errors
68
- **Integration Layer**: Seamless integration with Groovy's dynamic features and existing JSON processing APIs
69

70
## Capabilities
71

72
### YAML Parsing
73

74
Parse YAML documents from various sources (strings, streams, files) into Groovy data structures that can be accessed using Groovy's dynamic syntax.
75

76
```java { .api }
77
public class YamlSlurper {
78
    public YamlSlurper();
79
    public Object parseText(String yaml);
80
    public Object parse(Reader reader);
81
    public Object parse(InputStream stream);
82
    public Object parse(java.io.File file) throws IOException;
83
    public Object parse(Path path) throws IOException;
84
}
85
```
86

87
[YAML Parsing](./yaml-parsing.md)
88

89
### YAML Building
90

91
Programmatically construct YAML documents using Groovy's builder pattern with support for closures, maps, lists, and dynamic method calls.
92

93
```java { .api }
94
public class YamlBuilder extends GroovyObjectSupport implements Writable {
95
    public YamlBuilder();
96
    public Object getContent();
97
    public Object call(Map m);
98
    public Object call(List l);
99
    public Object call(Object... args);
100
    public Object call(Iterable coll, Closure c);
101
    public Object call(Collection coll, Closure c);
102
    public Object call(Closure c);
103
    public Object invokeMethod(String name, Object args);
104
    public String toString();
105
    public Writer writeTo(Writer out) throws IOException;
106
}
107
```
108

109
[YAML Building](./yaml-building.md)
110

111
### Format Conversion
112

113
Convert between YAML and JSON formats using utility methods that leverage Jackson's processing capabilities.
114

115
```java { .api }
116
public final class YamlConverter {
117
    public static String convertYamlToJson(Reader yamlReader);
118
    public static String convertJsonToYaml(Reader jsonReader);
119
}
120
```
121

122
[Format Conversion](./format-conversion.md)
123

124
## Types
125

126
```java { .api }
127
public class YamlRuntimeException extends GroovyRuntimeException {
128
    public YamlRuntimeException(String msg);
129
    public YamlRuntimeException(Throwable cause);
130
    public YamlRuntimeException(String msg, Throwable cause);
131
}
132
```