Module toml | Standard Library documentation

Overview

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}"')
}

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.

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

Aliases

This section is empty.

Constants

pub const null = Any(Null{})

Sum types

pub type Any = Date

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 Date struct.

fn (a Any) time() Time

time returns Any as a Time struct.

fn (a Any) datetime() DateTime

datetime returns Any as a 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) value_(value Any, key []string) Any

value_ returns the Any value found at key.

fn (a Any) reflect() T

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

Functions

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.

fn encode[T](typ T) string

encode encodes the type T into a TOML string.

Currently encode expects the method to_toml exists on T.

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

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.

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.

Structs

pub struct Null {
}

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

pub struct DateTime {
	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.

pub struct Date {
	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.

pub struct Time {
	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.

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

pub 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) to_any() Any

to_any converts the Doc to toml.Any type.

fn (d Doc) reflect() 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.

fn (d Doc) value_(value ast.Value, key []string) Any

value_ returns the value found at key in the map values as Any type.

Interfaces

This section is empty.

Enums

This section is empty.

Module toml stdlib

Dependencies defined in v.mod

Imports

Standard Library

Imported by

Standard Library

Local Modules

Overview

Description

Usage

Example

Value retrieval

Conversion

TOML to JSON

Aliases

Constants

#constant null

Sum types

#type Any

#fn (Any) string

#fn (Any) to_toml

#fn (Any) int

#fn (Any) i64

#fn (Any) u64

#fn (Any) f32

#fn (Any) f64

#fn (Any) array

#fn (Any) as_map

#fn (Any) bool

#fn (Any) date

#fn (Any) time

#fn (Any) datetime

#fn (Any) default_to

#fn (Any) value

#fn (Any) value_opt

#fn (Any) value_

#fn (Any) reflect[T]

Functions

#fn ast_to_any

#fn decode[T]

#fn encode[T]

#fn parse

#fn parse_dotted_key

#fn parse_file

#fn parse_text

#fn (map[string]Any) value

#fn (map[string]Any) as_strings

#fn (map[string]Any) to_toml

#fn (map[string]Any) to_inline_toml

#fn ([]Any) value

#fn ([]Any) as_strings

#fn ([]Any) to_toml

Structs

#struct Null

#struct DateTime

#fn (DateTime) str

#struct Date

#fn (Date) str

#struct Time

#fn (Time) str

#struct Config

#struct Doc

#fn (Doc) to_any

#fn (Doc) reflect[T]

#fn (Doc) value

#fn (Doc) value_opt

#fn (Doc) value_

Interfaces

Enums

Module `toml` stdlib

Dependencies defined in `v.mod`

#constant `null`

#type `Any`

#fn `(Any) string`

#fn `(Any) to_toml`

#fn `(Any) int`

#fn `(Any) i64`

#fn `(Any) u64`

#fn `(Any) f32`

#fn `(Any) f64`

#fn `(Any) array`

#fn `(Any) as_map`

#fn `(Any) bool`

#fn `(Any) date`

#fn `(Any) time`

#fn `(Any) datetime`

#fn `(Any) default_to`

#fn `(Any) value`

#fn `(Any) value_opt`

#fn `(Any) value_`

#fn `(Any) reflect[T]`

#fn `ast_to_any`

#fn `decode[T]`

#fn `encode[T]`

#fn `parse`

#fn `parse_dotted_key`

#fn `parse_file`

#fn `parse_text`

#fn `(map[string]Any) value`

#fn `(map[string]Any) as_strings`

#fn `(map[string]Any) to_toml`

#fn `(map[string]Any) to_inline_toml`

#fn `([]Any) value`

#fn `([]Any) as_strings`

#fn `([]Any) to_toml`

#struct `Null`

#struct `DateTime`

#fn `(DateTime) str`

#struct `Date`

#fn `(Date) str`

#struct `Time`

#fn `(Time) str`

#struct `Config`

#struct `Doc`

#fn `(Doc) to_any`

#fn `(Doc) reflect[T]`

#fn `(Doc) value`

#fn `(Doc) value_opt`

#fn `(Doc) value_`