TOML · Opinions Minimal — told at library speed

TOML, told at
library speed.

teptris is the TOML sibling of libleptris: a parser and writer in pure C99 — zero required dependencies, a stable C ABI, opaque handles — with first-class Ruby and Python bindings shaped like tomlib and tomllib.

Get started See the race

Speed with a referee — every figure comes from the open benchmark lane: interleaved runs, pinned competitors, medians, ledger kept in the repository.
Conformance first — 714/714 on BurntSushi’s toml-test (1.1 view), the round-trip property, ASan/UBSan/TSan suites, and a nightly libFuzzer lane.
One core, three surfaces — the same C99 engine from C, Ruby, and Python; a typed-JSON CLI thrown in.

the third hare joins the chase

0/714toml-test, the 1.1 view

0×mixed shape vs tomlc17, dev hardware

0×table-heavy vs cpptoml, dev hardware

0+prebuilt platform gems, per Ruby minor

zerorequired runtime dependencies

What it is

An engine built like a ledger, not a claim

Every performance statement in teptris reproduces from the benchmark lane — interleaved A/B rounds, pinned competitor commits, medians because runner minimums wobble. The 4×-mandate gate shapes were confirmed on developer hardware: mixed 4.13×, cargo 4.67×, deep 4.97×, table 5.84×.

2.9–10.2× / best competitor, per shape

The race, in the open

The CI lane rebuilds tomlc99, tomlc17, cpptoml, toml11 and tomlplusplus at pinned commits on every push and races nine document shapes: 223–386 MB/s parse on the ubuntu cell. The harness, the corpus seed and the ledger (benchmarks/LEDGER.md) ship in the repository.

714/714 toml-test, 1.1 view

Conformant where it counts

The TOML 1.1 draft grammar as a strict superset of 1.0 —\e and \xNN escapes, optional seconds, inline-table newlines, trailing commas. Parse → emit → parse tree-equality, byte-stable emit, ASan/UBSan/TSan suites and a nightly libFuzzer lane standing guard.

1 pass for planned keys

Beyond the DOM

Compile a schema descriptor once, walk a document once, materialize only the planned keys — the descriptor plan ABI (teptris/plan.h, Teptris::TOML.load_schema) for framework adapters. Batch and lazy paths for many-document corpora; zero-copy key views in C.

10+ prebuilt gem rows · 12 abi3 wheels

Packaging that installs

Ruby: fat platform gems with one extension per Ruby minor (3.0–4.0), qemu-built 32-bit ARM, big-endian s390x and ppc64le — the engine source rides every gem. Python: cp310-cp314 + cp39-abi3wheels for every CPython ≥ 3.9. C: cmake --install, pkg-config and a teptris:: CMake export.

The surface

Shaped like the incumbents

Ruby mirrors tomlib (offset datetimes becomeTime, dates become Date); Python mirrorstomllib (TOMLDecodeError and itslineno/colno included). Switching is a require away.

#include <teptris/teptris.h>

teptris_document *doc = NULL;
if (teptris_parse(data, len, NULL, &doc) != TEPTRIS_OK) {
    const teptris_error *e = teptris_document_error(doc);
    /* e->line, e->column (1-based), e->message */
}
const teptris_node *v = teptris_node_table_get(
    teptris_document_root(doc), "key", 3);   /* zero-copy view */
char *out = NULL; size_t out_len = 0;
teptris_document_emit(doc, &out, &out_len);  /* canonical TOML */
teptris_document_free(doc);

require "teptris"

doc = Teptris::TOML.load(<<~TOML)
  title = "teptris"
  [owner]
  name = "t"
TOML
# => {"title" => "teptris", "owner" => {"name" => "t"}}

Teptris::TOML.dump(doc)               # canonical TOML, through the C emitter

begin
  Teptris::TOML.load("a = [1,")
rescue Teptris::ParseError => e
  [e.line, e.column]                  # [1, 8]
end

import teptris

doc = teptris.loads('title = "teptris"\n[owner]\nname = "t"\n')
# => {'title': 'teptris', 'owner': {'name': 't'}}  — tomllib contract

teptris.dumps(doc)                    # canonical TOML, 3.5-14.2x tomli_w

try:
    teptris.loads("a = [1,")
except teptris.TOMLDecodeError as e:
    e.lineno, e.colno                 # the tomllib attributes

$ teptris parse config.toml        # typed-JSON tree (toml-test wire shape)
$ teptris to-json config.toml
$ teptris format config.toml       # canonical TOML
$ teptris validate broken.toml     # exit 1 with line:col on error

The chase begins

Install, three ways

surface	command	what you get
Ruby	`gem install teptris`	a prebuilt platform gem where one exists — otherwise the source gem compiles the vendored engine loudly
Python	`pip install teptris`	a self-contained wheel (version-specific cp310-cp314 or cp39-abi3) — engine statically linked, PGO-built, CPython ≥ 3.9
C	`cmake -B build -S . && cmake --build build`	LTO on by default; `cmake --install` carries headers, pkg-config and the CMake export

The teptris docs — C, Ruby and Python guides →

Fast as hares.
Told at library speed.

teptris v0.1.27 — libteptris v0.1.27, the teptris gem v0.2.47, the teptris package v0.2.23. Repos canonical: teptris, teptris-ruby, teptris-py.

TOML, told atlibrary speed.