or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-org-apache-groovy--groovy-toml

TOML parsing and building library for Apache Groovy that provides TomlSlurper for parsing TOML documents and TomlBuilder for constructing TOML from Groovy DSL

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/org.apache.groovy/groovy-toml@5.0.x

To install, run

npx @tessl/cli install tessl/maven-org-apache-groovy--groovy-toml@5.0.0

index.mddocs/

Groovy TOML

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.

Package Information

  • Package Name: org.apache.groovy:groovy-toml
  • Package Type: maven
  • Language: Java (for Groovy)
  • Installation: Add dependency to your build.gradle: implementation 'org.apache.groovy:groovy-toml:5.0.0'

Core Imports

import groovy.toml.TomlSlurper;
import groovy.toml.TomlBuilder;
import groovy.toml.TomlRuntimeException;

// Additional imports for usage examples
import java.io.*;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.*;
import groovy.lang.Closure;

Basic Usage

import groovy.toml.TomlSlurper;
import groovy.toml.TomlBuilder;

// Parsing TOML
TomlSlurper slurper = new TomlSlurper();
Object result = slurper.parseText("""
    title = "TOML Example"
    
    [database]
    server = "192.168.1.1"
    ports = [ 8001, 8001, 8002 ]
    connection_max = 5000
    enabled = true
""");

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

// Building TOML
TomlBuilder builder = new TomlBuilder();
builder.call(Map.of(
    "title", "Generated TOML",
    "database", Map.of(
        "server", "localhost",
        "port", 5432
    )
));
String tomlOutput = builder.toString();

Capabilities

TOML Parsing

Parse TOML documents into Groovy data structures using TomlSlurper.

/**
 * TOML parser that converts TOML text into Groovy data structures
 */
public class TomlSlurper {
    /** Creates a new TomlSlurper instance */
    public TomlSlurper();
    
    /** Parse TOML string into Groovy objects */
    public Object parseText(String toml);
    
    /** Parse TOML from Reader into Groovy objects */
    public Object parse(Reader reader);
    
    /** Parse TOML from InputStream into Groovy objects */
    public Object parse(InputStream stream);
    
    /** Parse TOML from File into Groovy objects */
    public Object parse(java.io.File file) throws IOException;
    
    /** Parse TOML from Path into Groovy objects */
    public Object parse(Path path) throws IOException;
}

Usage Examples:

import groovy.toml.TomlSlurper;
import java.io.*;

TomlSlurper slurper = new TomlSlurper();

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

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

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

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

// Parse from Path
Object pathData = slurper.parse(Paths.get("config.toml"));

TOML Building

Construct TOML documents programmatically using TomlBuilder's DSL syntax.

/**
 * Builder for creating TOML payloads using Groovy DSL syntax
 */
public class TomlBuilder extends GroovyObjectSupport implements Writable {
    /** Creates a new TomlBuilder instance */
    public TomlBuilder();
    
    /** Get the internal content object */
    public Object getContent();
    
    /** Create TOML from named arguments/map */
    public Object call(Map m);
    
    /** Create TOML array from list */
    public Object call(List l);
    
    /** Create TOML array from varargs */
    public Object call(Object... args);
    
    /** Create TOML array applying closure to collection items */
    public Object call(Iterable coll, Closure c);
    
    /** Create TOML array applying closure to collection items */
    public Object call(Collection coll, Closure c);
    
    /** Create TOML object from closure DSL */
    public Object call(Closure c);
    
    /** Dynamic method calls for DSL building */
    public Object invokeMethod(String name, Object args);
    
    /** Serialize to TOML string */
    public String toString();
    
    /** Write TOML to Writer (Writable interface) */
    public Writer writeTo(Writer out) throws IOException;
}

Usage Examples:

import groovy.toml.TomlBuilder;
import groovy.lang.Closure;
import java.io.StringWriter;
import java.util.*;

TomlBuilder builder = new TomlBuilder();

// Build from Map
builder.call(Map.of(
    "name", "John Doe",
    "age", 30,
    "active", true
));

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

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

// DSL-style building (requires Groovy context)
// builder.database {
//     host "localhost"
//     port 5432
//     credentials {
//         username "admin"
//         password "secret"
//     }
// }

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

// Write to Writer
StringWriter writer = new StringWriter();
builder.writeTo(writer);
String result = writer.toString();

Error Handling

Handle TOML processing errors with TomlRuntimeException.

/**
 * Runtime exception for TOML parsing/building errors
 */
public class TomlRuntimeException extends GroovyRuntimeException {
    /** Exception with message */
    public TomlRuntimeException(String msg);
    
    /** Exception with cause */
    public TomlRuntimeException(Throwable cause);
    
    /** Exception with message and cause */
    public TomlRuntimeException(String msg, Throwable cause);
}

Usage Examples:

import groovy.toml.TomlSlurper;
import groovy.toml.TomlRuntimeException;

TomlSlurper slurper = new TomlSlurper();

try {
    // This will throw TomlRuntimeException for invalid TOML
    Object result = slurper.parseText("invalid = toml = syntax");
} catch (TomlRuntimeException e) {
    System.err.println("TOML parsing failed: " + e.getMessage());
    e.printStackTrace();
}

Data Type Mappings

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

TOML TypeJava/Groovy Type
Stringjava.lang.String
Integerjava.lang.Integer
Floatjava.lang.BigDecimal
Booleanboolean (true/false)
Datejava.util.Date (yyyy-MM-dd'T'HH:mm:ssZ format)
Arrayjava.util.ArrayList
Tablejava.util.LinkedHashMap
nullnull

GPath Expression Support

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

TomlSlurper slurper = new TomlSlurper();
Object config = slurper.parseText("""
    [database]
    hosts = ["db1.example.com", "db2.example.com"]
    
    [[servers]]
    name = "alpha"
    ip = "10.0.0.1"
    
    [[servers]]
    name = "omega"
    ip = "10.0.0.2"
""");

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

Installation Requirements

This library requires:

  • Apache Groovy 4.0.0 or later
  • Jackson TOML dataformat dependency (automatically included)
  • Java 8 or later

Add to your Gradle build file:

dependencies {
    implementation 'org.apache.groovy:groovy-toml:5.0.0'
}

For Maven:

<dependency>
    <groupId>org.apache.groovy</groupId>
    <artifactId>groovy-toml</artifactId>
    <version>5.0.0</version>
</dependency>

Notes

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