v/vlib/toml
Delyan Angelov 85ec0248e9
ci: rename types_test.v to toml_types_test.v
This is a workaround for a concurency bug, occuring sporadically when
test file names in different folders are duplicate.

The duplicate in this case was with vlib/v/ast/types_test.v
2022-01-22 20:25:06 +02:00
..
ast toml: expand short date time milliseconds in decoder (#12564) 2021-11-24 14:49:23 +02:00
checker toml: ignore CRLF just like LF in line comments, support VTEST_HIDE_OK=1 in tests. 2022-01-03 12:54:16 +02:00
decoder toml: fix bug in unicode decoding (#12643) 2021-12-02 11:19:12 +02:00
input toml: easier scanner configuration (#12016) 2021-09-29 14:53:06 +03:00
parser ci: fix failing `tests-sanitize-address-clang` step for vlib/toml/tests/spaced_keys_test.v 2021-12-11 19:03:47 +02:00
scanner toml: fix comment ends with crlf (#13097) 2022-01-08 19:16:32 +02:00
tests ci: rename types_test.v to toml_types_test.v 2022-01-22 20:25:06 +02:00
to toml: add conversion of ast inf and nan to Any (#12567) 2021-11-25 12:33:54 +02:00
token vlib: add toml module + tests (#11964) 2021-09-24 21:13:52 +03:00
util toml: small refactor, move all json functionality to submodule (#12502) 2021-11-18 13:27:59 +02:00
README.md docs: adding skeleton README.md files for all vlib modules (#13034) 2022-01-05 18:06:08 +02:00
any.v toml: add `encode<T>` and `decode<T>` (#13244) 2022-01-21 21:21:31 +02:00
toml.v toml: fix a doc string (#13246) 2022-01-22 10:27:16 +02:00

README.md

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:

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