std.json

Reads and writes JSON by RFC 8259, strictly: JsonWriter and TreeBuilder encode and JsonReader decodes in std.codec's model, JsonValue is the dynamic tree, JsonOptions steers the text written, and JsonError is what a text that is no JSON throws. json.encode(v) writes any Encode value as text, json.decode<T>(text) reads any Decode value out of one; json.parse(text) is the tree. A struct is an object, a sequence an array, a map an object whose keys are strings — a number's digits where the key is a number —, bytes a Base64 string, a unit variant its name, a variant with a payload {"Name": payload}. NaN and the infinities have no text (RFC 8259 §6): writing one is an EncodeError. The text is read whole into the tree first, then decoded from it.

Examples

import std.io { println };
import std.codec { Codable, EncodeError, DecodeError };
import std.json;

struct Point :: [Codable] {
    x: int,
    y: int,
}

fn main(): void throws [EncodeError, json.JsonError, DecodeError] {
    let text = try json.encode(Point { x = 3, y = 4 });
    println(text);
    let back = try json.decode<Point>("{\"x\": 5, \"y\": 6}");
    println(back.x + back.y);
}

{"x":3,"y":4}
11

Types

JsonOptions struct — Steers how the text is written: pretty with newlines and indent spaces per level, sortKeys with an object's keys in order (which goes through the tree).

JsonError struct — The error a text that is no JSON throws: where (line and column), and what was wrong.

JsonValue enum — A JSON document as a value: the six forms, a number as Int where it has no fraction or exponent and fits an int, Float else.

JsonWriter class — The encoder that writes JSON text: compact, or pretty with newlines and indentation.

TreeBuilder class — An encoder that builds a JsonValue: a struct as an object, a variant as its name or an object of one member, bytes as a Base64 string, a key as its string.

JsonReader class — The decoder over a JSON tree: a struct from an object by its members' names, a sequence from an array, a map from an object (its keys as strings, or as the numbers they spell), a variant from its name or from an object of one member, bytes from a Base64 string.

Functions

pub fn encode<T :: [Encode]>(v: T, opts: JsonOptions = JsonOptions { }): string throws EncodeError

Encodes v as JSON text under opts.

Errors

Throws EncodeError for a NaN or an infinity, a map key that is null, a bool, a float or a container, or whatever v's conformance throws.

pub fn encodeTo<T :: [Encode], W :: [Writer]>(
    v: T,
    &w: W,
    opts: JsonOptions = JsonOptions { }
): void throws [EncodeError, IoError, Cancelled]

Encodes v as JSON text under opts and writes it into w.

Errors

Throws what encode throws, and the IoError or Cancelled of the write.

pub fn parse(text: StringView): JsonValue throws JsonError

Parses text into the tree it holds, strictly by RFC 8259: one value, with whitespace around it and nothing else.

Errors

Throws JsonError with the line and column where the text is no JSON, text follows the value, or the document nests deeper than 512 levels.

pub fn decode<T :: [Decode]>(text: StringView): T throws [JsonError, DecodeError]

Decodes a T out of text: parses it into the tree, then reads the value out of the tree.

Errors

Throws JsonError where the text is no JSON, and DecodeError where the tree does not hold a T.

pub fn decodeFrom<T :: [Decode], R :: [Reader]>(
    &r: R
): T throws [JsonError, DecodeError, IoError, Cancelled]

Decodes a T out of the text r holds, read to its end first.

Errors

Throws what decode throws, and the IoError or Cancelled of the read.