Reference

std/json/lib

std/json/src/lib.trb

JSON as a format, written in TorbScript: an Encoder that writes the text, a parser into an EncodedValue that the shared ValueDecoder of std/encoding reads a typed value out of, and JsonValue for a document whose shape is not known ahead of time.

const json = Json()
const text = json.encode user
const back = json.decode<User>(text)?

Json is a value with the options of the format - how field names are spelled, and whether a field nobody read is an error - so a convention of the format is never a property of a type. Json is also a Format<JsonError>, which is what makes it work on a stream: Json.items<User>() is a Stage that turns byte chunks into Users one at a time.

type Json

type Json

JSON, with its options. The default writes every field under the name the type declares and ignores a field of the input that no type asked for.

Examples

type Point {
  x: Int
  y: Int
}

const json = Json()
const text = json.encode Point(1, 2)
print text
print json.decode<Point>(text)

Related

field naming

naming: Naming = Naming.Unchanged

How the field names are written and read: Naming.SnakeCase writes logLabel as log_label.

field strict

strict: Bool = false

Whether a field of the input that no type asked for is an error, instead of being ignored.

fn encode

fn encode<Value: Encode>(value: Value): String

value as JSON text.

fn decode

fn decode<Value: Decode>(text: String): Result<Value, JsonError>

Parses text and reads it as a Value. Fails on malformed JSON as well as on JSON that does not fit Value.

Errors

A JsonError that is a syntax error for text that is not JSON, and one that holds the DecodeError - with the field chain it happened in - for JSON of the wrong shape.

fn parse

fn parse(text: String): Result<JsonValue, JsonError>

Parses text into a JsonValue, without knowing its shape.

Errors

A syntax error, with the line it was found on.

fn value

fn value<Value: Encode>(value: Value): JsonValue

Any Encode value as the JsonValue this format would write it as: to diff two versions of it structurally.

type JsonValue

type JsonValue

A JSON document without a fixed shape: config previews, diffing, passing on fields nobody has a type for yet. Encoder and Decoder are driven by a type, so "whatever is there" is this library type and nothing in the language.

case Null

case Null

Not documented.

case Bool

case Bool(value: Bool)

Not documented.

case Number

case Number(value: Float64)

JSON does not distinguish integers from floating point, so every number is a Float64 here.

case String

case String(value: String)

Not documented.

case Array

case Array(items: List<JsonValue>)

Not documented.

case Object

case Object(entries: Map<String, JsonValue>)

Not documented.

extend JsonValue with Encode

extend JsonValue with Encode

A JsonValue writes itself into any Encoder, not only Json's own. A whole number is written as one.

fn encode

fn encode<Target: Encoder>(var target: Target)

type JsonError

type JsonError with Show, Error

What went wrong turning text into a value: malformed JSON, or JSON that parsed fine but does not fit the requested type.

fn syntax

static fn syntax(line: Int, message: String): JsonError

The text was not well-formed JSON.

fn decodeFailed

static fn decodeFailed(cause: DecodeError): JsonError

The text was well-formed JSON, but Decode rejected it.

fn invalidText

static fn invalidText(cause: Utf8Error): JsonError

JSON is text, and the bytes that arrived are not UTF-8 - so there was no text to parse in the first place.

fn isSyntaxError

fn isSyntaxError(): Bool

true for malformed JSON text, as opposed to well-formed JSON that did not fit the target type.

fn show

fn show(): String

Not documented.

fn cause

fn cause(): Error?

The DecodeError a rejected document failed on, so a report can unwind the chain down to the field.

extend JsonError with From<Utf8Error>

extend JsonError with From<Utf8Error>

What checked() needs to lift a broken byte sequence into the failure of a JSON stream.

fn from

static fn from(value: Utf8Error): JsonError

extend Json with Format<JsonError>

extend Json with Format<JsonError>

Everything a stream needs: a framer that finds where one element ends, and the ordinary Decode for the element itself. The static members use the default options, Json().

fn encodeAll

static fn encodeAll<Value: Encode>(value: Value): Bytes

fn decodeAll

static fn decodeAll<Value: Decode>(bytes: Bytes): Result<Value, JsonError>

fn items

static fn items<Item: Decode>(): Stage<Bytes, Result<Item, JsonError>>

Byte chunks to items. The first byte that is not whitespace decides what the stream is: a [ opens one top-level array and its elements are the items; anything else makes it a sequence of values written one after another, which covers newline-separated JSON (NDJSON) without a rule of its own.

Memory is one element - what has arrived of the one being read, and nothing else.

fn encoded

static fn encoded<Item: Encode>(): Stage<Item, Bytes>

Items to bytes, one value per line (NDJSON). Not an array: a stream has no end at which a closing bracket could be written, and a reader would have to hold the whole thing to find one.