Skip to content
Weaverv0.5.0

JSON and TOML

weft/json and weft/toml read and write their formats two ways: into the program’s own types, whose code #Json and #Toml write at compile time, without reflection; or as a document of any shape, a tree to walk and to build.

Terminal window
wv add weft/json
wv add weft/toml

#Json writes how a type is encoded and decoded; Json.decode<T> and Json.encode use it:

import weaver.io.print
import weft.json.{Json, JsonError}
/// How a book is bound.
#Json(tag: "type")
enum Format =
| Paperback(pages: Int)
| Ebook(sizeKb: Int)
| Unknown
/// A book of the catalog.
#Json(rename: .snakeCase)
type Book = {
title: String
isbn: String? `json(omitEmpty)`
publishedYear: Int `json(name: "year")`
format: Format
tags: String[] `json(omitEmpty)`
coverUrl: String? `json(omitEmpty)`
}
val catalog = """
[
{"title": "Dune", "year": 1965, "publisher": "Chilton",
"format": {"type": "Paperback", "pages": 412}},
{"title": "Neuromancer", "isbn": "0-441-56956-0", "year": 1984,
"format": {"type": "Unknown"}, "tags": ["cyberpunk"]}
]
"""
fn main() ! JsonError {
val books = Json.decode<Book[]>(catalog)!
for b in books { print("${b.title} (${b.publishedYear}), ${b.tags.len()} tag(s)") }
print(Json.encode(books[0]))
val snow = Book{
title: "Snow Crash",
isbn: None,
publishedYear: 1992,
format: Ebook(sizeKb: 2048),
tags: [],
coverUrl: "https://example.org/snow.jpg"
}
print(Json.encode(snow, indent: 2))
}
Dune (1965), 0 tag(s)
Neuromancer (1984), 1 tag(s)
{"title":"Dune","year":1965,"format":{"type":"Paperback","pages":412}}
{
"title": "Snow Crash",
"year": 1992,
"format": {
"type": "Ebook",
"sizeKb": 2048
},
"cover_url": "https://example.org/snow.jpg"
}

What the example shows:

  • A record is an object, its fields the keys. #Json(rename: .snakeCase) changes the keys of the whole type, coverUrl becoming cover_url, and a field’s own json(name: "…") wins over it.
  • A key the type does not have is ignored, publisher here, so that a newer producer does not break an older reader.
  • An optional field may be absent; with json(omitEmpty), an empty value, None, [], "", 0 or false, is not written either.
  • An enum is written by default as "Unknown" for a variant without fields, and {"Paperback": {"pages": 412}} for one with fields. #Json(tag: "type") puts the variant’s name in a key of the object, as most web APIs do.
  • The text is decoded straight from the stream of tokens, without building a tree first, and encoded straight to text.
Tag on a field Effect
json(name: "user_id") the key
json(omitEmpty) not written when empty
json(default) absent, it takes its type’s default value
json(skip) neither written nor read

A JsonError says where the document departs from the type, by its path and its position in the text:

import weaver.io.print
import weft.json.{Json, JsonError}
#Json
type Point = { x: Int, y: Int }
#Json(denyUnknown: true)
type Strict = { x: Int }
fn main() {
for text in ["{\"x\": 1, \"y\": \"2\"}", "{\"x\": 1}", "{\"x\": 1, \"y\": 2,}", "[1, 2]"] {
match Json.decode<Point>(text) {
Ok(p) => print("${p.x} ${p.y}")
Err(e) => print(e.message())
}
}
if Json.decode<Strict>("{\"x\": 1, \"z\": 0}") is Err(e) { print(e.message()) }
}
$.y: expected an integer, found a string (line 1, column 15)
$: missing key `y` (line 1, column 1)
line 1, column 17: expected a key
$: expected an object, found an array (line 1, column 1)
$.z: unknown key `z` (line 1, column 15)

#Json(denyUnknown: true) refuses the keys the type does not have, for a format the program owns.

When the shape is not known in advance, Json.parse gives a JsonValue, which is walked, built and written back:

import weaver.io.{print, IoError}
import weaver.io.File
import weaver.{Fs}
import weft.json.{Json, JsonValue, JsonError}
fn main() ! JsonError | IoError {
val doc = Json.parse(
"{\"name\": \"weaver\", \"releases\": [{\"tag\": \"v0.5.0\", \"assets\": 3}, {\"tag\": \"v0.4.0\"}]}"
)!
print(doc["releases"].item(0)["tag"].string() ?? "?")
print("${doc.at("$.releases[0].assets")?.int()}")
print("${doc.at("$.releases[1].assets")?.int()}")
print("${doc["missing"]["deeper"].isNull()}")
val summary = JsonValue.object([
("project", doc["name"]),
("count", JsonValue.number(n: doc["releases"].items()?.len() ?? 0)),
("ok", JsonValue.Bool(b: true))
])
print(summary.text())
print(summary.text(indent: 2, sortKeys: true))
val dir = Fs.createTempDir("json")!.display().copy()
Fs.writeText("${dir}/data.json", summary.text())!
using f = File.open("${dir}/data.json")!
val back = Json.read(f)!
print("${back == summary}")
Fs.removeAll(dir)!
}
v0.5.0
Some(3)
None
true
{"project":"weaver","count":2,"ok":true}
{
"count": 2,
"ok": true,
"project": "weaver"
}
true
  • doc["key"] and .item(i) give Null along a path that does not exist, rather than stopping the program; doc.at("$.a[0].b") gives None. .string(), .int(), .items()… give None for another kind of value.
  • A number keeps its text: 1.10 or an integer beyond 64 bits is written back as it was read. An object keeps the order of its keys.
  • Json.read(source) reads a file or a socket through a window, never holding the whole text; Json.parseLines reads JSON Lines.

#Toml does for TOML what #Json does for JSON, with toml(…) tags. A type can adopt both, like Server here:

import weaver.io.print
import weft.toml.{Toml, TomlError}
import weft.json.{Json}
/// A server the proxy sends requests to.
#Toml
#Json
type Server = {
host: String
port: Int
tls: Bool `toml(default)`
}
/// The proxy's settings.
#Toml
type Proxy = {
name: String
servers: Server[]
owner: String?
}
val text = """
name = "edge"
[[servers]]
host = "a.example"
port = 443
tls = true
[[servers]]
host = "b.example"
port = 8080
"""
fn main() ! TomlError {
val proxy = Toml.decode<Proxy>(text)!
for s in proxy.servers { print("${s.host}:${s.port}, tls ${s.tls}") }
print(Json.encode(proxy.servers[1]))
print(Toml.encode(proxy))
if Toml.decode<Proxy>("name = \"x\"\nservers = [{ host = 1 }]") is Err(e) { print(e.message()) }
}
a.example:443, tls true
b.example:8080, tls false
{"host":"b.example","port":8080,"tls":false}
name = "edge"
[[servers]]
host = "a.example"
port = 443
tls = true
[[servers]]
host = "b.example"
port = 8080
tls = false
servers[0].host: expected a string, found an integer

A record is a table, an array of records an array of tables, [[servers]]. Toml.encode writes the plain values of a table first, then its tables as sections.

Toml.parse gives a TomlValue, whose dotted paths read a value deep in the document. The parser follows TOML 1.0.0 strictly: what the specification forbids is an error at its line, never a guess.

import weaver.io.print
import weft.toml.{Toml, TomlError}
fn main() ! TomlError {
val doc = Toml.parse("""
[package]
name = "app"
version = "1.4.0"
[dependencies]
"weft/json" = "1.0"
"weft/toml" = { path = "../toml" }
""")!
print(doc.at("package.name")?.str() ?? "?")
for (name, spec) in doc.get("dependencies")?.entries() ?? [:] {
print("${name}: ${spec.str() ?? "local"}")
}
for bad in ["a = 1\na = 2", "x = 0123"] {
if Toml.parse(bad) is Err(e) { print(e.message()) }
}
}
app
weft/json: 1.0
weft/toml: local
line 2, column 1: key `a` defined twice
line 1, column 5: invalid value `0123`

Dates are weaver.time’s types: an offset date-time is a Timestamp with its offset, written back as it was read.

  • A type whose encoding no option describes writes the Json contract by hand: toJson writes to a JsonWriter, fromJson reads from a JsonReader, the same stream #Json uses.
  • A program’s settings, read from TOML or JSON files, the environment and the command line, are a configuration.
  • The registry documents weft/json and weft/toml in full.