CtrlK
BlogDocsLog inGet started
Tessl Logo

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

Pending
Overview
Eval results
Files

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

Install with Tessl CLI

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

docs

index.md

tile.json