toml

TOML serialization and deserialization.

Types

Type	Description
`DecodeError`	Raised when `decode` is given invalid TOML, or TOML that uses a feature it doesn't support.
`EncodeError`	Raised when `encode` is given a value that can't be written as TOML as it stands.
`DecodeValue`	A value decoded from TOML.
`EncodeValue`	A value that encodes as TOML.

`DecodeValue`

@let DecodeValue = $
  | Bool
  | Int
  | Float
  | Str
  | Array[DecodeValue]
  | Dict[Str, DecodeValue]

A value decoded from TOML.

`EncodeValue`

@let EncodeValue = $
  | Bool
  | Int
  | Float
  | Str
  | Sym
  | BaseArray[EncodeValue]
  | Tuple[...EncodeValue]
  | Record[...{**EncodeValue}]
  | std.BaseStruct[{**EncodeValue}]
  | BaseDict[Str | Sym, EncodeValue]

A value that encodes as TOML.

Functions

`decode toml -> DecodeValue`

Parses a TOML string into a Do value.

TOML Value	Do Type
boolean	`Bool`
integer	`Int`
float	`Float`
string	`Str`
array	`Array`
table	`Dict`

Full documents and bare TOML values such as numbers, arrays, and inline tables are accepted.

Parameters

Name	Type	Description
`toml`	`Str`	TOML input to parse.

Errors

DecodeError if the input is invalid TOML, contains a datetime, date, or time value, or has a number too large to represent. When the input is neither a valid document nor a valid bare value, the error is from whichever reading got further.

Example

assert_eq (decode "42") 42
assert_eq (decode "[1, 2, 3]") [1, 2, 3]

let Dict(doc) = decode |
  title = "Example"
  [server]
  port = 8080

assert_eq $doc["title"] "Example"
let Dict(server) = doc["server"]
assert_eq $server["port"] 8080

Open in playground

`encode value -> Str`

Serializes a Do value to a TOML string.

Do Type	TOML Value
`Bool`	boolean
`Int`	integer
`Float`	float
`Str`	string
`Sym`	string
`Array`	array
`Tuple`	array
`Dict`	table
`Struct`	table
`Record`	table

Top-level dicts, records, and structs serialize as documents, while other values serialize as values. In a document, each table's plain keys come first. Nested tables follow as [a.b] sections, and non-empty arrays whose elements are all tables as [[a.b]] sections. Values inside arrays are written inline. The result has no trailing newline.

Parameters

Name	Type	Description
`value`	`EncodeValue`	The value to serialize.

Errors

Exception	Condition
`TypeError`	A value has no TOML form, such as `nil`, a `Bin`, or a custom object, or a key is not a `Str` or `Sym`.
`EncodeError`	The value contains itself, an `Int` is outside the signed 64-bit range, or a table has two keys with the same name.

Example

assert_eq (encode 42) "42"
assert_eq (decode $ encode [1, 2, 3]) [1, 2, 3]

let doc = encode {"enabled": true, "name": "alice"}
assert_eq (decode doc) {"enabled": true, "name": "alice"}