Skip to content

toml #

TOML module

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:

doc := toml.parse(<file path or string>) 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(toml_text) or { panic(err) }
    title := doc.value('title').string()
    println('title: "$title"')
    ip := doc.value('servers.alpha.ip').string()
    println('Server IP: "$ip"')
}

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.

import toml

const toml_text = '
val = true

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

doc := toml.parse(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

// You can pass parts of the TOML document around
// and still use .value() 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.

TOML value V conversion (via toml.Any)
val = "Basic string" .string()
val = 'Literal string' .string()
val = true .bool()
val = 1979-05-27T07:32:00Z .datetime() (toml.DateTime)
val = 1979-05-27 .date() (toml.Date)
val = 07:32:59 .time() (toml.Time)
val = 3.14 .f32() / .f64()
val = 100 .int() / .i64() / .u64()

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(toml_text) or { panic(err) }
assert to.json(doc) == '{ "val": true, "table": { "array": [ { "a": "A" }, { "b": "B" } ] } }'

fn ast_to_any #

fn ast_to_any(value ast.Value) Any

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

fn parse #

fn parse(toml string) ?Doc

parse parses the TOML document provided in toml.
parse automatically try to determine if the type of toml is a file or text.
For explicit parsing of input types see parse_file or parse_text.

fn parse_dotted_key #

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 #

fn parse_file(path string) ?Doc

parse_file parses the TOML file in path.

fn parse_text #

fn parse_text(text string) ?Doc

parse_text parses the TOML document provided in text.

fn ([]Any) value #

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 ([]Any) as_strings #

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

type Any #

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 (Any) string #

fn (a Any) string() string

string returns Any as a string.

fn (Any) int #

fn (a Any) int() int

int returns Any as an 32-bit integer.

fn (Any) i64 #

fn (a Any) i64() i64

i64 returns Any as a 64-bit integer.

fn (Any) u64 #

fn (a Any) u64() u64

u64 returns Any as a 64-bit unsigned integer.

fn (Any) f32 #

fn (a Any) f32() f32

f32 returns Any as a 32-bit float.

fn (Any) f64 #

fn (a Any) f64() f64

f64 returns Any as a 64-bit float.

fn (Any) array #

fn (a Any) array() []Any

array returns Any as an array.

fn (Any) as_map #

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

as_map returns Any as a map (TOML table).

fn (Any) bool #

fn (a Any) bool() bool

bool returns Any as a boolean.

fn (Any) date #

fn (a Any) date() Date

date returns Any as a toml.Date struct.

fn (Any) time #

fn (a Any) time() Time

time returns Any as a toml.Time struct.

fn (Any) datetime #

fn (a Any) datetime() DateTime

datetime returns Any as a toml.DateTime struct.

fn (Any) default_to #

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 (Any) value #

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 (Any) reflect #

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 (map[string]Any) value #

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].

struct Config #

struct Config {
pub:
	text           string
	file_path      string
	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 #

struct Date {
	date string
}

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

fn (Date) str #

fn (d Date) str() string

struct DateTime #

struct DateTime {
	datetime string
}

DateTime is the representation of an RFC 3339 datetime string.

fn (DateTime) str #

fn (dt DateTime) str() string

struct Doc #

struct Doc {
pub:
	ast &ast.Root
}

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

fn (Doc) to_any #

fn (d Doc) to_any() Any

to_any converts the Doc to toml.Any type.

fn (Doc) reflect #

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 (Doc) value #

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].

struct Null #

struct Null {
}

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

struct Time #

struct Time {
	time string
}

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

fn (Time) str #

fn (t Time) str() string