std/json

Types

Metadata

@schema
pub type Metadata = {
    // private fields omitted
}

Field metadata read by encode and decode; attach it in a field's { ... } block, e.g. pub id Int { json.name("user_id") }.

Value

pub type Value =
    | Null
    | Boolean(Bool)
    | Integer(Int)
    | Unsigned(u64)
    | Wide(Bool, u128)
    | Number(Float)
    | Text(String)
    | List(Array[Value])
    | Object(map.Map[String, Value])

A JSON document. Integers and other numbers are kept apart so a decode into an integer type can refuse 1.5. Unsigned holds an integral literal above i64::MAX, which Integer cannot represent. Wide holds an integral literal outside both i64 and u64 (negative flag and magnitude).

Error

pub type Error = {
    pub text String
}

Why an encode or decode failed.

Error.message

pub fn Error.message(self) -> String

Fields

pub type Fields = {
    // private fields omitted
}

Builder the derived toJson of a record uses: fields in declaration order, omitNone fields skipped when None.

Fields.new

pub fn Fields.new() -> Fields

Fields.put

pub fn Fields.put(mut self, key: String, value: Value)

Fields.finish

pub fn Fields.finish(move self) -> Value

Record

pub type Record = {
    pub owner String
    // private fields omitted
}

The object a derived fromJson of a record reads; fields are taken out by their JSON key.

Record.expect

pub fn Record.expect(value: Value, typeName: String) -> Record!

Record.field

pub fn Record.field[T: Decode](mut self, key: String) -> T!

Record.optional

pub fn Record.optional[T: Decode](mut self, key: String) -> Option[T]!

Tagged

pub type Tagged = {
    pub owner String
    pub name String
    // private fields omitted
}

The variant a derived fromJson of an ADT reads: the name and its payload values in order.

Tagged.expect

pub fn Tagged.expect(value: Value, typeName: String) -> Tagged!

Tagged.arity

pub fn Tagged.arity(self, count: Int) -> Void!

Checks the payload count of the variant named in the JSON.

Tagged.next

pub fn Tagged.next[T: Decode](mut self) -> T!

Takes the next payload value, in order.

Tagged.unknown

pub fn Tagged.unknown[T](self) -> T!

Interfaces

Encode

@derivable
pub interface Encode {
    fn toJson(self) -> Value
}

Types that encode to JSON. Records and ADTs get a structural implementation from the compiler unless they define one.

Decode

@derivable
pub interface Decode {
    fn fromJson(value: Value) -> Self!
}

Types that decode from JSON; the requirement has no receiver, so it is dispatched on the type argument.

DecodeKey

pub interface DecodeKey {
    fn fromKeyText(text: String) -> Self!
}

Types a Map key can round-trip through JSON as: reconstructs Self from the object field name that Map.toJson rendered it into.

Methods of i64

i64.toJson

pub fn i64.toJson(self) -> Value

i64.fromJson

pub fn i64.fromJson(value: Value) -> Int!

i64.fromKeyText

pub fn i64.fromKeyText(s: String) -> Int!

Methods of i32

i32.toJson

pub fn i32.toJson(self) -> Value

i32.fromJson

pub fn i32.fromJson(value: Value) -> i32!

i32.fromKeyText

pub fn i32.fromKeyText(s: String) -> i32!

Methods of u8

u8.toJson

pub fn u8.toJson(self) -> Value

u8.fromJson

pub fn u8.fromJson(value: Value) -> u8!

u8.fromKeyText

pub fn u8.fromKeyText(s: String) -> u8!

Methods of u32

u32.toJson

pub fn u32.toJson(self) -> Value

u32.fromJson

pub fn u32.fromJson(value: Value) -> u32!

u32.fromKeyText

pub fn u32.fromKeyText(s: String) -> u32!

Methods of u64

u64.toJson

pub fn u64.toJson(self) -> Value

Integer when the value fits i64, else Unsigned.

u64.fromJson

pub fn u64.fromJson(value: Value) -> u64!

u64.fromKeyText

pub fn u64.fromKeyText(s: String) -> u64!

Methods of usize

usize.toJson

pub fn usize.toJson(self) -> Value

Integer when the value fits i64, else Unsigned.

usize.fromJson

pub fn usize.fromJson(value: Value) -> usize!

usize.fromKeyText

pub fn usize.fromKeyText(s: String) -> usize!

Methods of i128

i128.toJson

pub fn i128.toJson(self) -> Value

Integer when the value fits i64, Unsigned when it fits u64, else Wide.

i128.fromJson

pub fn i128.fromJson(value: Value) -> i128!

i128.fromKeyText

pub fn i128.fromKeyText(s: String) -> i128!

Methods of u128

u128.toJson

pub fn u128.toJson(self) -> Value

Integer when the value fits i64, Unsigned when it fits u64, else Wide.

u128.fromJson

pub fn u128.fromJson(value: Value) -> u128!

u128.fromKeyText

pub fn u128.fromKeyText(s: String) -> u128!

Methods of f64

f64.toJson

pub fn f64.toJson(self) -> Value

f64.fromJson

pub fn f64.fromJson(value: Value) -> Float!

f64.fromKeyText

pub fn f64.fromKeyText(s: String) -> Float!

Methods of Bool

Bool.toJson

pub fn Bool.toJson(self) -> Value

Bool.fromJson

pub fn Bool.fromJson(value: Value) -> Bool!

Bool.fromKeyText

pub fn Bool.fromKeyText(s: String) -> Bool!

Methods of String

String.toJson

pub fn String.toJson(self) -> Value

String.fromJson

pub fn String.fromJson(value: Value) -> String!

String.fromKeyText

pub fn String.fromKeyText(s: String) -> String!

Methods of Char

Char.toJson

pub fn Char.toJson(self) -> Value

Char.fromJson

pub fn Char.fromJson(value: Value) -> Char!

Char.fromKeyText

pub fn Char.fromKeyText(s: String) -> Char!

Methods of Bytes

Bytes.toJson

pub fn Bytes.toJson(self) -> Value

Bytes.fromJson

pub fn Bytes.fromJson(value: Value) -> Bytes!

Bytes.fromKeyText

pub fn Bytes.fromKeyText(s: String) -> Bytes!

Methods of Void

Void.toJson

pub fn Void.toJson(self) -> Value

Void.fromJson

pub fn Void.fromJson(value: Value) -> Void!

Methods of Option

Option.toJson

pub fn Option[T: Encode].toJson(self) -> Value

Option.fromJson

pub fn Option[T: Decode].fromJson(value: Value) -> Option[T]!

Methods of Box

Box.toJson

pub fn Box[T: Encode].toJson(self) -> Value

A Box encodes as its content.

Box.fromJson

pub fn Box[T: Decode].fromJson(value: Value) -> Box[T]!

Methods of Array

Array.toJson

pub fn Array[T: Encode].toJson(self) -> Value

Array.fromJson

pub fn Array[T: Decode].fromJson(value: Value) -> Array[T]!

Methods of Map

Map.toJson

pub fn Map[K: Copy + Encode, V: Encode].toJson(self) -> Value

Map.fromJson

pub fn Map[K: DecodeKey + Eq + Hash, V: Decode].fromJson(value: Value) -> Map[K, V]!

Methods of Ordering

Ordering.toJson

pub fn Ordering.toJson(self) -> Value

Ordering.fromJson

pub fn Ordering.fromJson(value: Value) -> Ordering!

Methods of Tuple2

Tuple2.toJson

pub fn Tuple2[A: Encode, B: Encode].toJson(self) -> Value

Tuple2.fromJson

pub fn Tuple2[A: Decode, B: Decode].fromJson(value: Value) -> Tuple2[A, B]!

Methods of Tuple3

Tuple3.toJson

pub fn Tuple3[A: Encode, B: Encode, C: Encode].toJson(self) -> Value

Tuple3.fromJson

pub fn Tuple3[A: Decode, B: Decode, C: Decode].fromJson(value: Value) -> Tuple3[A, B, C]!

Methods of Tuple4

Tuple4.toJson

pub fn Tuple4[A: Encode, B: Encode, C: Encode, D: Encode].toJson(self) -> Value

Tuple4.fromJson

pub fn Tuple4[A: Decode, B: Decode, C: Decode, D: Decode].fromJson(value: Value) -> Tuple4[A, B, C, D]!

Methods of Tuple5

Tuple5.toJson

pub fn Tuple5[A: Encode, B: Encode, C: Encode, D: Encode, E: Encode].toJson(self) -> Value

Tuple5.fromJson

pub fn Tuple5[A: Decode, B: Decode, C: Decode, D: Decode, E: Decode].fromJson(value: Value) -> Tuple5[A, B, C, D, E]!

Methods of Tuple6

Tuple6.toJson

pub fn Tuple6[A: Encode, B: Encode, C: Encode, D: Encode, E: Encode, F: Encode].toJson(self) -> Value

Tuple6.fromJson

pub fn Tuple6[A: Decode, B: Decode, C: Decode, D: Decode, E: Decode, F: Decode].fromJson(value: Value) -> Tuple6[A, B, C, D, E, F]!

Methods of Tuple7

Tuple7.toJson

pub fn Tuple7[A: Encode, B: Encode, C: Encode, D: Encode, E: Encode, F: Encode, G: Encode].toJson(self) -> Value

Tuple7.fromJson

pub fn Tuple7[A: Decode, B: Decode, C: Decode, D: Decode, E: Decode, F: Decode, G: Decode].fromJson(value: Value) -> Tuple7[A, B, C, D, E, F, G]!

Methods of Tuple8

Tuple8.toJson

pub fn Tuple8[A: Encode, B: Encode, C: Encode, D: Encode, E: Encode, F: Encode, G: Encode, H: Encode].toJson(self) -> Value

Tuple8.fromJson

pub fn Tuple8[A: Decode, B: Decode, C: Decode, D: Decode, E: Decode, F: Decode, G: Decode, H: Decode].fromJson(value: Value) -> Tuple8[A, B, C, D, E, F, G, H]!

Functions

name

pub pure fn name(n: String) -> Metadata

Uses n as the JSON key of the field instead of its Kigumi name.

omitNone

pub pure fn omitNone() -> Metadata

Leaves the field out of the output when its value is None.

encode

pub fn encode[T: Encode](value: T) -> String!

Serializes value to JSON text, following the field metadata of record types.

encodeRef

pub fn encodeRef[T: Encode](value: &T) -> String!

Same as encode but borrows value, so a record or an Array can be encoded again afterwards.

decode

pub fn decode[T: Decode](text: String) -> T!

Parses JSON text into a T; fails on malformed input or a shape that does not match T.

kindOf

pub fn kindOf(value: Value) -> String

The JSON kind of a value, for error messages.

tag

pub fn tag(variant: String) -> Value

A variant as JSON: its name as a string, or {"Name": [payload...]} when it carries one.

tagged

pub fn tagged(variant: String, payload: Array[Value]) -> Value

parse

pub fn parse(source: String) -> Value!

Parses JSON text (RFC 8259) into a Value; any deviation fails with "invalid JSON".

render

pub fn render(value: Value) -> String!

Renders a value as compact JSON text; fails on a non-finite float, which JSON cannot express.