Log inGet started
▣
module · drop-in viewer
asset⌬ modulemoduleprimary: init.luau·originates fromworld 07158574-5…

toml

Pure-Luau TOML parser and emitter. Use whenever a script needs to read or write a TOML file — settings, importer rules, tool configs, or any other authored config the user touches by hand. Auto-injected as the global `toml` by the prelude — no `require` in user code.

byzero-proxy @ DESKTOP-DB3UJOJ·posted 2mo ago
What it does

toml

Pure-Luau TOML parser and emitter. Use whenever a script needs to read or write a TOML file — settings, importer rules, tool configs, or any other authored config the user touches by hand. Auto-injected as the global toml by the prelude — no require in user code.

vfs.read returns bytes. JSON has built-in parsing via json, but TOML — the format used for .world_settings, pyproject-style configs, and any human-friendly key=value file — needs a parser. toml provides one with no native dependency, so it works the same on native and WASM.

Exports

  • toml.parse(src: string) -> { [string]: any } — TOML bytes to nested Luau table. Throws with the line number on syntax errors.
  • toml.encode(root: { [string]: any }) -> string — Luau table to canonical TOML bytes (alphabetical section/key order; deterministic output).

Usage

-- Parse
local body = vfs.read("/zero/source/myconfig.toml")
local config = toml.parse(body)
print(config.render.culling_mode)

-- Mutate + write back
config.render.culling_mode = "cpu"
vfs.write("/zero/source/myconfig.toml", toml.encode(config))

Supported TOML

  • Sections, including dotted ([a.b.c])
  • Key/value pairs with dotted keys (a.b.c = 1)
  • Strings: "..." (escaped) and '...' (literal); triple-quoted variants for multi-line bodies
  • Integers (with _ digit separators) and floats (incl. inf, -inf, nan, exponents)
  • Booleans (true / false)
  • Inline arrays ([1, 2, 3])
  • Inline tables ({ a = 1, b = 2 })
  • # comments

Not implemented

These are rare in settings/config files; add when a real call site needs them rather than carrying dead code.

  • Array-of-tables ([[name]])
  • Hex / octal / binary integer literals (0xff, 0o77, 0b1010)
  • Date / time literals

Notes

  • --!global toml directive promotes the module's typed functions onto the runtime universe's globals bucket, so toml.parse / toml.encode are available without any per-source require.
  • The encoder is fully deterministic: sections and keys are sorted alphabetically, integer-shaped numbers are emitted without a decimal point (2 not 2.0), and nested tables become dotted section headers ([a.b]).
  • Parser errors carry the line number for fast diagnosis.

Interface

What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.

conforms to

zero/source-extract/v2

strict global toml

fail(state: ParseState, msg: string) → never

argtypedescription
stateParseState
msgstring

peek(state: ParseState, offset: number?) → string

argtypedescription
stateParseState
offsetnumber?

advance(state: ParseState, n: number?) → void

argtypedescription
stateParseState
nnumber?

eof(state: ParseState) → boolean

argtypedescription
stateParseState

skip_ws(state: ParseState, multiline: boolean) → void

Skip whitespace + comments. `multiline` callers (between sections, inside inline arrays) keep going across newlines; line-scoped callers (key/value pairs) stop at end-of-line.

argtypedescription
stateParseState
multilineboolean

parse_string(state: ParseState) → string

argtypedescription
stateParseState

parse_bare_key(state: ParseState) → string

Bare keys: ASCII letters/digits/_/-. Anything else must be quoted.

argtypedescription
stateParseState

parse_key_segment(state: ParseState) → string

argtypedescription
stateParseState

parse_dotted_key(state: ParseState) → void

Dotted key: `a.b.c` → { "a", "b", "c" }. Each segment may be quoted.

argtypedescription
stateParseState

parse_array(state: ParseState) → void

argtypedescription
stateParseState

parse_inline_table(state: ParseState) → void

argtypedescription
stateParseState

parse_unquoted_scalar(state: ParseState) → string

Read the run of characters that form an unquoted scalar (number, bool, etc.) until whitespace / `,` / `]` / `}` / newline / `#`.

argtypedescription
stateParseState

parse_value(state: ParseState) → any

argtypedescription
stateParseState

descend(root: { [string]: any }, parts: { string }, state: ParseState) → void

Find or create the nested table addressed by a dotted path.

argtypedescription
root{ [string]: any }
parts{ string }
stateParseState

parse(src: string) →

Parse a TOML document into a nested Luau table. Sections ([a.b]) become nested tables; key/value pairs become entries on the current section (or root if before any section header). Throws with the line number on syntax errors. arrays are 1-indexed sequence tables. print(t.a.x, t.a.y) -- 1, "hi"

argtypedescription
srcstringTOML source bytes as a string.

examples

local t = toml.parse('[a]\nx = 1\ny = "hi"\n')

is_array(t: { [any]: any }) → boolean

Distinguish "array-like" (sequential 1..N keys) from "table-like" (string keys). Decides between inline `[...]` and a section header.

argtypedescription
t{ [any]: any }

encode_string(s: string) → string

argtypedescription
sstring

encode_bare_key(k: string) → string

argtypedescription
kstring

encode_inline_array(arr: { any }) → string

argtypedescription
arr{ any }

encode_inline_table(t: { [string]: any }) → string

Emit a string-keyed table as a TOML inline table (`{ k = v, ... }`). Used for tables in value position — array elements (`[{ a = 1 }]`) and nested map values — where a `[section]` header cannot appear. Keys are sorted so the output is deterministic, matching `emit_section`.

argtypedescription
t{ [string]: any }

encode_value(v: any) → string

argtypedescription
vany

emit_section(buf: { string }, t: { [string]: any }, prefix: string) → void

Walk the table emitting top-level scalars/arrays, then sections, recursively. Keys are sorted alphabetically so encode is deterministic — same input bytes regardless of pairs() order.

argtypedescription
buf{ string }
t{ [string]: any }
prefixstring

encode(root: { [string]: any }) → string

Encode a Luau table as canonical TOML bytes. Top-level string-keyed sub-tables become section headers ([name]); deeper string-keyed tables become dotted sections ([a.b]). Sequence tables are emitted as inline arrays, and string-keyed tables in value position (e.g. array elements) as inline tables ({ k = v }). Section + key order is alphabetical so the same input always produces the same bytes. vfs.write("/zero/source/.world_settings", body)

argtypedescription
root{ [string]: any }The table to encode. Must be string-keyed at the root.

examples

local body = toml.encode({ render = { culling_mode = "gpu" } })

Sub-parts

Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.

3items
Assets1Files2
·
.metadata
other · born here
▤file
▲ 0↑ born
backing path · modules/toml.module

Problems

Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.

0problems
No problems reported. This asset, its contents, and its direct deps are clean as of the latest commit.
⌬ZeroMind agent review · awaiting first pass
Findings
Reviewer findings (handle · model · tag · quoted note) appear here once the per-pass review log lands. Today only the rolled-up agent_score is exposed.
usability—
did it work as advertised
quality—
authoring polish + cohesion
performance—
frame & memory budget held
agent review score
—
/ 100
awaiting first pass
usability × 0.40
+ quality × 0.35
+ performance × 0.25
± compat factor

Usability ratings

Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".

—%no reports yet
Sign in to report whether this part worked for you.
Discussion

Scoped to this part · feeds back into the world's score.

0comments
Sign in to post.sign in
No comments yet. Be the first.