March Docs

Msgpack

Msgpack module: MessagePack binary serialization.

Encodes and decodes the MessagePack format (https://msgpack.org/). Compact binary alternative to JSON; supported by most languages.

Types: Value = Null | Bool(Bool) | Int(Int) -- 63-bit signed; see plan for range details | Str(String) -- UTF-8 bytes | Bin(List(Int)) -- raw bytes (values 0-255) | Array(List(Value)) | Map(List((Value, Value)))

Functions: encode(Value) -> List(Int) decode(List(Int)) -> Result(Value, String) decode_all(List(Int)) -> Result(List(Value), String) null/bool/int/str/bin/array/map -- convenience constructors

Note: Float is not supported in v1 (requires float_bits builtin). Note: encode returns List(Int); wrap with Bytes.from_list if needed.

Format byte constants (decimal): 192 = nil 194 = false 195 = true 196..198 = bin8/16/32 202..203 = float32/64 (unsupported) 204..207 = uint8/16/32/64 208..211 = int8/16/32/64 217..219 = str8/16/32 220..221 = array16/32 222..223 = map16/32 128..143 = fixmap 144..159 = fixarray 160..191 = fixstr 0..127 = pos fixint 224..255 = neg fixint

Types

typeValueValue#

Functions

fnarrayarray(xs : List(Value)) : Value do Array(xs) end#

Construct a MessagePack array value from a list of values.

Msgpack.encode(Msgpack.array([Msgpack.bool(true), Msgpack.int(1)]))   -- [146, 195, 1]
fnbinbin(bs : List(Int)) : Value do Bin(bs) end#

Construct a MessagePack binary value from a list of byte ints (0-255). The values are not validated; anything outside 0-255 produces an invalid encoding.

Msgpack.encode(Msgpack.bin([1, 2]))   -- [196, 2, 1, 2]
fnboolbool(b : Bool) : Value do Bool(b) end#

Construct a MessagePack boolean value (encoded as 195 for true, 194 for false).

Msgpack.encode(Msgpack.bool(false))   -- [194]
fndecodedecode(bs : List(Int)) : Result(Value, String)#

Decode a MessagePack byte list to a Value. Returns Err if the input is empty, truncated, has trailing bytes, or contains an unsupported format byte (float, ext). Every input produced by encode round-trips. A uint64 above the 63-bit Int range wraps rather than failing.

Msgpack.decode([192])                -- Ok(Null)
Msgpack.decode([42])                 -- Ok(Int(42))
Msgpack.decode([195])                -- Ok(Bool(true))
Msgpack.decode([205, 1, 44])         -- Ok(Int(300))
Msgpack.decode([])                   -- Err("unexpected end of input")
Msgpack.decode([42, 1])              -- Err("trailing bytes after value")
Msgpack.decode([202, 0, 0, 0, 0])    -- Err("float32 is not supported")
fndecode_alldecode_all(bs : List(Int)) : Result(List(Value), String)#

Decode zero or more concatenated MessagePack values from bs. Returns Ok([]) on empty input, or the first error (a truncated final value is an error, not a partial result). Useful for framing protocols.

Msgpack.decode_all([195, 42, 194])
-- Ok([Bool(true), Int(42), Bool(false)])
fnencodeencode(v : Value) : List(Int)#

Encode a Value to a list of bytes (0-255) in MessagePack format. Always picks the smallest encoding: integers use fixint, then the narrowest int8/16/32 (negative) or uint8/16/32/64 (non-negative) form; strings (UTF-8 byte length), binaries, arrays and maps use the fix/8/16/32 header for their length. Map pairs are written in list order. Bin elements are emitted as given and are not range-checked.

Msgpack.encode(Msgpack.null())        -- [192]
Msgpack.encode(Msgpack.bool(true))    -- [195]
Msgpack.encode(Msgpack.int(42))       -- [42]
Msgpack.encode(Msgpack.int(-1))       -- [255]
Msgpack.encode(Msgpack.int(300))      -- [205, 1, 44]
Msgpack.encode(Msgpack.str("hi"))     -- [162, 104, 105]
Msgpack.encode(Msgpack.str("é"))      -- [162, 195, 169]
fnintint(n : Int) : Value do Int(n) end#

Construct a MessagePack integer value. Any March Int is accepted; encode chooses the narrowest wire format.

Msgpack.encode(Msgpack.int(-33))   -- [208, 223]
fnmapmap(kvs : List((Value, Value))) : Value do Map(kvs) end#

Construct a MessagePack map value from a list of (key, value) pairs. Keys may be any Value; order is kept and duplicates are not removed.

Msgpack.encode(Msgpack.map([(Msgpack.str("a"), Msgpack.null())]))   -- [129, 161, 97, 192]
fnnullnull() : Value do Null end#

Construct a MessagePack null value (Null, encoded as [192]).

Msgpack.encode(Msgpack.null())   -- [192]
fnstrstr(s : String) : Value do Str(s) end#

Construct a MessagePack string value. It is encoded as its UTF-8 bytes, with a length header counting bytes, not characters.

Msgpack.encode(Msgpack.str("a"))   -- [161, 97]