Browse the docs

silk.json.codec.

The interfaces that let a type be written to JSON and read from JSON.

When to use#

Implement Serialize for your type to write it with silk.json.value.Json.serialize. Implement Decode (no memory needed) or Deserialize (memory needed) to read it with Json.decode or Json.deserialize.

Details#

The standard library implements the interfaces for bool, the integer types, f32, f64, strings, Option<T>, and List<T>. Option<T> is null when absent.

A Serialize implementation for a struct usually writes an object with silk.json.object.JsonObject, or uses silk.json.reflect.JsonReflect.write. A Deserialize implementation reads tokens from a JsonScanner and calls JsonCodec.deserializeOne for each field.

Errors#

  • JsonError when the JSON does not match the type, a number does not fit, or a float that is not finite is written. A float that is not finite fails before any bytes are written.

Gotchas#

Each read function reads exactly one value and leaves the next token, such as , or ], for the caller. The caller must check that the document ends.

Examples#

Implement Serialize for a struct#

silk
import silk.core.effect { Effect }
import silk.json.codec { Serialize }
import silk.json.object { JsonObject }
import silk.json.output { JsonOptions }
import silk.json.scanner { JsonError }
import silk.json.value { Json }
import silk.io.writer { Writer, WriterError }

struct CaptureWriter {
  bytes: [u8; 64],
  length: usize,
}

impl Writer for CaptureWriter {
  effect fn writeAll(self: &mut Self, value: &[u8]) -> ()
    ! WriterError
    ? &mut Writer {
    let mut index: usize = 0
    while index < value.length {
      self.bytes[self.length] = value[index]
      self.length = self.length + 1
      index = index + 1
    }
    return ()
  }

  effect fn flush(self: &mut Self) -> ()
    ! WriterError
    ? &mut Writer {
    return ()
  }
}

fn holds(writer: &CaptureWriter, expected: &[u8]) -> bool {
  if writer.length != expected.length {
    return false
  }
  let mut index: usize = 0
  while index < expected.length {
    if writer.bytes[index] != expected[index] {
      return false
    }
    index = index + 1
  }
  return true
}

struct Point {
  x: i32,
  y: i32,
}

impl Serialize for Point {
  effect fn serialize(self: &Self, options: &JsonOptions) -> ()
    ! JsonError | WriterError
    ? &mut Writer {
    return run JsonObject.begin(options) |> JsonObject.field("x", &self.x)
      |> JsonObject.field("y", &self.y)
      |> JsonObject.end
  }
}

pub effect fn main() -> i32
  ! JsonError | WriterError {
  let mut writer = CaptureWriter { bytes: [0; 64], length: 0 }
  let point = Point { x: 3, y: -4 }
  run Json.serialize(&point, &JsonOptions.compact()) |> Effect.provideMut<Writer>(&mut writer)
  if !holds(&writer, b"{\"x\":3,\"y\":-4}") {
    return 1
  }
  return 0
}

Import as JsonCodec with import silk.json.codec { JsonCodec }.

Public declarations: 4.

Serialize#

silk
pub interface Serialize

A type that can write itself as one JSON value.

When to use#

Implement it for your type to write the type with silk.json.value.Json.serialize. The standard library implements it for bool, the integer types, f32, f64, strings, Option<T> (null when absent), and List<T> (an array).

Details#

An implementation for a struct usually writes an object with silk.json.object.JsonObject, or uses silk.json.reflect.JsonReflect.write.

Errors#

  • JsonError when a value cannot be written, such as a float that is not finite. A float that is not finite fails before any bytes are written.

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Writes self as one JSON value to the Writer, with options.

Decode#

silk
pub interface Decode

A type that can read itself from one JSON value without memory from an Allocator.

When to use#

Implement it for your type to read the type with silk.json.value.Json.decode. If the type needs memory, implement Deserialize instead. The standard library implements it for bool, the integer types, f32, f64, and Option<T> of those (null when absent).

Gotchas#

decode reads exactly one value and leaves the next token, such as , or ], for the caller. The caller must check that the document ends.

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Reads one value from scanner. It leaves the next token unread.

Deserialize#

silk
pub interface Deserialize

A type that can read itself from one JSON value and can use memory from the Allocator.

When to use#

Implement it for your type to read the type with silk.json.value.Json.deserialize. The standard library implements it for bool, the integer types, f32, f64, strings, Option<T> (null when absent), and List<T>.

Details#

An implementation for a struct reads tokens from the JsonScanner and calls JsonCodec.deserializeOne for each field.

Gotchas#

deserialize reads exactly one value and leaves the next token, such as , or ], for the caller. The caller must check that the document ends.

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Reads one value from scanner. It leaves the next token unread.

JsonCodec#

silk
pub struct JsonCodec

The owner type of the generic read and write operations. It has no fields and is never constructed.

Implementation JsonCodec#

silk
impl JsonCodec

Associated function decodeOne#

silk
pub fn decodeOne<T: Decode>(scanner: &mut JsonScanner) -> Result<T, JsonError>

Reads one value of type T from scanner with its Decode implementation. It leaves the next token unread.

Errors#

  • JsonError if the value is not valid JSON or does not have type T.

Associated function deserializeOne#

silk
pub effect fn deserializeOne<T: Deserialize>(scanner: &mut JsonScanner)
    -> T ! JsonError | OutOfMemoryError ? &mut Allocator

Reads one value of type T from scanner with its Deserialize implementation. It leaves the next token unread.

When to use#

Call it for each field in your own Deserialize implementation.

Errors#

  • JsonError if the value is not valid JSON or does not have type T.

  • OutOfMemoryError if the Allocator cannot supply the value.

Associated function writeOne#

silk
pub effect fn writeOne<T: Serialize>(value: &T, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Writes value with its Serialize implementation.

Errors#

  • JsonError from the implementation, such as for a float that is not finite.

  • WriterError if the Writer fails. Bytes that it accepted before the failure stay written.

Implementation Serialize for bool#

silk
impl Serialize for bool

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Decode for bool#

silk
impl Decode for bool

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Implementation Deserialize for bool#

silk
impl Deserialize for bool

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Serialize for u8#

silk
impl Serialize for u8

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Decode for u8#

silk
impl Decode for u8

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Implementation Deserialize for u8#

silk
impl Deserialize for u8

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Serialize for u16#

silk
impl Serialize for u16

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Decode for u16#

silk
impl Decode for u16

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Implementation Deserialize for u16#

silk
impl Deserialize for u16

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Serialize for u32#

silk
impl Serialize for u32

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Decode for u32#

silk
impl Decode for u32

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Implementation Deserialize for u32#

silk
impl Deserialize for u32

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Serialize for u64#

silk
impl Serialize for u64

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Decode for u64#

silk
impl Decode for u64

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Implementation Deserialize for u64#

silk
impl Deserialize for u64

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Serialize for usize#

silk
impl Serialize for usize

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Decode for usize#

silk
impl Decode for usize

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Implementation Deserialize for usize#

silk
impl Deserialize for usize

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Serialize for i8#

silk
impl Serialize for i8

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Decode for i8#

silk
impl Decode for i8

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Implementation Deserialize for i8#

silk
impl Deserialize for i8

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Serialize for i16#

silk
impl Serialize for i16

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Decode for i16#

silk
impl Decode for i16

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Implementation Deserialize for i16#

silk
impl Deserialize for i16

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Serialize for i32#

silk
impl Serialize for i32

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Decode for i32#

silk
impl Decode for i32

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Implementation Deserialize for i32#

silk
impl Deserialize for i32

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Serialize for i64#

silk
impl Serialize for i64

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Decode for i64#

silk
impl Decode for i64

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Implementation Deserialize for i64#

silk
impl Deserialize for i64

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Serialize for isize#

silk
impl Serialize for isize

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Decode for isize#

silk
impl Decode for isize

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Implementation Deserialize for isize#

silk
impl Deserialize for isize

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Decode for f32#

silk
impl Decode for f32

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Implementation Deserialize for f32#

silk
impl Deserialize for f32

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Serialize for f32#

silk
impl Serialize for f32

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Decode for f64#

silk
impl Decode for f64

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Implementation Deserialize for f64#

silk
impl Deserialize for f64

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Serialize for f64#

silk
impl Serialize for f64

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Serialize for string<'a>#

silk
impl<'a> Serialize for string<'a>

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Serialize for String#

silk
impl Serialize for String

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Deserialize for String#

silk
impl Deserialize for String

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Serialize for Option<T>#

silk
impl<T: Serialize> Serialize for Option<T>

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Decode for Option<T>#

silk
impl<T: Decode> Decode for Option<T>

Operation decode#

silk
fn decode(scanner: &mut JsonScanner) -> Result<Self, JsonError>

Implementation Deserialize for Option<T>#

silk
impl<T: Deserialize> Deserialize for Option<T>

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Implementation Serialize for List<T>#

silk
impl<T: Serialize> Serialize for List<T>

Operation serialize#

silk
effect fn serialize(self: &Self, options: &JsonOptions)
    -> () ! JsonError | WriterError ? &mut Writer

Implementation Deserialize for List<T>#

silk
impl<T: Deserialize> Deserialize for List<T>

Operation deserialize#

silk
effect fn deserialize(scanner: &mut JsonScanner)
    -> Self ! JsonError | OutOfMemoryError ? &mut Allocator

Category: Data formats.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2.

View the source of this page