0
# Groovy TOML
1

2
Groovy TOML is a library that provides comprehensive TOML (Tom's Obvious, Minimal Language) processing capabilities for Apache Groovy applications. It offers two main components: TomlSlurper for parsing TOML text into native Groovy data structures with full GPath expression support, and TomlBuilder for programmatically constructing TOML documents using Groovy's DSL syntax.
3

4
## Package Information
5

6
- **Package Name**: org.apache.groovy:groovy-toml
7
- **Package Type**: maven
8
- **Language**: Java (for Groovy)
9
- **Installation**: Add dependency to your build.gradle: `implementation 'org.apache.groovy:groovy-toml:5.0.0'`
10

11
## Core Imports
12

13
```java
14
import groovy.toml.TomlSlurper;
15
import groovy.toml.TomlBuilder;
16
import groovy.toml.TomlRuntimeException;
17

18
// Additional imports for usage examples
19
import java.io.*;
20
import java.nio.file.Path;
21
import java.nio.file.Paths;
22
import java.util.*;
23
import groovy.lang.Closure;
24
```
25

26
## Basic Usage
27

28
```java
29
import groovy.toml.TomlSlurper;
30
import groovy.toml.TomlBuilder;
31

32
// Parsing TOML
33
TomlSlurper slurper = new TomlSlurper();
34
Object result = slurper.parseText("""
35
    title = "TOML Example"
36
    
37
    [database]
38
    server = "192.168.1.1"
39
    ports = [ 8001, 8001, 8002 ]
40
    connection_max = 5000
41
    enabled = true
42
""");
43

44
// Access parsed data using GPath expressions
45
String title = result.title;
46
String server = result.database.server;
47
List<Integer> ports = result.database.ports;
48

49
// Building TOML
50
TomlBuilder builder = new TomlBuilder();
51
builder.call(Map.of(
52
    "title", "Generated TOML",
53
    "database", Map.of(
54
        "server", "localhost",
55
        "port", 5432
56
    )
57
));
58
String tomlOutput = builder.toString();
59
```
60

61
## Capabilities
62

63
### TOML Parsing
64

65
Parse TOML documents into Groovy data structures using TomlSlurper.
66

67
```java { .api }
68
/**
69
 * TOML parser that converts TOML text into Groovy data structures
70
 */
71
public class TomlSlurper {
72
    /** Creates a new TomlSlurper instance */
73
    public TomlSlurper();
74
    
75
    /** Parse TOML string into Groovy objects */
76
    public Object parseText(String toml);
77
    
78
    /** Parse TOML from Reader into Groovy objects */
79
    public Object parse(Reader reader);
80
    
81
    /** Parse TOML from InputStream into Groovy objects */
82
    public Object parse(InputStream stream);
83
    
84
    /** Parse TOML from File into Groovy objects */
85
    public Object parse(java.io.File file) throws IOException;
86
    
87
    /** Parse TOML from Path into Groovy objects */
88
    public Object parse(Path path) throws IOException;
89
}
90
```
91

92
**Usage Examples:**
93

94
```java
95
import groovy.toml.TomlSlurper;
96
import java.io.*;
97

98
TomlSlurper slurper = new TomlSlurper();
99

100
// Parse from string
101
Object data = slurper.parseText("name = 'example'\nvalue = 42");
102

103
// Parse from file
104
Object fileData = slurper.parse(new File("config.toml"));
105

106
// Parse from InputStream
107
try (InputStream stream = new FileInputStream("config.toml")) {
108
    Object streamData = slurper.parse(stream);
109
}
110

111
// Parse from Reader
112
try (Reader reader = new FileReader("config.toml")) {
113
    Object readerData = slurper.parse(reader);
114
}
115

116
// Parse from Path
117
Object pathData = slurper.parse(Paths.get("config.toml"));
118
```
119

120
### TOML Building
121

122
Construct TOML documents programmatically using TomlBuilder's DSL syntax.
123

124
```java { .api }
125
/**
126
 * Builder for creating TOML payloads using Groovy DSL syntax
127
 */
128
public class TomlBuilder extends GroovyObjectSupport implements Writable {
129
    /** Creates a new TomlBuilder instance */
130
    public TomlBuilder();
131
    
132
    /** Get the internal content object */
133
    public Object getContent();
134
    
135
    /** Create TOML from named arguments/map */
136
    public Object call(Map m);
137
    
138
    /** Create TOML array from list */
139
    public Object call(List l);
140
    
141
    /** Create TOML array from varargs */
142
    public Object call(Object... args);
143
    
144
    /** Create TOML array applying closure to collection items */
145
    public Object call(Iterable coll, Closure c);
146
    
147
    /** Create TOML array applying closure to collection items */
148
    public Object call(Collection coll, Closure c);
149
    
150
    /** Create TOML object from closure DSL */
151
    public Object call(Closure c);
152
    
153
    /** Dynamic method calls for DSL building */
154
    public Object invokeMethod(String name, Object args);
155
    
156
    /** Serialize to TOML string */
157
    public String toString();
158
    
159
    /** Write TOML to Writer (Writable interface) */
160
    public Writer writeTo(Writer out) throws IOException;
161
}
162
```
163

164
**Usage Examples:**
165

166
```java
167
import groovy.toml.TomlBuilder;
168
import groovy.lang.Closure;
169
import java.io.StringWriter;
170
import java.util.*;
171

172
TomlBuilder builder = new TomlBuilder();
173

174
// Build from Map
175
builder.call(Map.of(
176
    "name", "John Doe",
177
    "age", 30,
178
    "active", true
179
));
180

181
// Build from List (creates array)
182
builder.call(Arrays.asList("apple", "banana", "cherry"));
183

184
// Build from varargs (creates array)
185
builder.call("red", "green", "blue");
186

187
// DSL-style building (requires Groovy context)
188
// builder.database {
189
//     host "localhost"
190
//     port 5432
191
//     credentials {
192
//         username "admin"
193
//         password "secret"
194
//     }
195
// }
196

197
// Serialize to string
198
String tomlOutput = builder.toString();
199

200
// Write to Writer
201
StringWriter writer = new StringWriter();
202
builder.writeTo(writer);
203
String result = writer.toString();
204
```
205

206
### Error Handling
207

208
Handle TOML processing errors with TomlRuntimeException.
209

210
```java { .api }
211
/**
212
 * Runtime exception for TOML parsing/building errors
213
 */
214
public class TomlRuntimeException extends GroovyRuntimeException {
215
    /** Exception with message */
216
    public TomlRuntimeException(String msg);
217
    
218
    /** Exception with cause */
219
    public TomlRuntimeException(Throwable cause);
220
    
221
    /** Exception with message and cause */
222
    public TomlRuntimeException(String msg, Throwable cause);
223
}
224
```
225

226
**Usage Examples:**
227

228
```java
229
import groovy.toml.TomlSlurper;
230
import groovy.toml.TomlRuntimeException;
231

232
TomlSlurper slurper = new TomlSlurper();
233

234
try {
235
    // This will throw TomlRuntimeException for invalid TOML
236
    Object result = slurper.parseText("invalid = toml = syntax");
237
} catch (TomlRuntimeException e) {
238
    System.err.println("TOML parsing failed: " + e.getMessage());
239
    e.printStackTrace();
240
}
241
```
242

243
## Data Type Mappings
244

245
TOML types are automatically converted to appropriate Java/Groovy types:
246

247
| TOML Type | Java/Groovy Type |
248
|-----------|------------------|
249
| String | `java.lang.String` |
250
| Integer | `java.lang.Integer` |
251
| Float | `java.lang.BigDecimal` |
252
| Boolean | `boolean` (true/false) |
253
| Date | `java.util.Date` (yyyy-MM-dd'T'HH:mm:ssZ format) |
254
| Array | `java.util.ArrayList` |
255
| Table | `java.util.LinkedHashMap` |
256
| null | `null` |
257
258
## GPath Expression Support
259

260
TomlSlurper results support Groovy's GPath expressions for convenient data navigation:
261

262
```java
263
TomlSlurper slurper = new TomlSlurper();
264
Object config = slurper.parseText("""
265
    [database]
266
    hosts = ["db1.example.com", "db2.example.com"]
267
    
268
    [[servers]]
269
    name = "alpha"
270
    ip = "10.0.0.1"
271
    
272
    [[servers]]
273
    name = "omega"
274
    ip = "10.0.0.2"
275
""");
276

277
// GPath navigation (in Groovy context)
278
// String firstHost = config.database.hosts[0];
279
// List<String> serverNames = config.servers.name;
280
// String alphaIp = config.servers.find { it.name == "alpha" }.ip;
281
```
282

283
## Installation Requirements
284

285
This library requires:
286
- Apache Groovy 4.0.0 or later
287
- Jackson TOML dataformat dependency (automatically included)
288
- Java 8 or later
289

290
Add to your Gradle build file:
291

292
```gradle
293
dependencies {
294
    implementation 'org.apache.groovy:groovy-toml:5.0.0'
295
}
296
```
297

298
For Maven:
299

300
```xml
301
<dependency>
302
    <groupId>org.apache.groovy</groupId>
303
    <artifactId>groovy-toml</artifactId>
304
    <version>5.0.0</version>
305
</dependency>
306
```
307

308
## Notes
309

310
- All classes are marked with `@Incubating` annotation, indicating the API may change in future versions
311
- Built on Jackson's TOML dataformat for high-performance parsing
312
- Integrates seamlessly with Groovy's object model and DSL capabilities
313
- Null values in TOML are represented as Groovy null, not singleton objects
314
- The library is part of the optional groovy-toml module in the Apache Groovy ecosystem