toml.document
import toml.document
tomllifts part of this module out to its own top level; each name below is shown with the path that reaches it. Anything still spelledtoml.document.*needsimport toml.document.
The document tree, which is the text.
A TOML file read for its values can throw away everything that is not a
value. A TOML file read so that it can be written back cannot throw away
anything at all: the comment above a key, the blank line between two
tables, the choice of 0x1F over 31, the single quotes around a
Windows path. A program that rewrites a file it did not write has to
leave all of it alone.
So every node here holds two things: what it means, and the exact text
it was. Value keeps the decoded value beside the source spelling that
produced it. Entry keeps the whitespace on each side of its =.
Table keeps the trivia before its header. Rendering is concatenation,
and a document nobody edited comes back byte for byte.
Nodes are built by parser.zu when reading and by encoder.zu when
writing. Reach them through Document, which is what the module’s
public API hands out.
Functions
spell_key()
toml.document.spell_key(name: string) -> string
Returns name as TOML would spell it as a key: bare when every
character allows it, and quoted when not.
An empty key is legal in TOML and must be written "".
Parameters
name(string)
Returns string
spell_basic_string()
toml.document.spell_basic_string(text: string) -> string
Returns text as a TOML basic string, quoted and escaped.
Control characters that have no short escape are written as \uXXXX.
Every other character is passed through as itself, so the result stays
readable for anything that is not a control character.
Parameters
text(string)
Returns string
spell_multiline_string()
toml.document.spell_multiline_string(text: string) -> string
Returns text as a TOML multi-line basic string.
Newlines and single quotes pass through untouched; a run of three quotes and a trailing quote are escaped, since either would close the string early.
Parameters
text(string)
Returns string
spell_integer()
toml.document.spell_integer(value) -> string
Returns value as a TOML integer.
Parameters
value(number|bigint)
Returns string
spell_float()
toml.document.spell_float(value) -> string
Returns value as a TOML float, including the inf and nan spellings
TOML defines.
A whole number gains a .0, because a float that renders without one
reads back as an integer.
Parameters
value(number)
Returns string
spell_value()
toml.document.spell_value(value, path) -> Value
Builds the Value node for a plain Zuri value, choosing the TOML
spelling as it goes.
A string with a newline in it becomes a multi-line basic string; a whole
number becomes an integer; a Float becomes a float whatever its value.
A list becomes a single-line array and a dictionary becomes an inline
table, because this is the spelling a value takes when it is written in
place. Document.table() is how a value becomes a table block instead.
Parameters
value(any)path(?string) — Dotted path used in an error message.
Returns Value
Raises EncodeError If the value has no TOML spelling, or if a list
or dictionary contains itself.
Classes
Value
class toml.Value
One value in a document: a scalar, an array, or an inline table.
kind names the TOML type. value is the decoded Zuri value for a
scalar, or the Array or InlineTable node for a container. raw is
the exact source text of a scalar, which is what makes 0x1F survive a
round trip as 0x1F rather than as 31.
prefix and suffix hold the trivia on each side: whatever sat between
the = and the value, and whatever followed it on the same line, a
trailing comment included.
- printable — has a
@to_string(), soechoandprint()show something useful
Fields
| Field | Type | Description |
|---|---|---|
kind | ||
value | ||
raw | ||
prefix | ||
suffix |
Constructor
toml.Value(kind, value, raw)
Parameters
kind(string) — One ofstring,integer,float,boolean,datetime,local-datetime,local-date,local-time,arrayorinline-table.value(any) — The decoded value, or the container node.raw(?string) — The exact source text, for a scalar.
Value.to_string()
toml.Value.to_string() -> string
Returns the value’s own text, without its surrounding trivia.
Returns string
Value.to_value()
toml.Value.to_value() -> any
Returns the value as a plain Zuri value, with every container below it converted too.
Returns any
Array
class toml.Array
A TOML array, holding its items and the trivia between them.
An array may run across lines and carry comments between its items, so each item keeps its own prefix and suffix and the array keeps whatever sits before the closing bracket.
- printable — has a
@to_string(), soechoandprint()show something useful
Fields
| Field | Type | Description |
|---|---|---|
items | ||
trailing_comma | ||
trailing |
Constructor
toml.Array()
Array.to_string()
toml.Array.to_string() -> string
Returns the array as TOML text, brackets included.
Returns string
Array.to_value()
toml.Array.to_value() -> list
Returns the array as a plain Zuri list.
Returns list
InlineTable
class toml.InlineTable
A TOML inline table, holding its entries and the trivia between them.
An inline table is sealed once written: TOML forbids adding to one after the fact, and this module enforces that on edit as well as on parse.
- printable — has a
@to_string(), soechoandprint()show something useful
Fields
| Field | Type | Description |
|---|---|---|
entries | ||
trailing |
Constructor
toml.InlineTable()
InlineTable.to_string()
toml.InlineTable.to_string() -> string
Returns the inline table as TOML text, braces included.
Returns string
InlineTable.to_value()
toml.InlineTable.to_value() -> dict
Returns the inline table as a plain Zuri dictionary, with dotted keys expanded into nested dictionaries.
Returns dict
Entry
class toml.Entry
One key = value pair.
path is the decoded key, which has more than one element when the key
was dotted. key_raw is the key exactly as written, dots, quotes and
interior spaces included, so a . b stays a . b.
prefix is everything from the end of the previous line to the first
character of the key, which is where a comment above the key lives.
newline is the line terminator, and is empty for an entry inside an
inline table.
- printable — has a
@to_string(), soechoandprint()show something useful
Fields
| Field | Type | Description |
|---|---|---|
path | ||
key_raw | ||
prefix | ||
pre_eq | ||
value | ||
newline |
Constructor
toml.Entry(path, key_raw, value)
Parameters
path(list) — The decoded key path.key_raw(string) — The key exactly as written.value(Value) — The value this key holds.
Entry.to_string()
toml.Entry.to_string() -> string
Returns the whole pair as TOML text, its own trivia included.
Returns string
Entry.comment()
toml.Entry.comment() -> string|nil
Returns the comment written above this key, without its #, the single
space that usually follows it, or the indentation. Returns nil when
there is no comment.
Returns string|nil
Table
class toml.Table
A table: a [header] block, the root of a document, or a parent that
only exists because something below it was written.
entries holds the pairs written directly under this table’s header, in
document order. children maps a name to the Table or ArrayOfTables
below it.
A table is explicit when a header was written for it, and implicit
when it exists only because a deeper table named it. A table brought
into being by a dotted key is marked dotted: TOML allows sub-tables to
be added under one, but forbids reopening it with a header of its own.
- printable — has a
@to_string(), soechoandprint()show something useful
Fields
| Field | Type | Description |
|---|---|---|
document | ||
path | ||
header_raw | ||
prefix | ||
suffix | ||
newline | ||
entries | ||
children | ||
explicit | ||
dotted | ||
is_aot_element |
Constructor
toml.Table(path)
Parameters
path(list) — The full key path from the root.
Table.to_string()
toml.Table.to_string() -> string
Returns this table’s own text: its header when it has one, then every pair written under it.
Child tables are not included. A document renders them in the order their headers appeared, which is not necessarily the order the tree nests them in.
Returns string
Table.to_value()
toml.Table.to_value() -> dict
Returns this table and everything under it as a plain Zuri dictionary.
Returns dict
Table.entry_at()
toml.Table.entry_at(path: list) -> Entry|nil
Returns the Entry whose key path is exactly path, or nil.
Parameters
path(list)
Returns Entry|nil
Table.keys()
toml.Table.keys() -> list
Returns the names of everything this table holds, pairs first and then child tables, in the order they were written.
A dotted key contributes only its first element, which is the name this table actually holds.
Returns list
Table.length()
toml.Table.length() -> number
Returns how many names this table holds.
Returns number
Table.get()
toml.Table.get(path) -> any
Returns the value stored at path, as a plain Zuri value, or nil when
nothing is there.
path is a dotted string or a list of key names. A dotted string splits
on ., so a key that contains a literal dot has to be passed as a list.
Parameters
path(string|list)
Returns any
Table.has()
toml.Table.has(path) -> bool
Returns true when something is stored at path.
Parameters
path(string|list)
Returns bool
Table.set()
toml.Table.set(path, value) -> Entry
Writes value at path, relative to this table.
A key that is already there keeps its line: only the value text changes,
so the spacing around the = and a trailing comment both survive. A key
that is not there is appended to this table, indented to match the pairs
already in it.
Parent tables along path are created as table blocks when they do not
exist. A dictionary passed as value is written as an inline table;
Document.table() is how a dictionary becomes a table block of its own
instead.
Parameters
path(string|list) — A dotted key path, or a list of names.value(any)
Returns Entry — The pair that was written.
Raises EditError If path runs through something that is not a
table, or names a table that already exists.
Raises EncodeError If value has no TOML spelling.
Table.remove()
toml.Table.remove(path) -> bool
Removes whatever sits at path, relative to this table.
A removed pair takes the comment written directly above it with it, because that comment described the pair. The blank lines around it are left alone.
Parameters
path(string|list)
Returns bool — True when something was there to remove.
Table.comment()
toml.Table.comment(key) -> string|nil
Returns the comment written above key, without its #, the single
space that usually follows it, or the indentation. Returns nil when
there is no comment.
Parameters
key(string|list)
Returns string|nil
Table.set_comment()
toml.Table.set_comment(key, text)
Writes text as the comment above key, replacing any comment already
there. Pass nil to remove it.
A text containing newlines becomes one # line per line.
Parameters
key(string|list)text(string|nil)
Raises EditError If key is not in this table.
ArrayOfTables
class toml.ArrayOfTables
A [[header]] array of tables.
Each element is a Table of its own, carrying its own header text and
its own trivia, because each was written separately.
- printable — has a
@to_string(), soechoandprint()show something useful
Fields
| Field | Type | Description |
|---|---|---|
document | ||
path | ||
elements |
Constructor
toml.ArrayOfTables(path)
Parameters
path(list) — The full key path from the root.
ArrayOfTables.to_value()
toml.ArrayOfTables.to_value() -> list
Returns every element as a plain Zuri list of dictionaries.
Returns list
ArrayOfTables.length()
toml.ArrayOfTables.length() -> number
Returns how many elements the array holds.
Returns number
ArrayOfTables.to_string()
toml.ArrayOfTables.to_string()
ArrayOfTables.append()
toml.ArrayOfTables.append() -> Table
Adds a new [[header]] block to the end of the array and returns the
Table it made, which is where that element’s keys go.
Returns Table
ArrayOfTables.element()
toml.ArrayOfTables.element(index: number) -> Table
Returns the element at index, counting from zero.
Parameters
index(number)
Returns Table
Raises EditError If index is outside the array.
Document
class toml.Document
A whole TOML document: every table in it, and every byte between them.
A document that nobody has edited renders back exactly as it was read, byte for byte. An edited one keeps everything the edit did not touch, so a rewritten configuration file still reads as the file somebody wrote.
order is the sequence the table headers appeared in, which is not the
order the tree nests them in: a document may open [a], then [b],
then [a.c], and all three keep their places.
import toml
var doc = toml.edit('# the package\n[package]\nname = "app"\n')
doc.set('package.version', '1.0.0')
echo doc.to_string()
# the package
[package]
name = "app"
version = "1.0.0"
- printable — has a
@to_string(), soechoandprint()show something useful
Fields
| Field | Type | Description |
|---|---|---|
root | ||
order | ||
trailing | ||
bom | ||
newline |
Constructor
toml.Document()
Document.to_string()
toml.Document.to_string() -> string
Returns the whole document as TOML text.
Returns string
Document.to_value()
toml.Document.to_value() -> dict
Returns the document as a plain Zuri dictionary, with every table, array and scalar below it converted too.
Returns dict
Document.get()
toml.Document.get(path) -> any
Returns the value at path, or nil when nothing is there.
Parameters
path(string|list) — A dotted key path, or a list of key names for keys that contain a literal dot.
Returns any
Document.has()
toml.Document.has(path) -> bool
Returns true when something is stored at path.
Parameters
path(string|list)
Returns bool
Document.keys()
toml.Document.keys() -> list
Returns the top-level names the document holds, in the order they were written.
Returns list
Document.length()
toml.Document.length() -> number
Returns how many top-level names the document holds.
Returns number
Document.set()
toml.Document.set(path, value) -> Entry
Writes value at path.
A key that is already there keeps its line, its spacing and its trailing
comment; only the value text changes. A key that is not there is
appended to the table that should hold it, and the table blocks along
path are created when they do not exist.
import toml
var doc = toml.edit('[server]\nhost = "localhost" # bind address\n')
doc.set('server.host', '0.0.0.0')
doc.set('server.port', 8080)
echo doc.to_string()
[server]
host = "0.0.0.0" # bind address
port = 8080
Parameters
path(string|list) — A dotted key path, or a list of names for keys that contain a literal dot.value(any)
Returns Entry — The pair that was written.
Raises EditError If path runs through something that is not a
table, or names a table that already exists.
Raises EncodeError If value has no TOML spelling.
Document.remove()
toml.Document.remove(path) -> bool
Removes whatever sits at path, a pair or a whole table.
A removed pair takes the comment written directly above it with it. Removing a table removes everything under it.
Parameters
path(string|list)
Returns bool — True when something was there to remove.
Document.table()
toml.Document.table(path) -> Table
Returns the table at path, creating it as a table block when it is not
there.
This is how a dictionary becomes a [header] block rather than the
inline table set() would write.
import toml
var doc = toml.edit('name = "app"\n')
doc.table('dependencies').set('http', '^2.0')
echo doc.to_string()
name = "app"
[dependencies]
http = "^2.0"
Parameters
path(string|list)
Returns Table
Raises EditError If path runs through something that is not a
table.
Document.array_of_tables()
toml.Document.array_of_tables(path) -> ArrayOfTables
Returns the array of tables at path, creating an empty one when it is
not there.
append() on the result adds a [[header]] block and returns the
Table it made, which is where the new element’s keys go.
import toml
var doc = toml.edit('')
doc.array_of_tables('bin').append().set('name', 'serve')
echo doc.to_string()
[[bin]]
name = "serve"
Parameters
path(string|list)
Returns ArrayOfTables
Raises EditError If path names something that is not an array of
tables.
Document.save()
toml.Document.save(path: string)
Writes the document to path, creating or overwriting the file.
Parameters
path(string) — Filesystem path to write to.
Raises Error On any file error.
2026, Richard Ore and The Zuri Contributors