Msgpax v2.2.0 Msgpax.Ext View Source
A struct used to represent the MessagePack Extension type.
Examples
Let’s say we want to be able to serialize a custom type that consists of a
byte data
repeated reps
times. We could represent this as a RepByte
struct in Elixir:
defmodule RepByte do
defstruct [:data, :reps]
end
A simple (albeit not space efficient) approach to encoding such data is simply
a binary containing data
for reps
times: %RepByte{data: ?a, reps: 2}
would be encoded as "aa"
.
We can now define the Msgpax.Packer
protocol for the RepByte
struct to
tell Msgpax
how to encode this struct (we’ll choose 10
as an arbitrary
integer to identify the type of this extension).
defimpl Msgpax.Packer, for: RepByte do
@rep_byte_ext_type 10
def pack(%RepByte{data: b, reps: reps}) do
@rep_byte_ext_type
|> Msgpax.Ext.new(String.duplicate(<<b>>, reps))
|> Msgpax.Packer.pack()
end
end
Now, we can pack RepByte
s:
iex> packed = Msgpax.pack!(%RepByte{data: ?a, reps: 3})
iex> Msgpax.unpack!(packed)
#Msgpax.Ext<10, "aaa">
Unpacking
As seen in the example above, since the RepByte
struct is packed as a
MessagePack extension, it will be unpacked as that extension later on; what we
may want, however, is to unpack that extension back to a RepByte
struct.
To do this, we can pass an :ext
option to Msgpax.unpack/2
(and other
unpacking functions). This option has to be a module that implements the
Msgpax.Ext.Unpacker
behaviour; it will be used to unpack extensions to
arbitrary Elixir terms.
For our RepByte
example, we could create an unpacker module like this:
defmodule MyExtUnpacker do
@behaviour Msgpax.Ext.Unpacker
@rep_byte_ext_type 10
def unpack(%Msgpax.Ext{type: @rep_byte_ext_type, data: data}) do
<<byte, _rest::binary>> = data
{:ok, %RepByte{data: byte, reps: byte_size(data)}}
end
end
With this in place, we can now unpack a packed RepByte
back to a RepByte
struct:
iex> packed = Msgpax.pack!(%RepByte{data: ?a, reps: 3})
iex> Msgpax.unpack!(packed, ext: MyExtUnpacker)
%RepByte{data: ?a, reps: 3}
Link to this section Summary
Functions
Creates a new Msgpax.Ext
struct
Link to this section Types
Link to this section Functions
Creates a new Msgpax.Ext
struct.
type
must be an integer in 0..127
and it will be used as the type of the
extension (whose meaning depends on your application). data
must be a binary
containing the serialized extension (whose serialization depends on your
application).
Examples
iex> Msgpax.Ext.new(24, "foo")
#Msgpax.Ext<24, "foo">