# TOML module `toml` is a fully fledged [TOML v1.0.0](https://toml.io/en/v1.0.0) compatible parser written in pure V. The module is tested against the [official compliance tests](https://github.com/toml-lang/compliance). ## Usage Parsing files or `string`s containing TOML is easy. Simply import the `toml` module and do: ```v ignore doc := toml.parse() or { panic(err) } ``` ## Example Here we parse the official [TOML example](https://github.com/toml-lang/toml/blob/3b11f6921da7b6f5db37af039aa021fee450c091/README.md#Example) and print out some values. ```v 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 `[]`. 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. ```v 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](https://toml.io/en/v1.0.0#spec). ## TOML to JSON The `toml.to` module supports easy serialization of any TOML to JSON. ```v 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" } ] } }' ```