Json

4 types1 value21 functions

JSON (RFC 8259) values: parsing, encoding, and decoding into Bert values. Objects keep their members in order, duplicate keys included, and a number keeps the lexeme it was written with, so nothing is rounded. Decoders are plain functions from a @Json to a Result, combined with ?.

point = (json) -> {
  x = Json.field(json, "x", Json.int)?
  y = Json.field(json, "y", Json.int)?
  Ok({ x: x, y: y })
}

Json.decode("{\"x\": 1, \"y\": 2}", point)

Returns

Ok({ x: 1, y: 2 })

At a glance

@Json
A JSON value.
DecodeError
Where decoding failed, outermost key or index first, what the decoder wanted there, and a short description of the value it found.
Option
Shorthand for [Some(a) | None], a value that may be absent.
Result
Shorthand for [Ok(a) | Err(e)], the variant this module's fallible functions return.
null
The JSON null.
view
The value's outermost layer, for a match.
fromBool
The JSON true or false.
fromInt
The JSON number with the integer's decimal digits.
fromFloat
The shortest number that reads back as exactly this float.
fromString
The JSON string holding s.
array
An array of these values, in this order.
object
An object with these members, in this order.
parse
One JSON value, with nothing but whitespace around it.
parseBytes
parse for bytes, which must be UTF-8 first.
encode
Compact JSON text: no whitespace between tokens.
encodePretty
JSON text with each array element and object member on a line of its own, indented by indent spaces per level of nesting, and a space after each :.
int
A number written as a decimal integer in the Int range.
float
Any number, as the float nearest its lexeme.
string
Decodes a JSON string.
bool
Decodes true or false.
list
Each element through decoder.
field
The value of the first member named key, through decoder.
optionalField
field for a member that may be left out: a missing member, or one whose value is null, is None.
nullable
None for null, and anything else through decoder.
at
The value at the end of a path of keys, through decoder: at(j, ["a", "b"], d) is field(j, "a", \(x) -> field(x, "b", d)).
decode
Parse text, then decode the value.

Types

@Json

type @Json

A JSON value. A number holds its lexeme, valid by the JSON grammar.

DecodeError

DecodeError = { path: List(String), expected: String, found: String }

Where decoding failed, outermost key or index first, what the decoder wanted there, and a short description of the value it found.

Option

Option(a) = [Some(a) | None]

Shorthand for [Some(a) | None], a value that may be absent.

Result

Result(a, e) = [Ok(a) | Err(e)]

Shorthand for [Ok(a) | Err(e)], the variant this module's fallible functions return.

Values

null

@Jsonpure

The JSON null.

Functions

view

(@Json) -> [JNull | JBool(Bool) | JNumber(String) | JString(String) | JArray(List(@Json)) | JObject(List({ key: String, value: @Json }))]pure

The value's outermost layer, for a match. Nested values stay @Json.

fromBool

(Bool) -> @Jsonpure

The JSON true or false.

fromInt

(Int) -> @Jsonpure

The JSON number with the integer's decimal digits.

fromFloat

(Float) -> @Jsonpure

The shortest number that reads back as exactly this float. JSON has no NaN or infinities, so those are null, as JavaScript writes them.

fromString

(String) -> @Jsonpure

The JSON string holding s. It is not parsed: parse reads JSON text.

array

(List(@Json)) -> @Jsonpure

An array of these values, in this order.

object

(List({ key: String, value: @Json })) -> @Jsonpure

An object with these members, in this order. A repeated key is kept.

parse

(String) -> Result(@Json, [JsonSyntax({ pos: Int, expected: String }) | e])pure

One JSON value, with nothing but whitespace around it. JsonSyntax gives the byte offset of the first problem and a short description of what was expected there.

parseBytes

(Bytes.@Bytes) -> Result(@Json, [JsonSyntax({ pos: Int, expected: String }) | InvalidUtf8({ pos: Int }) | e])pure

parse for bytes, which must be UTF-8 first.

encode

(@Json) -> Stringpure

Compact JSON text: no whitespace between tokens.

encodePretty

(@Json, Int) -> Stringpure

JSON text with each array element and object member on a line of its own, indented by indent spaces per level of nesting, and a space after each :. An empty array or object stays [] or {}. An indent of zero or less is encode, and one above 10 is 10, as JSON.stringify has it.

int

(@Json) -> Result(Int, [JsonDecode(DecodeError) | e])pure

A number written as a decimal integer in the Int range. A fraction or an exponent is an error even when the value is whole, as 1.0 and 1e2 are.

float

(@Json) -> Result(Float, [JsonDecode(DecodeError) | e])pure

Any number, as the float nearest its lexeme. One past the largest float is an infinity, as JavaScript reads it.

string

(@Json) -> Result(String, [JsonDecode(DecodeError) | e])pure

Decodes a JSON string.

bool

(@Json) -> Result(Bool, [JsonDecode(DecodeError) | e])pure

Decodes true or false.

list

(@Json, (@Json) -> Result(a, [JsonDecode(DecodeError) | e])) -> Result(List(a), [JsonDecode(DecodeError) | e])pure if arg2 is

Each element through decoder. A failure's path starts with the element's index.

field

(@Json, String, (@Json) -> Result(a, [JsonDecode(DecodeError) | e])) -> Result(a, [JsonDecode(DecodeError) | e])pure if arg3 is

The value of the first member named key, through decoder. A value that is not an object, or has no such member, is an error at the object's path; a failure inside the member's value has key in front of its path.

optionalField

(@Json, String, (@Json) -> Result(a, [JsonDecode(DecodeError) | e])) -> Result(Option(a), [JsonDecode(DecodeError) | e])pure if arg3 is

field for a member that may be left out: a missing member, or one whose value is null, is None. A value that is not an object is still an error.

nullable

(@Json, (@Json) -> Result(a, [JsonDecode(DecodeError) | e])) -> Result(Option(a), [JsonDecode(DecodeError) | e])pure if arg2 is

None for null, and anything else through decoder.

at

(@Json, List(String), (@Json) -> Result(a, [JsonDecode(DecodeError) | e])) -> Result(a, [JsonDecode(DecodeError) | e])pure if arg3 is

The value at the end of a path of keys, through decoder: at(j, ["a", "b"], d) is field(j, "a", \(x) -> field(x, "b", d)).

decode

(String, (@Json) -> Result(a, [JsonDecode(DecodeError) | JsonSyntax({ pos: Int, expected: String }) | e])) -> Result(a, [JsonDecode(DecodeError) | JsonSyntax({ pos: Int, expected: String }) | e])pure if arg2 is

Parse text, then decode the value.