msgpack

The msgpack library serialises Scriptling values to MessagePack binary form and parses MessagePack payloads back into Scriptling values. It is the binary counterpart to json — more compact and faster, at the cost of human readability.

packb returns a bytes value; unpackb takes one.

Available Functions

Functions

packb(obj)

Converts a Scriptling value (dict, list, tuple, str, int, float, bool, None, or bytes) to its MessagePack binary representation.

Parameters:

• obj: Value to serialise. bytes round-trips as msgpack bin; str as msgpack str; tuples and lists both encode as msgpack arrays.

Returns: bytes: the MessagePack-encoded payload.

import msgpack

payload = msgpack.packb({"user": "alice", "id": 42})
# payload is a bytes value

unpackb(packed)

Parses MessagePack bytes back into a Scriptling value. msgpack bin decodes to bytes; msgpack str decodes to str; integers are clamped to Scriptling’s int64.

Parameters:

• packed (bytes): A bytes value containing a MessagePack payload.

Returns: dict, list, str, int, float, bool, None, or bytes: the decoded value.

Raises: Error: if packed is not a bytes value or the payload is malformed.

import msgpack

payload = msgpack.packb({"name": "alice"})
data = msgpack.unpackb(payload)
print(data["name"])  # "alice"

Round-tripping

Every supported value type round-trips losslessly:

import msgpack

values = [
    None, True, False,
    0, -5, 12345,
    3.14,
    "hello",
    [1, 2, 3],
    {"a": 1, "b": [2, 3]},
]

for v in values:
    assert msgpack.unpackb(msgpack.packb(v)) == v

Binary data round-trips as bytes:

import msgpack
import bytes

binary = bytes([0, 128, 255, 1, 254])
assert msgpack.unpackb(msgpack.packb(binary)) == binary

Limitations

• ext types (msgpack timestamp, application-defined extensions) are not supported.
• Streaming Packer / Unpacker classes are intentionally omitted — packb / unpackb cover the one-shot use case.
• Large integers clamp to Scriptling’s int64 range, matching json’s behaviour.

Choosing a backing codec (Go embedders)

The msgpack library is codec-backed: the stdlib.MsgpackCodec interface is

type MsgpackCodec interface {
    Name() string
    Marshal(v interface{}) ([]byte, error)
    Unmarshal(data []byte, v interface{}) error
}

This is structurally identical to gossip’s codec.Serializer — any gossip codec satisfies it without an adapter, so a single driver instance can be shared between Scriptling’s msgpack library and a gossip cluster, guaranteeing both sides use the same wire format.

import (
    "github.com/paularlott/gossip/codec"
    "github.com/paularlott/scriptling/stdlib"
)

// One codec instance, used by both gossip and Scriptling.
shared := codec.NewShamatonMsgpackCodec() // or Vmihailenco, Hashicorp, etc.

// Hand it to gossip:
cfg := gossip.DefaultConfig() // already defaults to shamaton
cfg.MsgCodec = shared

// And to Scriptling — register a library built from the shared codec:
p.RegisterLibrary(stdlib.NewMsgpackLibrary(shared))

The default package-level library is stdlib.MsgpackLibrary and defaults to gossip’s codec.NewShamatonMsgpackCodec() (matching gossip.DefaultConfig), which is what stdlib.RegisterAll registers. Embedders who want to override that globally can reassign the var before calling RegisterAll:

stdlib.MsgpackLibrary = stdlib.NewMsgpackLibrary(myCodec)
stdlib.RegisterAll(p)

See Also

• json: the text counterpart — human-readable, larger payloads.
• bytes: the binary type returned by packb().
• toml / yaml: other structured data formats.