Source Code

This module provides everything necessary to parse and generate Tom's Obvious, Minimal Language (TOML) documents.

As described in the TOML documentation:

TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics. TOML is designed to map unambiguously to a hash table. TOML should be easy to parse into data structures in a wide variety of languages.

Example TOML Document

# This is a TOML document.

title = "TOML Example"

name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00 # First class dates

server = ""
ports = [ 8001, 8001, 8002 ]
connection_max = 5000
enabled = true


# Indentation (tabs and/or spaces) is allowed but not required
ip = ""
dc = "eqdc10"

ip = ""
dc = "eqdc10"

data = [ ["gamma", "delta"], [1, 2] ]

# Line breaks are OK when inside arrays
hosts = [


Use the parseToml() top-level function to parse a TOML document into a TomlTable:

import ceylon.toml {
    parseToml, TomlTable, TomlParseException
import ceylon.time.timezone {

value sampleDocument = ...;
TomlTable|TomlParseException table = parseToml(sampleDocument);
if (is TomlParseException table) {
    throw table;
assert (is TomlTable owner = table["owner"]);
assert (is String ownerName = owner["name"]);
assert (is ZoneDateTime ownerDOB = owner["dob"]);
print("``ownerName`` was born at ``ownerDOB``");

Convenience getters such as TomlTable.getString() and TomlTable.getZoneDateTimeOrNull() can be used when the item type is known:

TomlTable owner = table.getTomlTable("owner");
String ownerName = owner.getString("name");
ZoneDateTime? ownerDOB = owner.getZoneDateTimeOrNull("dob");
print("``ownerName`` was born at ``ownerDOB else "an unknown time!"``");

TomlTables are also MutableLists, and TomlTables are also MutableMaps, and can be iterated and modified as regular collections:

String people =
        firstName = \"Joe\"
        lastName = \"Blow\"

        firstName = \"John\"
        lastName = \"Smith\"
assert (is TomlTable data = parseToml(people));
data.getTomlArray("people").add {
    TomlTable {
        "firstName" -> "Jane",
        "lastName" -> "Doe"
for (person in data.getTomlArray("people")) {
    assert (is TomlTable person);
    print("``person.getString("lastName")``, \


Blow, Joe
Smith, John
Doe, Jane

Error Handling

parseToml() returns the union TomlTable|TomlParseException. If a TomlParseException is returned, it will contain:

  • a brief description of the first error that was found and a count of the total number of errors,

  • a listing of all errors, including line number information, and

  • a TomlTable containing the portions of the document that could be parsed without error.

The following program can be used to parse a document and report all errors, if any:

import ceylon.toml {
    parseToml, TomlTable, TomlParseException

String tomlDocument = ...;
switch (result = parseToml(tomlDocument))
case (is TomlParseException) {
    printAll {
        separator = "\n"; => "error: ``e``");
    print("\n``result.errors.size`` errors\n");
case (is TomlTable) {
    // process(result);

Generating TOML Documents

formatToml() can be used to generate a TOML document from a TomlTable or a Map<Anything, Anything>. In either case, the argument must represent a valid TOML document, with Strings for keys and TomlValues, Maps, or Lists for values.

The code below produces a portion of the “Exampe TOML Document”:

    import ceylon.time.timezone {
        zoneDateTime, timeZone
    import ceylon.toml {
        TomlTable, TomlArray, formatToml

    shared void run() {
        value document = TomlTable {
            "title" -> "TOML Example",
            "owner" -> TomlTable {
                "name" -> "Tom Preston-Werner",
                "dob" -> zoneDateTime {
                    timeZone = timeZone.offset {
                        hours = -8;
                    year = 1979;
                    month = 5;
                    date = 27;
                    hour = 7;
                    minutes = 32;
            "hosts" -> TomlArray {
                "alpha", "omega"

A parser for Tom's Obvious, Minimal Language (TOML)


A parser for Tom's Obvious, Minimal Language (TOML)

TomlValueSource Codeshared TomlValue=> TomlTable|TomlArray|Time|Date|DateTime|ZoneDateTime|Boolean|Float|Integer|String

A TOML value.

formatTomlSource Codeshared String formatToml(Map<String,Object> tomlTable)

Generate a TOML document from the given Map. For added type safety, it is recommended that the argument be a TomlTable, although any Map with valid content can be used.

Note that all keys must be Strings, and all values must be TomlValues, Maps, or Lists. No type coercion is performed by this function.

parseTomlSource Codeshared TomlTable|TomlParseException parseToml({Character*} input)

Parse a TOML document.

TomlArraySource Codeshared final TomlArray

A TOML Array.

TomlTableSource Codeshared final TomlTable

A TOML Table.

TomlParseExceptionSource Codeshared TomlParseException

A ParseException that may be thrown by parseToml().