msgpack

auto data = tuple("MessagePack!", [1, 2], true);

auto serialized = pack(data);

// ...

typeof(data) deserialized;

unpack(serialized, deserialized);

assert(data == deserialized);

ubyte[] pack (bool withFieldName = false, Args...)(in Args args);

Serializes args.

Assumes single object if the length of args == 1, otherwise array object.

Params:

Args args

the contents to serialize.

Returns:
a serialized data.

@trusted Unpacked unpack (in ubyte[] buffer);

Deserializes buffer using stream deserializer.

Params:

ubyte[] buffer

the buffer to deserialize.

Returns:
a Unpacked contains deserialized object.

Throws:
UnpackException if deserialization doesn't succeed.

void unpack (bool withFieldName = false, Args...)(in ubyte[] buffer, ref Args args);

Deserializes buffer using direct-conversion deserializer.

Assumes single object if the length of args == 1, otherwise array object.

Params:

ubyte[] buffer	the buffer to deserialize.
Args args	the references of values to assign.

Type unpack (Type, bool withFieldName = false)(in ubyte[] buffer);

Return value version

class MessagePackException : object.Exception;

MessagePackException is a root Exception for MessagePack related operation.

struct nonPacked ;

Attribute for specifying non pack/unpack field. This is an alternative approach of MessagePackable mixin.

Example:

struct S
{
    int num;
    // Packer/Unpacker ignores this field;
    @nonPacked string str;
}

struct PackerImpl (Stream) if (isOutputRange!(Stream, ubyte) && isOutputRange!(Stream, ubyte[]));

Packer is a MessagePack serializer

Example:

auto packer = packer(Appender!(ubyte[])());

packer.packArray(false, 100, 1e-10, null);

stdout.rawWrite(packer.buffer.data);

NOTE:
Current implementation can't deal with a circular reference. If you try to serialize a object that has circular reference, runtime raises 'Stack Overflow'.

this(Stream stream, bool withFieldName = false);

Constructs a packer with stream.

Params:

Stream stream	the stream to write.
bool withFieldName	serialize class / struct with field name

this(bool withFieldName = false);

Constructs a packer with withFieldName.

Params:

bool withFieldName

serialize class / struct with field name

Stream stream ();

Forwards to stream .

Returns:
the stream .

PackerImpl pack (T)(in T value) if (is(Unqual!T == bool));
PackerImpl pack (T)(in T value) if (isUnsigned!T && !is(Unqual!T == enum));
PackerImpl pack (T)(in T value) if (isSigned!T && isIntegral!T && !is(Unqual!T == enum));
PackerImpl pack (T)(in T value) if (isFloatingPoint!T && !is(Unqual!T == enum));
PackerImpl pack (T)(in T value) if (is(Unqual!T == enum));

Serializes argument and writes to stream.

If the argument is the pointer type, dereferences the pointer and serializes pointed value.

int  a = 10;
int* b = &b;

packer.pack(b);  // serializes 10, not address of a

Serializes nil if the argument of nullable type is null.

NOTE:
MessagePack doesn't define real type format. Don't serialize real if you communicate with other languages. Transfer double serialization if real on your environment equals double.

Params:

T value

the content to serialize.

Returns:
self, i.e. for method chaining.

PackerImpl pack (T)(in T value) if (is(Unqual!T == typeof(null)));
PackerImpl pack (T)(in T value) if (isPointer!T);
PackerImpl pack (T)(in T array) if (isArray!T);
PackerImpl pack (T)(in T array) if (isAssociativeArray!T);
PackerImpl pack (Types...)(auto ref const Types objects) if (Types.length > 1);

Overload for pack (null) for 2.057 or later

PackerImpl pack (T)(in T object) if (is(Unqual!T == class));
PackerImpl pack (T)(auto ref T object) if (is(Unqual!T == struct));

Serializes object and writes to stream.

Calling toMsgpack if class and struct implement toMsgpack method. toMsgpack signature is:

void toMsgpack(Packer)(ref Packer packer) const

This method serializes all members of T object if class and struct don't implement toMsgpack .

An object that doesn't implement toMsgpack is serialized to Array type.

packer.pack(tuple(true, 1, "Hi!"))  // -> '[true, 1, "Hi!"]', not 'ture, 1, "Hi!"'

struct Foo
{
    int num    = 10;
    string msg = "D!";
}
packer.pack(Foo());  // -> '[10, "D!"]'

class Base
{
    bool flag = true;
}
class Derived : Base
{
    double = 0.5f;
}
packer.pack(new Derived());  // -> '[true, 0.5f]'

Params:

T object

the content to serialize.

Returns:
self, i.e. for method chaining.

PackerImpl packArray (Types...)(auto ref const Types objects);
PackerImpl packMap (Types...)(auto ref const Types objects);

Serializes the arguments as container to stream.

packer.packArray(true, 1);  // -> [true, 1]
packer.packMap("Hi", 100);  // -> ["Hi":100]

In packMap, the number of arguments must be even.

Params:

Types objects

the contents to serialize.

Returns:
self, i.e. for method chaining.

PackerImpl beginArray (in size_t length);
PackerImpl beginMap (in size_t length);

Serializes the type-information to stream.

These methods don't serialize contents. You need to call pack method to serialize contents at your own risk.

packer.beginArray(3).pack(true, 1);  // -> [true, 1,

// other operation

packer.pack("Hi!");                  // -> [true, 1, "Hi!"]

Params:

size_t length

the length of container.

Returns:
self, i.e. for method chaining.

alias Packer = PackerImpl!(Appender!(ubyte[])).PackerImpl;

Default serializer

void registerPackHandler (T, alias Handler, Stream = Appender!(ubyte[]))();

Register a serialization handler for T type

Example:

registerPackHandler!(Foo, fooPackHandler);

PackerImpl!Stream packer (Stream)(Stream stream, bool withFieldName = false);

Helper for Packer construction.

Params:

Stream stream	the stream to write.
bool withFieldName	serialize class / struct with field name

Returns:
a Packer object instantiated and initialized according to the arguments.

struct RefBuffer ;

RefBuffer is a reference stored buffer for more efficient serialization

Example:

auto packer = packer(RefBuffer(16));  // threshold is 16

// packs data

writev(fd, cast(void*)packer.buffer.vector.ptr, packer.buffer.vector.length);

this(in size_t threshold, in size_t chunkSize = 8192);

Constructs a buffer.

Params:

size_t threshold	the threshold of writing value or stores reference.
size_t chunkSize	the default size of chunk for allocation.

nothrow @property @safe ubyte[] data ();

Returns the buffer contents that excluding references.

Returns:
the non-contiguous copied contents.

nothrow @property ref @safe iovec[] vector ();

Forwards to all buffer contents.

Returns:
the array of iovec struct that stores references.

@safe void put (in ubyte value);
@safe void put (in ubyte[] value);

Writes the argument to buffer and stores the reference of writed content if the argument size is smaller than threshold, otherwise stores the reference of argument directly.

Params:

ubyte value

the content to write.

class UnpackException : msgpack.MessagePackException;

UnpackException is thrown on deserialization failure

template InternalBuffer ()

Internal buffer and related operations for Unpacker

Following Unpackers mixin this template. So, Unpacker can use following methods.

//buffer image:
+-------------------------------------------+
| [object] | [obj | unparsed... | unused... |
+-------------------------------------------+
           ^ offset
                  ^ current
                                ^ used
                                            ^ buffer.length

This mixin template is a private.

ubyte[] buffer ();

Forwards to internal buffer .

Returns:
the reference of internal buffer .

void feed (in ubyte[] target);

Fills internal buffer with target.

Params:

ubyte[] target

new serialized buffer to deserialize.

void bufferConsumed (in size_t size);

Consumes buffer. This method is helper for buffer property. You must use this method if you write bytes to buffer directly.

Params:

size_t size

the number of consuming.

void removeUnparsed ();

Removes unparsed buffer.

const size_t size ();

Returns:
the total size including unparsed buffer size .

const size_t parsedSize ();

Returns:
the parsed size of buffer.

const size_t unparsedSize ();

Returns:
the unparsed size of buffer.

struct Unpacker ;

This Unpacker is a MessagePack direct-conversion deserializer

This implementation is suitable for fixed data.

Example:

// serializedData is [10, 0.1, false]
auto unpacker = Unpacker(serializedData);

uint   n;
double d;
bool   b;

unpacker.unpackArray(n, d, b);

// using Tuple
Tuple!(uint, double, bool) record;
unpacker.unpack(record);  // record is [10, 0.1, false]

NOTE:
Unpacker becomes template struct if Phobos supports truly IO module.

this(in ubyte[] target, in size_t bufferSize = 8192, bool withFieldName = false);

Constructs a Unpacker .

Params:

ubyte[] target	byte buffer to deserialize
size_t bufferSize	size limit of buffer size

nothrow @safe void clear ();

Clears states for next deserialization.

Unpacker unpack (T)(ref T value) if (is(Unqual!T == bool));
Unpacker unpack (T)(ref T value) if (isUnsigned!T && !is(Unqual!T == enum));
Unpacker unpack (T)(ref T value) if (isSigned!T && isIntegral!T && !is(Unqual!T == enum));
Unpacker unpack (T)(ref T value) if (isFloatingPoint!T && !is(Unqual!T == enum));
Unpacker unpack (T)(ref T value) if (is(Unqual!T == enum));
Unpacker unpack (T)(T value) if (isPointer!T);
Unpacker unpack (Types...)(ref Types objects) if (Types.length > 1);

Deserializes T object and assigns to value.

If the argument is pointer, dereferences pointer and assigns deserialized value.

int* a;
unpacker.unpack(a)  // enforce throws Exception because a is null or
                    // no throw if deserialized value is nil

int b; a = &b;
unpacker.unpack(b)  // b is deserialized value or
                    // assigns null if deserialized value is nil

Params:

T value

the reference of value to assign.

Returns:
self, i.e. for method chaining.

Throws:
UnpackException when doesn't read from buffer or precision loss occurs and MessagePackException when T type doesn't match serialized type.

Unpacker unpack (T)(ref T array) if (isArray!T && !is(Unqual!T == enum));
Unpacker unpack (T)(ref T array) if (isAssociativeArray!T);

Deserializes T object and assigns to array.

This is convenient method for array deserialization. Rollback will be completely successful if you deserialize raw type((u)byte[] or string types). But, Rollback will be one element(e.g. int) if you deserialize other types(e.g. int[], int[int])

No assign if the length of deserialized object is 0.

In a static array, this method checks the length. Do rollback and throw exception if length of array is different from length of deserialized object.

Params:

T array

the reference of array to assign.

Returns:
self, i.e. for method chaining.

Throws:
UnpackException when doesn't read from buffer or precision loss occurs and MessagePackException when T type doesn't match serialized type.

Unpacker unpack (T, Args...)(ref T object, auto ref Args args) if (is(Unqual!T == class));
Unpacker unpack (T)(ref T object) if (is(Unqual!T == struct));

Deserializes T object and assigns to object.

Calling fromMsgpack if class and struct implement fromMsgpack method. fromMsgpack signature is:

void fromMsgpack(ref Unpacker unpacker)

Assumes std.typecons.Tuple or simple struct if struct doesn't implement fromMsgpack . Checks length if T is a std.typecons.Tuple or simple struct.

Params:

T object	the reference of object to assign.
Args args	the arguments to class constructor(class only). This is used at new statement if object is null.

Returns:
self, i.e. for method chaining.

Unpacker unpackArray (Types...)(ref Types objects);
Unpacker unpackMap (Types...)(ref Types objects);

Deserializes the container object and assigns to each argument.

These methods check the length. Do rollback if the length of arguments is different from length of deserialized object.

In unpackMap, the number of arguments must be even.

Params:

Types objects

the references of object to assign.

Returns:
self, i.e. for method chaining.

@safe size_t beginArray ();
@safe size_t beginMap ();

Deserializes the type-information of container.

These methods don't deserialize contents. You need to call unpack method to deserialize contents at your own risk.

// serialized data is [1, "Hi!"];
int num;
unpacker.beginArray(2).unpack(num);  // num is 1

// other operation

string str;
unpacker.unpack(str);  // str is "Hi!"

Returns:
the container size.

int scan (Types...)(scope int delegate(ref Types) dg);
int opApply (Types...)(scope int delegate(ref Types) dg);

Scans an entire buffer and converts each objects.

This method is used for unpacking record-like objects.

Example:

// serialized data is "[1, 2][3, 4][5, 6][...".
auto unpacker = Unpacker(serializedData);
foreach (n, d; &unpacker.scan!(int, int))  // == "foreach (int n, int d; unpacker)"
    writeln(n, d); // 1st loop "1, 2", 2nd loop "3, 4"...

void registerUnpackHandler (T, alias Handler)();

Register a deserialization handler for T type

Example:

registerUnackHandler!(Foo, fooUnackHandler);

struct Value ;

Value is a MessagePack value representation

Example:

auto unpacker = StreamingUnpacker(pack(1, 0.1L) ~ pack(true) ~ pack("foobarbaz"));

foreach (unpacked; unpacker) {
    if (unpacked.type == Value.Type.array) {
        foreach (obj; unpacked) {
            switch (obj.type) {
            case Value.Type.unsigned: writeln(obj.as!(uint)); break;
            case Value.Type.floating:            writeln(obj.as!(real)); break;
            defalut:
                throw new Exception("Unknown type");
            }
        }
    } else {
        if (unpacked.type == Value.Type.boolean)
            writeln(unpacked.as!(bool));
        else
            writeln("Message: ", unpacked.as!(string));
    }
}

enum Type : int;

MessagePack value type

nil

nil (null in D)

boolean

true, false

unsigned

positive fixnum, uint 8, uint 16, uint 32, uint 64

signed

negative fixnum, int 8, int 16, int 32, int 64

floating

float, double, real

array

fix array , array 16, array 32

map

fix map , map 16, map 32

raw

fix raw , raw 16, raw 32

union Via ;

msgpack value representation

bool boolean ;

corresponding to Type. boolean

ulong uinteger ;

corresponding to Type.unsigned

long integer ;

corresponding to Type.signed

real floating ;

corresponding to Type. floating

Value[] array ;

corresponding to Type. array

Value[Value] map ;

corresponding to Type. map

ubyte[] raw ;

corresponding to Type. raw

Type type ;

represents value type

Via via ;

represents real value

this(Type type = Type.nil);
this(bool value, Type type = Type.boolean);
this(ulong value, Type type = Type.unsigned);
this(long value, Type type = Type.signed);
this(real value, Type type = Type.floating);
this(Value[] value, Type type = Type.array);
this(Value[Value] value, Type type = Type.map);
this(ubyte[] value, Type type = Type.raw);

Constructs a Value with arguments.

Params:

value	the real content.
Type type	the type of value.

this(string value, Type type = Type.raw);

This is unsafe overload because using cast internally.

T as (T)() if (is(Unqual!T == bool));
T as (T)() if (isIntegral!T && !is(Unqual!T == enum));
T as (T)() if (isFloatingPoint!T && !is(Unqual!T == enum));
T as (T)() if (is(Unqual!T == enum));
T as (T)() if (isArray!T && !is(Unqual!T == enum));
T as (T)() if (isAssociativeArray!T);

Converts value to T type.

Returns:
converted value.

Throws:
MessagePackException if type is mismatched.

NOTE:
Current implementation uses cast.

T as (T, Args...)(Args args) if (is(Unqual!T == class));
T as (T)() if (is(Unqual!T == struct));

Converts to T type.

Calling fromMsgpack if class and struct implement fromMsgpack method. fromMsgpack signature is:

void fromMsgpack(Value value)

This method assigns converted values to all members of T object if class and struct don't implement fromMsgpack .

Params:

Args args

arguments to class constructor(class only).

Returns:
converted value.

const void toMsgpack (Packer)(ref Packer packer);

Special method called by Packer .

Params:

Packer packer

a MessagePack serializer.

const bool opEquals (Tdummy = void)(ref const Value other);
const bool opEquals (T : bool)(in T other);
const bool opEquals (T : ulong)(in T other);
const bool opEquals (T : real)(in T other);
const bool opEquals (T : const(Value[]))(in T other);
const bool opEquals (T : const(Value[Value]))(in T other);
const bool opEquals (T : const(ubyte)[])(in T other);
const bool opEquals (T : string)(in T other);

Comparison for equality. @trusted for union.

struct Unpacked ;

Unpacked is a Range wrapper for stream deserialization result

Value value ;

deserialized value

this(ref Value value);

Constructs a Unpacked with argument.

Params:

Value value

a deserialized value.

const nothrow @property @trusted bool empty ();

InputRange primitive operation that checks iteration state.

Returns:
true if there are no more elements to be iterated.

@property @trusted size_t length ();

Range primitive operation that returns the length of the range.

Returns:
the number of values.

@property ref @trusted Value front ();

InputRange primitive operation that returns the currently iterated element.

Returns:
the deserialized Value .

@trusted void popFront ();

InputRange primitive operation that advances the range to its next element.

nothrow ref @trusted Value opIndex (size_t n);

RandomAccessRange primitive operation.

Returns:
the deserialized Value at n position.

@trusted Value[] opSlice (size_t from, size_t to);

Returns a slice of the range.

Paramas:
from = the start point of slicing. to = the end point of slicing.

Returns:
the slice of Values.

@property @safe Unpacked save ();

Range primitive operation that returns the snapshot.

Returns:
the snapshot of this Value.

struct StreamingUnpacker ;

This StreamingUnpacker is a MessagePack streaming deserializer

This implementation enables you to load multiple objects from a stream(like network).

Example:

...
auto unpacker = StreamingUnpacker(serializedData);
...

// appends new data to buffer if pre execute() call didn't finish deserialization.
unpacker.feed(newSerializedData);

while (unpacker.execute()) {
    foreach (obj; unpacker.purge()) {
        // do stuff (obj is a Value)
    }
}

if (unpacker.size)
    throw new Exception("Message is too large");

this(in ubyte[] target, in size_t bufferSize = 8192);

Constructs a StreamingUnpacker .

Params:

ubyte[] target	byte buffer to deserialize
size_t bufferSize	size limit of buffer size

@property @safe Unpacked unpacked ();

Forwards to deserialized object.

Returns:
the Unpacked object contains deserialized value.

nothrow @safe void clear ();

Clears some states for next deserialization.

@safe Unpacked purge ();

Convenient method for unpacking and clearing states.

Example:

foreach (obj; unpacker.purge()) {
    // do stuff
}

is equivalent to

foreach (obj; unpacker.unpacked) {
    // do stuff
}
unpacker.clear();

Returns:
the Unpacked object contains deserialized value.

@trusted bool execute ();

Executes deserialization.

Returns:
true if deserialization has been completed, otherwise false.

Throws:
UnpackException when parse error occurs.

@trusted int opApply (scope int delegate(ref Unpacked) dg);

supports foreach. One loop provides Unpacked object contains execute() result. This is convenient in case that MessagePack values are continuous.