silk.msgpack.value.

Parse MessagePack data into an owned tree of values, read fields from it, and write it back.

When to use#

Use Msgpack.parse for MessagePack whose shape is not known in advance. Read the tree with Msgpack.field, Msgpack.item and the as functions such as Msgpack.asI64, or by matching on Value, and write a tree with Msgpack.write. To read and write your own types, use silk.schema.msgpack.SchemaMsgpack, which builds no tree. To read tokens without allocating, use silk.msgpack.scanner.MsgpackScanner.

Details#

A Value owns everything below it. It holds what MessagePack holds and JSON does not: binary data, extension values, map keys of any kind, and integers up to the largest u64. The tree does not keep the width a number was written in: an integer is Value.Integer when it fits in i64 and Value.Unsigned above that, and a float 32 is widened to f64. Writing uses the shortest format for each value, and float 64 for every float.

Errors#

  • MsgpackError with a MsgpackReason and the byte offset of the problem.

  • OutOfMemoryError if the Allocator cannot supply the tree.

Gotchas#

Nesting is limited to 64 levels. Duplicate map keys are kept as written; Msgpack.field returns the first. An extension value, such as a timestamp (type -1), is kept as its type and payload, not interpreted.

Examples#

Read a field and write the tree back#

silk
import silk.collections.slice { Slice }
import silk.core.effect { Effect }
import silk.io.writer { Writer, WriterError }
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.msgpack.scanner { MsgpackError }
import silk.msgpack.value { Msgpack }

struct Capture {
  bytes: [u8; 32],
  length: usize,
}

impl Writer for Capture {
  effect fn writeAll(self: &mut Self, value: &[u8]) -> () ! WriterError ? &mut Writer {
    if self.length + value.length > 32 { fail Writer.failure() }
    Slice.copyInto<u8>(&mut self.bytes, self.length, value)
    self.length = self.length + value.length
    return ()
  }

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

pub effect fn main() -> i32 ! MsgpackError | WriterError | OutOfMemoryError {
  let mut allocator = Allocator.systemAllocatorProvider()
  // {"port": 8080, "tags": ["a"]}
  let input = b"\x82\xa4port\xcd\x1f\x90\xa4tags\x91\xa1a"
  let document = run Msgpack.parse(input) |> Effect.provideMut<Allocator>(&mut allocator)
  let port = Msgpack.field(&document, "port") |> Msgpack.asI64()
  if port.unwrapOr(0) != 8080 {
    return 1
  }
  let mut capture = Capture { bytes: [0; 32], length: 0 }
  run Msgpack.write(&document) |> Effect.provideMut<Writer>(&mut capture)
  if Slice.view<u8>(&capture.bytes, 0, capture.length) != input {
    return 2
  }
  return 0
}

Import as Msgpack with import silk.msgpack.value { Msgpack }.

Public declarations: 3.

MsgpackEntry#

silk
pub struct MsgpackEntry

One key and value of a MessagePack map.

Field key#

silk
pub key: Value

The key. MessagePack allows a key of any kind; most data uses text.

Field value#

silk
pub value: Value

The value.

Value#

silk
pub union Value

An owned MessagePack value: a scalar, or an array or map that owns its elements.

Details#

An integer is Integer when it fits in i64, whatever width it was written in, and Unsigned only above the largest i64. Msgpack.write writes either in the shortest format, so a tree built by hand with a small Unsigned writes the same bytes as the Integer.

Nil#

silk
Nil

nil.

Bool#

silk
Bool

true or false.

Field value#

silk
pub value: bool

The value.

Integer#

silk
Integer

An integer that fits in i64.

Field value#

silk
pub value: i64

The value.

Unsigned#

silk
Unsigned

An integer above the largest i64.

Field value#

silk
pub value: u64

The value.

Float#

silk
Float

A float. A float 32 in the input is widened to f64.

Field value#

silk
pub value: f64

The value.

String#

silk
String

Text.

Field text#

silk
pub text: String

The text.

Binary#

silk
Binary

Binary data.

Field bytes#

silk
pub bytes: Bytes

The data.

Array#

silk
Array

An array.

Field values#

silk
pub values: List<Value>

The elements, in order.

Map#

silk
Map

A map.

Field entries#

silk
pub entries: List<MsgpackEntry>

The entries, in the order they were written. Keys are not checked for duplicates.

Extension#

silk
Extension

An extension value, such as a timestamp (type -1). It is not interpreted.

Field kind#

silk
pub kind: i8

The extension type. MessagePack reserves the negative types.

Field data#

silk
pub data: Bytes

The payload.

Msgpack#

silk
pub struct Msgpack

The owner of the functions that parse, read and write a MessagePack tree. It has no fields and is never constructed.

Implementation Msgpack#

silk
impl Msgpack

Associated function parse#

silk
pub effect fn parse(bytes: &[u8]) -> Value
    ! MsgpackError | OutOfMemoryError
    ? &mut Allocator

Parses bytes, which must be exactly one MessagePack value, into an owned tree.

When to use#

Use it when the shape of the data is not known in advance. To read a known type, use silk.schema.msgpack.SchemaMsgpack.decode, which builds no tree.

Details#

Text is checked to be UTF-8 and copied; binary data and extension payloads are copied. An integer becomes Value.Integer when it fits in i64 and Value.Unsigned above that. Map entries keep their order and are not checked for duplicate keys.

Errors#

  • MsgpackError with UnexpectedEnd if bytes is empty or ends inside the value, ReservedByte for the byte 0xc1, InvalidUtf8 for a string that is not UTF-8, DepthExceeded if more than 64 arrays and maps are nested, or TrailingBytes if bytes follow the value. The partial tree is dropped.

  • OutOfMemoryError if the Allocator cannot supply the tree.

Associated function write#

silk
pub effect fn write(value: &Value) -> ()
    ! MsgpackError | WriterError
    ? &mut Writer

Writes value as MessagePack through the ambient Writer, without flushing it.

Details#

Each value is written in the shortest format that holds it, and every float as a float 64, so the bytes of a parsed tree can be shorter than its input, and equal trees write equal bytes. Map entries are written in their order.

Errors#

  • MsgpackError with MsgpackReason.TooLong if a string, binary value, extension payload, array or map is longer than 4294967295. The values before it stay written.

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

Associated function field#

silk
pub fn field<'a>(value: &'a Value, key: string) -> Option<&'a Value>

Returns the value of the first entry of a map whose key is the text key. Returns None if value is not a map or has no such key.

Details#

Only a text key matches: a binary key with the same bytes does not. The returned value borrows the tree.

Associated function fieldAt#

silk
pub fn fieldAt<'a>(value: Option<&'a Value>, key: string) -> Option<&'a Value>

Returns the value of the first entry whose key is the text key if value is a present map. Returns None in other cases.

When to use#

Use it to read nested fields in a chain: Msgpack.field(&document, "user") |> Msgpack.fieldAt("name").

Associated function asBool#

silk
pub fn asBool(value: Option<&Value>) -> Option<bool>

Returns the boolean that a present Value.Bool holds, or None for an absent value or another kind.

Associated function asI64#

silk
pub fn asI64(value: Option<&Value>) -> Option<i64>

Returns the integer that a present Value.Integer holds, or None for an absent value, another kind, or a Value.Unsigned above the largest i64. A float is not converted.

Associated function asU64#

silk
pub fn asU64(value: Option<&Value>) -> Option<u64>

Returns the integer that a present Value.Unsigned, or a Value.Integer of 0 or more, holds. Returns None for an absent value, another kind, or a negative integer. A float is not converted.

Associated function asF64#

silk
pub fn asF64(value: Option<&Value>) -> Option<f64>

Returns the number that a present Value.Float holds, or a present integer converted to the nearest f64. Returns None for an absent value or another kind.

Associated function asString#

silk
pub fn asString<'a>(value: Option<&'a Value>) -> Option<string<'a>>

Returns the text of a present Value.String, or None for an absent value or another kind, binary data included. The text borrows the tree.

Associated function asBinary#

silk
pub fn asBinary<'a>(value: Option<&'a Value>) -> Option<&'a [u8]>

Returns the data of a present Value.Binary, or None for an absent value or another kind, text included. The data borrows the tree.

Associated function item#

silk
pub fn item<'a>(value: &'a Value, index: usize) -> Option<&'a Value>

Returns the element of an array at the zero-based index, or None if value is not an array or index is out of range. The returned value borrows the tree.

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, x86_64-pc-windows-msvc, wasm64-unknown-unknown.

View the source of this page