gmsg - v1.0.1

gmsg

Types

DecodeError

</> 
pub type DecodeError {
  UnableToParse(String)
  UnableToDecode(String)
  UnsupportedDecode
  Truncated
}

Constructors 

  • UnableToParse(String)
  • UnableToDecode(String)
  • UnsupportedDecode
  • Truncated

EncodeError

</> 
pub type EncodeError {
  UnsupportedEncode(String)
  Overflow(String)
  Internal(String)
}

Constructors 

  • UnsupportedEncode(String)
  • Overflow(String)
  • Internal(String)

MsgPack

</>

Represents all possible values in the MessagePack serialization format.

This type is used as an intermediate representation for converting between user-defined types and serialized binary data.

Variants

  • Nil: Represents a null or absent value.
  • Bool: Represents a true or false boolean value.
  • Int: Represents a signed or unsigned integer.
  • Float: Represents a 64-bit floating-point value.
  • String: Represents a UTF-8 encoded text string.
  • Binary: Represents raw binary data using a flat BitArray. which is more efficient for streaming and incremental construction.
  • Array: Represents a list of MsgPack values.
  • Map: Represents key-value pairs of MsgPack values.

Notes

  • Keys in Map can be any MsgPack value, not just strings.
pub type MsgPack {
  MsgNil
  MsgBool(Bool)
  MsgInt(Int)
  MsgFloat(Float)
  MsgString(String)
  MsgBinary(BitArray)
  MsgArray(List(MsgPack))
  MsgMap(List(#(MsgPack, MsgPack)))
}

Constructors 

  • MsgNil

    Represents a null or absent value.

  • MsgBool(Bool)

    Boolean value: true or false.

  • MsgInt(Int)

    Integer value (signed or unsigned).

  • MsgFloat(Float)

    64-bit floating-point value.

  • MsgString(String)

    UTF-8 string value.

  • MsgBinary(BitArray)

    Raw binary data as a flat BitArray.

  • MsgArray(List(MsgPack))

    Ordered list of MsgPack values.

  • MsgMap(List(#(MsgPack, MsgPack)))

    Map of MsgPack keys to MsgPack values.

Values

decode_msgpack_from_bit_offset

</> 
pub fn decode_msgpack_from_bit_offset(
  bits: BitArray,
  offset: Int,
) -> Result(#(MsgPack, Int), DecodeError)

Decode a single MsgPack value that starts offset bits into the given bits, returning both the value and the offset immediately after the parsed term.

Unlike parse/2, this routine skips the dynamic layer and produces a raw MsgPack tree that callers can transform straight into domain types or inspect for metadata. It is therefore ideal for streaming decoders that need fine-grained control over where the next item begins.

Parameters

  • bits – A BitArray that may contain one or more concatenated MsgPack values.
  • offset – The bit-offset at which the next value is expected to start.

Returns

  • Ok(#(msgpack, next_offset)) when decoding succeeds, where next_offset is the first unconsumed bit after the value.
  • Error(DecodeError) when the data end is reached prematurely or an unknown tag is encountered.

The implementation peeks at the 8-bit tag found at offset, then delegates to decode_value_with_offset/3 for type-specific logic; errors are wrapped in UnableToDecode to keep failure reporting consistent across the module.

encode

</> 
pub fn encode(mp: MsgPack) -> Result(BitArray, EncodeError)

Serialise a MsgPack value into its binary BitArray representation.

The function pattern-matches every MsgPack constructor and delegates to the appropriate helper, guaranteeing that all valid MsgPack terms can be encoded without crashing.
Large or nested structures—MsgArray and MsgMap—are first converted to lists or pairs with encode_list/1 and encode_pairs/1, then wrapped with size-prefixed headers by encode_array_bits/1 and encode_map_bits/1.

import convert_msgpack.{encode, MsgInt}

encode(MsgInt(42))
// => Ok(<<0x2A>>)

Returns Ok(BitArray) on success or Error(EncodeError) if the value cannot be represented (for example, an out-of-range integer).

pack_array

</> 
pub fn pack_array(
  from elements: List(a),
  of inner_type: fn(a) -> MsgPack,
) -> MsgPack

pack_binary

</> 
pub fn pack_binary(data: BitArray) -> MsgPack

pack_bool

</> 
pub fn pack_bool(value: Bool) -> MsgPack

pack_float

</> 
pub fn pack_float(f: Float) -> MsgPack

pack_int

</> 
pub fn pack_int(i: Int) -> MsgPack

pack_map

</> 
pub fn pack_map(
  from pairs: List(#(k, v)),
  of key_type: fn(k) -> MsgPack,
  and value_type: fn(v) -> MsgPack,
) -> MsgPack

pack_nil

</> 
pub fn pack_nil() -> MsgPack

pack_string

</> 
pub fn pack_string(s: String) -> MsgPack

parse

</> 
pub fn parse(
  from bits: BitArray,
  using decoder: decode.Decoder(t),
) -> Result(t, DecodeError)

Decode a MsgPack‐encoded BitArray into a concrete value.

This is the primary entry-point for decoding in convert_msgpack. It performs two steps:

  1. parse_bits/1 turns the raw BitArray into a dynamic.Dynamic value.
  2. decode.run/2 applies the user-supplied decoder, translating any low-level failures into this library’s own DecodeError with convert_decode_errors/1.
import codec/gmsg
import convert_msgpack

let bytes = <<0x92, 1, 2>>  // MsgPack array [1, 2]

case convert_msgpack.parse(bytes, gmsg.array(gmsg.int)) {
  Ok([1, 2]) -> do_something()
  Error(err) -> handle(err)
}

Parameters

  • bits – A complete MsgPack document as a BitArray.
  • decoder – A decode.Decoder(t) describing how to map the intermediate dynamic value into the target type t.

Returns Ok(t) on success, or Error(DecodeError) when decoding fails.

Note: parse/2 is total; it never crashes. All problems are surfaced as a value you can pattern-match on.

✨ Search Document