json, decoders
Reading JSON into types of your own, and writing them back
A Decoder(a) reads an a out of a Json value, and says where a document doesn’t fit. The decoders are in
nanyx.json/json with the rest of json, and the encoders, which go the other way, in encode.
Some decoders read one kind of value each: string, int (a whole number), float and bool, and value reads any
value as it is. The rest build larger decoders from smaller: list, dict, optional, field, oneOf, convert,
andThen, and record, a builder that reads a record a member at a time, each with try, and gives back what it
read with return. json.decode parses text and runs a decoder on it, and json.decodeValue runs one on a value
already parsed.
When a value doesn’t fit, the DecodeError says where, by the path from the document’s root to it, which
json.pathText writes as users[2].age, and what was wrong there; json.describe writes both. A decoder takes time
in proportion to the size of what it reads, and reads a long list in constant stack.
::dependency nanyx.json 0.1.0
import (
nanyx.json/encode as encode
nanyx.json/json as json
)
type User = (name: string, age: int)
def user: json.Decoder(User) = json.record {
def name = try json.field("name", json.string)
def age = try json.field("age", json.int)
return User(name = name, age = age)
}
def userEncoder: json.Encoder(User) = encode.object(
[
encode.field("name", { u -> u.name }, encode.string)
encode.field("age", { u -> u.age }, encode.int)
]
)
match json.decode('[{"name": "Ada", "age": 36}, {"name": "Bob", "age": 2.5}]', json.list(user))
| #some(users) -> println(json.encode(users, encode.list(userEncoder)))
| #error(e) -> println(json.describe(e))
-- [1].age: Expected a whole number, found 2.5
A tagged union is read by the decoder a field of it chooses: a try reads by any decoder, including one picked by what
an earlier try read.
::dependency nanyx.json 0.1.0
import nanyx.json/json as json
type Shape = #circle(float) | #square(float)
def shape: json.Decoder(Shape) = json.record {
def kind = try json.field("kind", json.string)
def size: json.Decoder(Shape) =
match kind
| "circle" -> json.convert(json.field("radius", json.float), { r -> #circle(r) })
| "square" -> json.convert(json.field("side", json.float), { s -> #square(s) })
| other -> json.fail("Expected the kind 'circle' or 'square', found '{other}'")
def s = try size
return s
}
match json.decode('{"kind": "square", "side": 2}', shape)
| #some(#square(side)) -> println("A square of side {side}")
| #some(_) -> println("Another shape")
| #error(e) -> println(json.describe(e))
-- A square of side 2.0
Reference
PathStep
type PathStep = #field(string) | #index(int)
One step on the way from a document’s root to a value in it: the member of an object with this name, or the element of an array at this index, counting from 0.
DecodeError
type DecodeError = (path: list(PathStep), message: string)
Why a decoder read no value: the path from the root of the document to the value that didn’t fit, each step in turn (empty for the root itself), and what was wrong with it.
Decoder
type Decoder(a) = private (run: (Json -> #some(a) | #failed(list(PathStep), string)), absent: #some(a) | #none)
What reads an a from a Json value, or says why it can’t. The decoders here make one, and
decode and decodeValue run one. A missing member is the decoder’s to read too: only
optional reads one, as #none.
string
def string: Decoder(string)
Reads a string.
float
def float: Decoder(float)
Reads a number, as JSON holds one: a float.
int
def int: Decoder(int)
Reads a number that is whole, and in the range of int, as an int: 2.5 is an error.
bool
def bool: Decoder(bool)
Reads true or false.
value
def value: Decoder(Json)
Reads any value, as it is: for a part of a document that is read later, or not at all.
list
def list: Decoder(a) -> Decoder(list(a))
Reads an array, each element by decoder: json.list(json.int) reads [1, 2, 3].
dict
def dict: Decoder(a) -> Decoder(map(string, a))
Reads an object as a map, each member’s value by decoder, in the order the object has them:
for an object whose members aren’t known ahead, as {"en": "Hello", "fr": "Bonjour"}.
optional
def optional: Decoder(a) -> Decoder(#some(a) | #none)
Reads null as #none, and anything else by decoder, as #some. A member that field
finds missing reads as #none too, so json.field("nickname", json.optional(json.string)) reads
an object with no nickname.
field
def field: string, Decoder(a) -> Decoder(a)
Reads the member name of an object by decoder. A missing member is an error, but for a
decoder that reads one as a value, as optional does.
succeed
def succeed: a -> Decoder(a)
The decoder that reads x from any value, whatever it is.
fail
def fail: string -> Decoder(a)
The decoder that reads no value, but fails with message: for a value that is the right kind
but not one of those allowed, as an unknown tag.
convert
def convert: Decoder(a), (a -> b) -> Decoder(b)
Reads a value by decoder, then gives f of it. A member decoder reads as missing is f of
what it reads it as.
andThen
def andThen: Decoder(a), (a -> Decoder(b)) -> Decoder(b)
Reads a value by decoder, then reads the same value again by the decoder next makes of
what the first read: for a value whose shape depends on part of it, as a tagged union’s does on
its tag.
oneOf
def oneOf: list(Decoder(a)) -> Decoder(a)
Reads a value by the first of decoders that reads it. When none does, the error is the one
that got furthest into the value, the first of those that tie.
DecodeRecord
context DecodeRecord = (
try: [c] Decoder(a), ([c] a -> Decoder(b)) -> Decoder(b)
return: a -> Decoder(a)
)
The keywords of a record block: try reads a value by a decoder, and return gives the
value the block reads.
try: Reads the value by the decoder, and goes on with what it read.return: The value the block reads.
record
def record: [c] ([DecodeRecord, c] () -> Decoder(b)) -> Decoder(b)
A decoder written as a block that reads a value a part at a time: each try reads the value by
a decoder, usually a field, and return says what the block reads from what they read.
def user: json.Decoder(User) = json.record {
def name = try json.field("name", json.string)
def age = try json.field("age", json.int)
return User(name = name, age = age)
}
The first try that fails ends the block with its error. A try can read by any decoder,
one chosen by what an earlier try read among them, as for a tagged union.
decodeValue
def decodeValue: Json, Decoder(a) -> #some(a) | #error(DecodeError)
What decoder reads from value, or why it reads nothing, with the path to what didn’t fit.
decode
def decode: string, Decoder(a) -> #some(a) | #error(DecodeError)
What decoder reads from the JSON text, or why it reads nothing: text that isn’t JSON is an
error at the root, whose message says where in the text, by line and column.
pathText
def pathText: list(PathStep) -> string
steps as a path is written: a member by its name, after a . but at the start, and an
element by its index in brackets, as users[2].age. The root, with no steps, is "".
describe
def describe: DecodeError -> string
e as a message writes it: its path, then what was wrong there, as
users[2].age: Expected a whole number, found 2.5, or only what was wrong for the root.
Encoder
type Encoder(a) = a -> Json
What writes an a as a Json value: any function that does. The encoders that build one are
in the module nanyx.json/encode.
encode
def encode: a, Encoder(a) -> string
value as JSON text, written by encoder and printed compactly as print prints.