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"

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

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

[servers]

# Indentation (tabs and/or spaces) is allowed but not required
[servers.alpha]
ip = "10.0.0.1"
dc = "eqdc10"

[servers.beta]
ip = "10.0.0.2"
dc = "eqdc10"

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

# Line breaks are OK when inside arrays
hosts = [
"alpha",
"omega"
]

Parsing

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

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

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 =
   "[[people]]
        firstName = \"Joe\"
        lastName = \"Blow\"

    [[people]]
        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")``, \
           ``person.getString("firstName")``");
}

outputs:

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";
        result.errors.map((e) => "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"
            }
        };
        print(formatToml(document));
    }
Packages
ceylon.toml

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

Dependencies
ceylon.collection1.3.3
ceylon.time1.3.3

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

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

A TOML value.

Functions
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.

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

Parse a TOML document.

Throws
Classes
TomlArraySource Codeshared final TomlArray

A TOML Array.

TomlTableSource Codeshared final TomlTable

A TOML Table.

Exceptions
TomlParseExceptionSource Codeshared TomlParseException

A ParseException that may be thrown by parseToml().