toml
import toml
TOML, read for its values or edited in place without disturbing the file around them.
TOML is the format configuration files settle on when they have to be
edited by people and by programs both. This module answers both halves.
parse() and dump() treat a document as data, the way json and
yaml do. edit() treats it as a file somebody wrote, and keeps every
comment, blank line and quoting choice through a change.
The implementation follows TOML v1.0.0 in full.
import toml
var config = toml.parse('[server]\nhost = "localhost"\nport = 8080\n')
echo config['server']['port']
8080
What a value decodes to
| TOML | Zuri |
|---|---|
| string | string |
| integer | number, or bigint past 2^53 |
| float | number |
| boolean | bool |
| offset date-time | DateTime |
| local date-time | LocalDateTime |
| local date | LocalDate |
| local time | LocalTime |
| array | list |
| table | dict |
Zuri’s number is an IEEE-754 double, exact only to 2^53. TOML requires
the full signed 64-bit range, so an integer past what a double can carry
decodes to a bigint instead of rounding silently. An integer outside
the 64-bit range is a parse error, which is what TOML asks for.
Integers, floats, and the one thing that does not round-trip
The same double is behind 1 and 1.0, and nothing afterwards tells
them apart. Encoding has to guess, and it guesses integer whenever a
number has no fractional part. Wrap a number in Float to settle it:
import toml
echo toml.dump({ a: 1.0, b: toml.Float(1.0) })
a = 1
b = 1.0
This is the only place a value changes type across a parse() and
dump() pair. edit() is not affected: it never re-spells a value it
was not asked to change.
Editing a file in place
edit() returns a Document, which knows the text it came from.
Rendering one nobody touched reproduces the input byte for byte, and an
edit disturbs only the line it lands on:
import toml
var doc = toml.edit('# what we ship\n[package]\nname = "app"\nversion = "0.9.0" # bump me\n')
doc.set('package.version', '1.0.0')
doc.table('dependencies').set('http', '^2.0')
echo doc.to_string()
# what we ship
[package]
name = "app"
version = "1.0.0" # bump me
[dependencies]
http = "^2.0"
The comment stayed, the header stayed, and the trailing comment on the line that changed stayed with it.
The toml API
Every public name in toml, wherever it is declared. Each links to the
page that documents it.
| Name | Kind | Summary |
|---|---|---|
toml.Array | class | A TOML array, holding its items and the trivia between them. |
toml.ArrayOfTables | class | A [[header]] array of tables. |
toml.DateTime | class | A date and time with a UTC offset, TOML’s offset-date-time. |
toml.Document | class | A whole TOML document: every table in it, and every byte between them. |
toml.EditError | class | An edit that the document cannot accept. |
toml.EncodeError | class | A Zuri value that cannot be written as TOML. |
toml.Entry | class | One key = value pair. |
toml.Float | class | A number that must be written as a TOML float. |
toml.InlineTable | class | A TOML inline table, holding its entries and the trivia between them. |
toml.LocalDate | class | A calendar date with no time and no offset, TOML’s local-date. |
toml.LocalDateTime | class | A date and a wall-clock time with no offset, TOML’s local-date-time. |
toml.LocalTime | class | A wall-clock time with no date and no offset, TOML’s local-time. |
toml.ParseError | class | Text that is not valid TOML. |
toml.Table | class | A table: a [header] block, the root of a document, or a parent that only exists because something below it… |
toml.TomlError | class | Base class for every error this module raises. |
toml.Value | class | One value in a document: a scalar, an array, or an inline table. |
toml.document | function | Builds a Document from a plain Zuri value. |
toml.document.spell_basic_string | function | Returns text as a TOML basic string, quoted and escaped. |
toml.document.spell_float | function | Returns value as a TOML float, including the inf and nan spellings TOML defines. |
toml.document.spell_integer | function | Returns value as a TOML integer. |
toml.document.spell_key | function | Returns name as TOML would spell it as a key: bare when every character allows it, and quoted when not. |
toml.document.spell_multiline_string | function | Returns text as a TOML multi-line basic string. |
toml.document.spell_value | function | Builds the Value node for a plain Zuri value, choosing the TOML spelling as it goes. |
toml.dump | function | Returns value as TOML text. |
toml.dump_file | function | Writes value to the file at path as TOML, creating or overwriting it. |
toml.edit | function | Parses TOML text into a Document, which remembers how it was written. |
toml.edit_file | function | Reads the TOML file at path into a Document. |
toml.encoder.encode | function | Builds the document for a Zuri dictionary. |
toml.load_file | function | Reads the TOML file at path and returns it as a plain Zuri dictionary. |
toml.parse | function | Parses TOML text and returns it as a plain Zuri dictionary. |
toml.parser.parse | function | Reads TOML text and returns the document tree it describes. |
Submodules
| Module | Reached as | Summary |
|---|---|---|
toml.document | toml.document.* | The document tree, which is the text. |
toml.encoder | import toml.encoder | Turning a plain Zuri value into a document. |
toml.errors | toml.errors.* | Every error the toml module raises, under one root. |
toml.parser | import toml.parser | Reading TOML text into the document tree, losing nothing. |
toml.values | toml.values.* | The TOML types that Zuri has no built-in equal for. |
Functions
parse()
toml.parse(text: string) -> dict
Parses TOML text and returns it as a plain Zuri dictionary.
A TOML document is always a table, so the result is always a dictionary, empty when the text held nothing but comments.
import toml
var config = toml.parse('title = "example"\n[owner]\nname = "Ada"\n')
echo config['title']
echo config['owner']['name']
example
Ada
Parameters
text(string) — The TOML text.
Returns dict
Raises ParseError On any syntax or structural error, carrying the
line and column it stopped at.
load_file()
toml.load_file(path: string) -> dict
Reads the TOML file at path and returns it as a plain Zuri dictionary.
import toml
var config = toml.load_file('zuri.toml')
echo config['package']['name']
Parameters
path(string) — Filesystem path to the TOML file.
Returns dict
Raises ParseError On any syntax or structural error.
Raises Error On any file error.
dump()
toml.dump(value, options: ?dict) -> string
Returns value as TOML text.
The result always ends in a line break. Keys keep the order the
dictionary holds them in unless sort_keys says otherwise.
import toml
echo toml.dump({
title: 'example',
owner: { name: 'Ada', active: true },
ports: [8000, 8001],
})
title = "example"
ports = [8000, 8001]
[owner]
name = "Ada"
active = true
Parameters
value(dict) — The value to write. A TOML document is a table, so this has to be a dictionary.options(?dict) —sort_keys(defaultfalse) writes keys in sorted order instead of insertion order.inline_threshold(default0, off) writes a flat table inline when its inline form is no longer than this many characters.multiline_strings(defaulttrue) writes a string holding a newline in triple quotes rather than escaping it.array_width(default80) is the length past which an array breaks onto one line per item.
Returns string
Raises EncodeError If value is not a dictionary, holds a nil
or a value with no TOML spelling, has a non-string key, or contains
itself.
dump_file()
toml.dump_file(path: string, value, options: ?dict)
Writes value to the file at path as TOML, creating or overwriting
it.
import toml
toml.dump_file('config.toml', {
server: { host: '0.0.0.0', port: 8080 },
})
Parameters
path(string) — Filesystem path to write to.value(dict) — The value to write.options(?dict) — The same optionsdump()takes.
Raises EncodeError If the value cannot be written.
Raises Error On any file error.
edit()
toml.edit(text: string) -> Document
Parses TOML text into a Document, which remembers how it was written.
This is the one to reach for when the file already exists and belongs to
somebody. A Document renders back byte for byte until it is changed,
and a change touches only what it names.
import toml
var doc = toml.edit('[a]\nx = 1 # keep me\ny = 2\n')
doc.set('a.x', 99)
doc.remove('a.y')
echo doc.to_string()
[a]
x = 99 # keep me
Parameters
text(string) — The TOML text.
Returns Document
Raises ParseError On any syntax or structural error.
edit_file()
toml.edit_file(path: string) -> Document
Reads the TOML file at path into a Document.
Document.save() writes it back.
import toml
var doc = toml.edit_file('zuri.toml')
doc.set('package.version', '2.0.0')
doc.save('zuri.toml')
Parameters
path(string) — Filesystem path to the TOML file.
Returns Document
Raises ParseError On any syntax or structural error.
Raises Error On any file error.
document()
toml.document(value, options: ?dict) -> Document
Builds a Document from a plain Zuri value.
dump() is this followed by to_string(). Reach for this one when the
document is going to be edited before it is written, or when a generated
file should be handed to the same code that handles a parsed one.
import toml
var doc = toml.document({ package: { name: 'app' } })
doc.set('package.version', '0.1.0')
echo doc.to_string()
[package]
name = "app"
version = "0.1.0"
Parameters
value(dict) — The value to write.options(?dict) — The same optionsdump()takes.
Returns Document
Raises EncodeError If the value cannot be written.
2026, Richard Ore and The Zuri Contributors