silk/json_value

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

Owned dynamic JSON values parsed from a byte slice and written through the ambient Writer.

When to use

Use Json.parse when a document needs borrowed field access after parsing. Use Json.write or Json.writeWith to serialize an owned tree. Token-only consumers can use silk.json_scanner without an allocator.

Details

Arrays and objects retain source order. Numbers retain valid source spelling and decode into integers or floats only when accessed. String escapes are decoded into owned UTF-8 storage. A failed parse releases every partially built value.

Gotchas

A borrowed field or string cannot outlive its owning Value. JSON output can leave an accepted prefix if Writer fails; it does not flush the writer.

Examples

Read an integer member

import silk.allocator { Allocator, OutOfMemoryError }
import silk.effect { Effect }
import silk.json_scanner { JsonError }
import silk.json_value { Json }
import silk.option { Option }

effect fn read() -> i32 ! JsonError | OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let document = run Json.parse(b"{\"id\":42}")
    |> Effect.provideMut<Allocator>(&mut allocator)
  return Json.field(&document, "id") |> Json.asI32 |> Option.unwrapOr<i32>(0)
}

effect fn recover(error: JsonError | OutOfMemoryError) -> i32 { return 0 }
pub fn main() -> i32 { return run Effect.catchAll(read(), recover) }

Import as Json with import silk.json_value { Json }.

Public declarations: 4.

`JsonEntry`

pub struct JsonEntry

One owned key/value pair in an insertion-ordered JSON object.

Field `key`

pub key: String

The decoded key.

Field `value`

pub value: Value

The owned member value.

`JsonChild`

pub union JsonChild

One owned child: an array item or an object member with its decoded key.

Details

Both container kinds use this one recursive storage shape, so cleanup follows one finite Box<Vector<JsonChild>> specialization even when arrays and objects nest in each other.

`Item`

JsonChild.Item { value: Value }: JsonChild

An array element without a key.

Field `value`

pub value: Value

The owned element value.

`Member`

JsonChild.Member { entry: JsonEntry }: JsonChild

An object member with a decoded key.

Field `entry`

pub entry: JsonEntry

The owned key and value.

`Value`

pub union Value

An owned JSON null, boolean, raw number, decoded string, array, or object.

`Null`

Value.Null: Value

JSON null.

`Bool`

Value.Bool { value: bool }: Value

A JSON boolean.

Field `value`

pub value: bool

The boolean value.

`Number`

Value.Number { text: String }: Value

A valid number lexeme retained exactly as read.

Field `text`

pub text: String

The valid number text in its source spelling.

`String`

Value.String { text: String }: Value

Decoded UTF-8 text.

Field `text`

pub text: String

The decoded UTF-8 text.

`Array`

Value.Array { values: silk/box.Box<silk/vector.Vector<silk/json_value.JsonChild>> }: Value

Values in source order.

Field `values`

pub values: silk/box.Box<silk/vector.Vector<silk/json_value.JsonChild>>

The array elements in source order.

`Object`

Value.Object { entries: silk/box.Box<silk/vector.Vector<silk/json_value.JsonChild>> }: Value

Members in source order.

Field `entries`

pub entries: silk/box.Box<silk/vector.Vector<silk/json_value.JsonChild>>

The object members in source order.

`Json`

pub struct Json

Operations on owned JSON values.

Associated function `Json.parse`

pub effect<'life0> fn parse<'life0>(bytes: &'life0 [u8]) -> Value ! JsonError | OutOfMemoryError ? &mut Allocator

Parses one complete strict JSON document into an owned value tree.

Details

Every allocation is charged to the ambient allocator. On syntax, duplicate-key, or allocation failure, the partially built tree is dropped.

Associated function `Json.decode`

pub fn decode<T, 'life1>(bytes: &'life1 [u8]) -> silk/result.Result<T, silk/json_scanner.JsonError>

Decodes one complete JSON document without an allocator requirement.

Associated function `Json.deserialize`

pub effect<'life1> fn deserialize<T, 'life1>(bytes: &'life1 [u8]) -> T ! JsonError | OutOfMemoryError ? &mut Allocator

Deserializes one complete JSON document, with allocation charged to the ambient allocator.

Associated function `Json.serialize`

pub effect<'life1 & 'life2> fn serialize<T: 'life1 & 'life2, 'life1, 'life2>(value: &'life1 T, options: &'life2 silk/json_output.JsonOptions) -> () ! JsonError | WriterError ? &mut Writer

Serializes one value through its static witness and the ambient Writer.

Associated function `Json.write`

pub effect<'life0> fn write<'life0>(document: &'life0 silk/json_value.Value) -> () ! JsonError | WriterError ? &mut Writer

Writes a tree compactly through the ambient Writer.

Associated function `Json.writeWith`

pub effect<'life0 & 'life1> fn writeWith<'life0, 'life1>(document: &'life0 silk/json_value.Value, options: &'life1 silk/json_output.JsonOptions) -> () ! JsonError | WriterError ? &mut Writer

Writes a tree with explicit indentation and depth policy.

Associated function `Json.field`

pub fn field<'a, 'life1>(self: &'a silk/json_value.Value, key: string<'life1>) -> silk/option.Option<&'a silk/json_value.Value>

Borrows a member of an object, or returns None for an absent key or other value kind.

Associated function `Json.fieldAt`

pub fn fieldAt<'a, 'life1>(self: silk/option.Option<&'a silk/json_value.Value>, key: string<'life1>) -> silk/option.Option<&'a silk/json_value.Value>

Chains an object lookup while preserving an absent value.

Associated function `Json.asI32`

pub fn asI32<'life0>(self: silk/option.Option<&'life0 silk/json_value.Value>) -> silk/option.Option<i32>

Decodes an integer number into i32, returning None for absence or overflow.

Associated function `Json.asI64`

pub fn asI64<'life0>(self: silk/option.Option<&'life0 silk/json_value.Value>) -> silk/option.Option<i64>

Decodes an integer number into i64, returning None for absence or overflow.

Associated function `Json.asU64`

pub fn asU64<'life0>(self: silk/option.Option<&'life0 silk/json_value.Value>) -> silk/option.Option<u64>

Decodes an integer number into u64, returning None for absence or overflow.

Associated function `Json.asF64`

pub fn asF64<'life0>(self: silk/option.Option<&'life0 silk/json_value.Value>) -> silk/option.Option<f64>

Decodes a finite f64, or returns None for absence, wrong type, invalid text, or overflow.

Associated function `Json.asF32`

pub fn asF32<'life0>(self: silk/option.Option<&'life0 silk/json_value.Value>) -> silk/option.Option<f32>

Decodes a finite f32, or returns None for absence, wrong type, invalid text, or overflow.

Associated function `Json.asString`

pub fn asString<'a>(self: silk/option.Option<&'a silk/json_value.Value>) -> silk/option.Option<string<'a>>

Borrows decoded string text while its owning tree remains alive.

Implementation `Serialize for Value`

impl Serialize for Value

Operation `serialize`

serialize = Value.impl@0.serialize

Implementation `Deserialize for Value`

impl Deserialize for Value

Operation `deserialize`

deserialize = Value.impl@1.deserialize

silk/json_value

On this page