toml #

Description

toml is a fully fledged TOML v1.0.0 compatible parser written in pure V. The module is tested against the official compliance tests.

Usage

Parsing files or strings containing TOML is easy.

Simply import the toml module and do:

doc1 := toml.parse_text(<string content>) or { panic(err) }
doc2 := toml.parse_file(<file path>) or { panic(err) }

Example

Here we parse the official TOML example and print out some values.

import toml

const toml_text = '# This is a TOML document.

title = "TOML Example"

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

[database]
server = "192.168.1.1"
ports = [ 8000, 8001, 8002 ]
connection_max = 5000
enabled = true

[servers]

  # Indentation (tabs and/or spaces) is allowed but not required
  [servers.alpha]
  ip = "10.0.0.1"
  dc = "eqdc10"

  [servers.beta]
  ip = "10.0.0.2"
  dc = "eqdc10"

[clients]
data = [ ["gamma", "delta"], [1, 2] ]

# Line breaks are OK when inside arrays
hosts = [
  "alpha",
  "omega"
]'

fn main() {
    doc := toml.parse_text(toml_text) or { panic(err) }
    title := doc.value('title').string()
    println('title: "${title}"')
    ip := doc.value('servers.alpha.ip').string()
    println('Server IP: "${ip}"')
}

Struct conversion

toml.decode[T] decodes TOML text into a struct and toml.encode[T] encodes a struct as TOML. A field maps to the key of the same name; @[toml: <name>] changes the key and @[skip] ignores the field. Fields missing from the document keep their default values. A from_toml(toml.Any) or to_toml() string method on T replaces the generic conversion.

Partial tables preserve the existing defaults inside a present optional struct. When that optional field is none, a table initializes it from the struct's own defaults.

TOML has no struct embedding, so the fields of an embedded struct are read from and written to the same table as the fields of the embedding struct. When decoding, a table named after the embedded struct (e.g. [Db]) is accepted too and takes precedence. Embedded toml.Date, toml.Time and toml.DateTime are scalars, stored under their type name (e.g. Date = 2026-09-30).

Array elements and map values may be scalars, enums, structs, arrays or maps, at any nesting depth, so []JobTitle, map[string][]int and [][]map[string]Item all decode. An element that does not fit the element type, such as a number where a struct is expected, is skipped. An enum element must be an integer, so a string, boolean, float, array or table in an enum position is skipped rather than coerced; a plain enum field still follows Any.int(), which reads a non-numeric value as 0.

import toml

struct Db {
    host string
    port int
}

struct Config {
    Db
    name   string @[toml: app_name]
    secret string @[skip]
}

config := toml.decode[Config]('app_name = "app"\nhost = "localhost"\nport = 5432')!
assert config.host == 'localhost' // promoted from Db
assert config.name == 'app'
encoded := toml.encode(config)
assert encoded == 'host = "localhost"\nport = 5432\napp_name = "app"'
assert toml.decode[Config](encoded)! == config

Map fields support string, boolean, and integer keys up to 64 bits. TOML keys are strings; integer keys are parsed as decimal numbers with the destination type's range, including full-width i64 and u64 keys. Invalid or out-of-range keys are skipped, as are out-of-range narrow integer values. Boolean keys must be true or false. Other map key types are rejected at compile time. Nested maps retain their own key types.

Value retrieval

The toml module supports easy retrieval of values from TOML documents by using a small and simple query syntax as argument to the value() function.

Keys in map entries are denoted by . and array entries uses [<int>]. Quoted keys are also supported by using the delimiters " or '.

doc.value('table.array[0].a."b.c"')

To query for a value that might not be in the document you can use the .default_to(...) function to provide a default value.

For cases where a default value might not be appropriate or to check if a value exists you can use doc.value_opt('query')! instead.

import toml

const toml_text = '
val = true

[table]
array = [
    { a = "A" },
    { b = "B" }
]
'

doc := toml.parse_text(toml_text) or { panic(err) }

assert doc.value('val').bool() == true
assert doc.value('table.array[0].a').string() == 'A'

// Provides a default value
assert doc.value('non.existing').default_to(false).bool() == false

// Check if value exist
// doc.value_opt('should.exist') or { ... }
// or
if value := doc.value_opt('table.array[1].b') {
    assert value.string() == 'B'
}

// You can pass parts of the TOML document around
// and still use .value()/.value_opt() to get the values
arr := doc.value('table.array')
assert arr.value('[1].b').string() == 'B'

Conversion

Any TOML value can be converted to a V equivalent type.

TOML values are represented as the toml.Any sum-type that can be converted to a V type.

Read more about values in the TOML specification.

TOML to JSON

The toml.to module supports easy serialization of any TOML to JSON.

import toml
import toml.to

const toml_text = '
val = true
[table]
array = [
    { a = "A" },
    { b = "B" }
]
'

doc := toml.parse_text(toml_text) or { panic(err) }
assert to.json(doc) == '{ "val": true, "table": { "array": [ { "a": "A" }, { "b": "B" } ] } }'

fn ast_to_any(value ast.Value) Any

ast_to_any converts from ast.Value to toml.Any value.

fn decode[T](toml_txt string) !T

decode decodes a TOML string into the target type T. If T has a custom .from_toml() method, it will be used instead of the default.

fn encode[T](typ T) string

encode encodes the type T into a TOML string. If T has a custom .to_toml() method, it will be used instead of the default.

fn parse_dotted_key(key string) ![]string

parse_dotted_key converts key string to an array of strings. parse_dotted_key preserves strings delimited by both " and '.

fn parse_file(path string) !Doc

parse_file parses the TOML file in path.

fn parse_text(text string) !Doc

parse_text parses the TOML document provided in text.

type Any = Date
	| DateTime
	| Null
	| Time
	| []Any
	| bool
	| f32
	| f64
	| i64
	| int
	| map[string]Any
	| string
	| u64

Pretty much all the same builtin types as the json2.Any type plus DateTime,Date,Time

fn (a Any) string() string

string returns Any as a string.

fn (a Any) to_toml() string

to_toml returns Any as a TOML encoded value.

fn (a Any) int() int

int returns Any as an 32-bit integer.

fn (a Any) i64() i64

i64 returns Any as a 64-bit integer.

fn (a Any) u64() u64

u64 returns Any as a 64-bit unsigned integer.

fn (a Any) f32() f32

f32 returns Any as a 32-bit float.

fn (a Any) f64() f64

f64 returns Any as a 64-bit float.

fn (a Any) array() []Any

array returns Any as an array.

fn (a Any) as_map() map[string]Any

as_map returns Any as a map (TOML table).

fn (a Any) bool() bool

bool returns Any as a boolean.

fn (a Any) date() Date

date returns Any as a toml.Date struct.

fn (a Any) time() Time

time returns Any as a toml.Time struct.

fn (a Any) datetime() DateTime

datetime returns Any as a toml.DateTime struct.

fn (a Any) default_to(value Any) Any

default_to returns value if a Any is Null. This can be used to set default values when retrieving values. E.g.: toml_doc.value('wrong.key').default_to(123).int()

fn (a Any) value(key string) Any

value queries a value from the Any type. key supports a small query syntax scheme: Maps can be queried in "dotted" form e.g. a.b.c. quoted keys are supported as a."b.c" or a.'b.c'. Arrays can be queried with a[0].b[1].[2].

fn (a Any) value_opt(key string) !Any

value_opt queries a value from the current element's tree. Returns an error if the key is not valid or there is no value for the key.

fn (a Any) reflect[T]() T

reflect returns T with T.<field>'s value set to the value of any 1st level TOML key by the same name.

fn (a []Any) value(key string) Any

value queries a value from the array. key supports a small query syntax scheme: The array can be queried with [0].b[1].[2]. Maps can be queried in "dotted" form e.g. a.b.c. quoted keys are supported as a."b.c" or a.'b.c'.

fn (a []Any) as_strings() []string

as_strings returns the contents of the array as []string

fn (a []Any) to_toml() string

to_toml returns the contents of the array as a TOML encoded string.

fn (m map[string]Any) value(key string) Any

value queries a value from the map. key supports a small query syntax scheme: Maps can be queried in "dotted" form e.g. a.b.c. quoted keys are supported as a."b.c" or a.'b.c'. Arrays can be queried with a[0].b[1].[2].

fn (m map[string]Any) as_strings() map[string]string

as_strings returns the contents of the map as map[string]string

fn (m map[string]Any) to_toml() string

to_toml returns the contents of the map as a TOML encoded string.

fn (m map[string]Any) to_inline_toml() string

to_inline_toml returns the contents of the map as an inline table encoded TOML string.

struct Config {
pub:
	text           string // TOML text
	file_path      string // '/path/to/file.toml'
	parse_comments bool
}

Config is used to configure the toml parser. Only one of the fields text or file_path, is allowed to be set at time of configuration.

struct Date {
pub:
	date string
}

Date is the representation of an RFC 3339 date-only string.

fn (d Date) str() string

str returns the RFC 3339 date-only string representation.

struct DateTime {
pub:
	datetime string
}

DateTime is the representation of an RFC 3339 datetime string.

fn (dt DateTime) str() string

str returns the RFC 3339 string representation of the datetime.

struct Doc {
pub:
	ast &ast.Root = unsafe { nil }
}

Doc is a representation of a TOML document. A document can be constructed from a string buffer or from a file path

fn (d Doc) decode[T]() !T

decode decodes a TOML string into the target struct type T.

fn (d Doc) to_any() Any

to_any converts the Doc to toml.Any type.

fn (d Doc) reflect[T]() T

reflect returns T with T.<field>'s value set to the value of any 1st level TOML key by the same name.

fn (d Doc) value(key string) Any

value queries a value from the TOML document. key supports a small query syntax scheme: Maps can be queried in "dotted" form e.g. a.b.c. quoted keys are supported as a."b.c" or a.'b.c'. Arrays can be queried with a[0].b[1].[2].

fn (d Doc) value_opt(key string) !Any

value_opt queries a value from the TOML document. Returns an error if the key is not valid or there is no value for the key.

struct Null {
}

Null is used in sumtype checks as a "default" value when nothing else is possible.

struct Time {
pub:
	time string
}

Time is the representation of an RFC 3339 time-only string.

fn (t Time) str() string

str returns the RFC 3339 time-only string representation.