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.
wv add weft/jsonwv add weft/tomlJSON into a type
Section titled “JSON into a type”#Json writes how a type is encoded and decoded; Json.decode<T> and
Json.encode use it:
import weaver.io.printimport 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,coverUrlbecomingcover_url, and a field’s ownjson(name: "…")wins over it. - A key the type does not have is ignored,
publisherhere, so that a newer producer does not break an older reader. - An optional field may be absent; with
json(omitEmpty), an empty value,None,[],"",0orfalse, 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 |
When the document does not fit
Section titled “When the document does not fit”A JsonError says where the document departs from the type, by its path
and its position in the text:
import weaver.io.printimport weft.json.{Json, JsonError}
#Jsontype 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.
Documents of any shape
Section titled “Documents of any shape”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.Fileimport 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.0Some(3)Nonetrue{"project":"weaver","count":2,"ok":true}{ "count": 2, "ok": true, "project": "weaver"}truedoc["key"]and.item(i)giveNullalong a path that does not exist, rather than stopping the program;doc.at("$.a[0].b")givesNone..string(),.int(),.items()… giveNonefor another kind of value.- A number keeps its text:
1.10or 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.parseLinesreads JSON Lines.
TOML into a type
Section titled “TOML into a type”#Toml does for TOML what #Json does for JSON, with toml(…) tags. A
type can adopt both, like Server here:
import weaver.io.printimport weft.toml.{Toml, TomlError}import weft.json.{Json}
/// A server the proxy sends requests to.#Toml#Jsontype Server = { host: String port: Int tls: Bool `toml(default)`}
/// The proxy's settings.#Tomltype 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 trueb.example:8080, tls false{"host":"b.example","port":8080,"tls":false}name = "edge"
[[servers]]host = "a.example"port = 443tls = true
[[servers]]host = "b.example"port = 8080tls = false
servers[0].host: expected a string, found an integerA 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 of any shape
Section titled “TOML of any shape”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.printimport 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()) } }}appweft/json: 1.0weft/toml: localline 2, column 1: key `a` defined twiceline 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.
Going further
Section titled “Going further”- A type whose encoding no option describes writes the
Jsoncontract by hand:toJsonwrites to aJsonWriter,fromJsonreads from aJsonReader, the same stream#Jsonuses. - A program’s settings, read from TOML or JSON files, the environment and the command line, are a configuration.
- The registry documents
weft/jsonandweft/tomlin full.