1
0
mirror of https://github.com/vlang/v.git synced 2023-08-10 21:13:21 +03:00
v/vlib/toml
2022-01-08 19:16:32 +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 toml: improve SKIP reporting, fix formatting 2022-01-03 13: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
any.v toml: add as_strings() method to map of Any (#12824) 2021-12-13 21:43:33 +02:00
README.md docs: adding skeleton README.md files for all vlib modules (#13034) 2022-01-05 18:06:08 +02:00
toml.v toml: add doc string to reflect methods (#12666) 2021-12-03 23:07:44 +02:00

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