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#
MsgpackErrorwith aMsgpackReasonand the byte offset of the problem.OutOfMemoryErrorif theAllocatorcannot 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#
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#
pub struct MsgpackEntryOne key and value of a MessagePack map.
Field key#
pub key: ValueThe key. MessagePack allows a key of any kind; most data uses text.
Field value#
pub value: ValueThe value.
Value#
pub union ValueAn 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#
Nilnil.
Bool#
Booltrue or false.
Field value#
pub value: boolThe value.
Integer#
IntegerAn integer that fits in i64.
Field value#
pub value: i64The value.
Unsigned#
UnsignedAn integer above the largest i64.
Field value#
pub value: u64The value.
Float#
FloatA float. A float 32 in the input is widened to f64.
Field value#
pub value: f64The value.
String#
StringText.
Field text#
pub text: StringThe text.
Binary#
BinaryBinary data.
Field bytes#
pub bytes: BytesThe data.
Array#
ArrayAn array.
Field values#
pub values: List<Value>The elements, in order.
Map#
MapA map.
Field entries#
pub entries: List<MsgpackEntry>The entries, in the order they were written. Keys are not checked for duplicates.
Extension#
ExtensionAn extension value, such as a timestamp (type -1). It is not interpreted.
Field kind#
pub kind: i8The extension type. MessagePack reserves the negative types.
Field data#
pub data: BytesThe payload.
Msgpack#
pub struct MsgpackThe owner of the functions that parse, read and write a MessagePack tree. It has no fields and is never constructed.
Implementation Msgpack#
impl MsgpackAssociated function parse#
pub effect fn parse(bytes: &[u8]) -> Value
! MsgpackError | OutOfMemoryError
? &mut AllocatorParses 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#
MsgpackErrorwithUnexpectedEndifbytesis empty or ends inside the value,ReservedBytefor the byte0xc1,InvalidUtf8for a string that is not UTF-8,DepthExceededif more than 64 arrays and maps are nested, orTrailingBytesif bytes follow the value. The partial tree is dropped.OutOfMemoryErrorif theAllocatorcannot supply the tree.
Associated function write#
pub effect fn write(value: &Value) -> ()
! MsgpackError | WriterError
? &mut WriterWrites 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#
MsgpackErrorwithMsgpackReason.TooLongif a string, binary value, extension payload, array or map is longer than 4294967295. The values before it stay written.WriterErrorif theWriterfails. Bytes that it accepted before the failure stay written.
Associated function field#
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#
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#
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#
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#
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#
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#
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#
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#
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.