Crate tomlproc 

A self-contained TOML 1.1.0 parser and serializer.

tomlproc implements the whole of TOML 1.1.0 – every string flavour, all four date-time types, dotted keys, inline tables and arrays of tables – with no dependencies outside the standard library.

Parsing

parse turns a document into a Table, an insertion-ordered map of Values:

let doc = tomlproc::parse(r#"
    title = "TOML Example"

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

    [[server]]
    ip = "10.0.0.1"
    ports = [8000, 8001]
"#).unwrap();

assert_eq!(doc["title"].as_str(), Some("TOML Example"));
assert_eq!(doc["owner"]["dob"].as_datetime().unwrap().date.unwrap().year, 1979);
assert_eq!(doc["server"][0]["ports"][1].as_integer(), Some(8001));

Errors carry the line and column at which the problem was found:

let error = tomlproc::parse("a = 1\nb = [1, 2").unwrap_err();
assert_eq!(error.line(), 2);
assert_eq!(error.to_string(), "TOML parse error at line 2, column 5: unterminated array");

Building and writing

Tables can be built by hand and written back out with to_string:

let mut package = tomlproc::Table::new();
package.insert("name", "tomlproc");
package.insert("edition", "2024");

let mut doc = tomlproc::Table::new();
doc.insert("package", package);

assert_eq!(tomlproc::to_string(&doc), "[package]\nname = \"tomlproc\"\nedition = \"2024\"\n");

Parsing and serializing round-trip: key order, and the shape of tables and arrays of tables, are preserved. Formatting is not – comments, blank lines and the choice between a header and an inline table belong to the document, not to the value model.

Features

Feature	Default	What it adds
std	yes	Implies alloc, and indexes tables by hash
alloc	via std	The value model, the parser and the serializer
serde	no	tomlproc::serde; implies alloc

The crate is #![no_std]. With alloc but not std everything here works unchanged, on ordered maps instead of hash maps; the public API is the same, and so is what the parser accepts. Turn alloc off too and what is left is Datetime and the types it is made of, which parse and format with no allocator at all – the value model cannot follow, since a Table owns its keys and values.

# embedded, with a heap
tomlproc = { version = "0.1", default-features = false, features = ["alloc"] }

Beyond the value model

parse_spans also reports where each value was written, so a value that turns out to be wrong later can be pointed back at its line and column.

The optional serde feature adds tomlproc::serde, which maps documents onto your own types. It is off by default, and it is the only thing that gives the crate a dependency.

Conformance

Everything TOML 1.1.0 added over 1.0.0 is accepted: newlines and trailing commas inside inline tables, the \e and \xHH string escapes, and times written without seconds. Since 1.1 only adds to 1.0, every 1.0 document still parses. What is written stays within 1.0, so a document this crate produces can be read by an older parser: seconds are always written, inline tables stay on one line, and control characters are escaped as \u00XX.

The parser is strict, and rejects what the specification calls invalid: duplicate keys, extending an inline table, redefining a table, mismatched quotes, out-of-range integers and dates, bad underscore or leading-zero placement in numbers, control characters in strings and comments, and a key of any kind landing on a table that is already defined. A bare carriage return is an error; \r\n in a multi-line string is normalized to \n, as the specification permits.

Modules

serdeserde

Mapping TOML documents onto your own types, with serde.

Macros

arrayalloc

Builds an array Value whose elements need not share a type.

tablealloc

Builds a Table from key => value pairs.

Structs

Date

A calendar date: year, month and day.

Datetime

A TOML date-time: an offset date-time, a local date-time, a local date or a local time, depending on which fields are present.

Error

An error produced while parsing or serializing TOML.

IntoIteralloc

An owning iterator over a table’s entries, in insertion order.

Iteralloc

An iterator over a table’s entries, in insertion order.

IterMutalloc

A mutable iterator over a table’s entries, in insertion order.

Keysalloc

An iterator over a table’s keys, in insertion order.

OccupiedEntryalloc

An entry for a key that is in the table.

Spanalloc

The stretch of source a value came from.

Spansalloc

Where every value in a document was written, keyed by its dotted path.

Tablealloc

A TOML table: a map from keys to Values that remembers the order in which keys were first inserted.

Time

A time of day, with nanosecond precision.

VacantEntryalloc

An entry for a key that is not in the table.

Valuesalloc

An iterator over a table’s values, in insertion order.

ValuesMutalloc

A mutable iterator over a table’s values, in insertion order.

Enums

DatetimeKind

Which of TOML’s four date-time types a Datetime holds.

Entryalloc

A view into one entry of a Table, vacant or occupied.

Offset

The time zone offset of an offset date-time.

Valuealloc

Any TOML value.

Functions

parsealloc

Parses a TOML document.

parse_bytesalloc

Parses a TOML document from bytes, which must be UTF-8.

parse_spansalloc

Parses a TOML document, also reporting where each value was written.

to_stringalloc

Serializes a table as a TOML document.

to_string_prettyalloc

Serializes a table as a TOML document, laid out for a human to read.