msgpack

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

 auto serialized = pack(data);

 // ...

 typeof(data) deserialized;

 unpack(serialized, deserialized);

 assert(data == deserialized);

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);

@safe this(const(ulong) threshold, const(ulong) chunkSize = cast(const(ulong))8192);

Constructs a buffer.

Params:

const(ulong) threshold	the threshold of writing value or stores reference.
const(ulong) 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 MessagePackException : object.Exception;

MessagePackException is a root Exception for MessagePack related operation.

struct Packer (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 a field name at class or struct

Stream stream ();

Forwards to stream .

Returns:
the stream .

Packer pack (T)(in T value);
Packer pack (T)(in T value);
Packer pack (T)(in T value);
Packer pack (T)(in T value);
Packer pack (T)(in T value);

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:

value

the content to serialize.

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

Packer pack (T)(in T value);
Packer pack (T)(in T value);
Packer pack (T)(in T array);
Packer pack (T)(in T array);
Packer pack (Types...)(auto ref const Types objects);

Overload for pack (null) for 2.057 or later

Packer pack (T)(in T object);
Packer pack (T)(auto ref T object);

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:

object

the content to serialize.

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

Packer packArray (Types...)(auto ref const Types objects);
Packer 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:

objects

the contents to serialize.

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

Packer beginArray (in size_t length);
Packer 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.

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

Helper for Packer construction.

Params:

stream

the stream to write.

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

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.

@safe this(const(ubyte[]) target, const(ulong) bufferSize = cast(const(ulong))8192);

Constructs a Unpacker .

Params:

const(ubyte[]) target	byte buffer to deserialize
const(ulong) bufferSize	size limit of buffer size

nothrow @safe void clear ();

Clears states for next deserialization.

Unpacker unpack (T)(ref T value);
Unpacker unpack (T)(ref T value);
Unpacker unpack (T)(ref T value);
Unpacker unpack (T)(ref T value);
Unpacker unpack (T)(ref T value);
Unpacker unpack (T)(T value);
Unpacker unpack (Types...)(ref Types objects);

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:

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);
Unpacker unpack (T)(ref T array);

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:

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);
Unpacker unpack (T)(ref T object);

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:

object	the reference of object to assign.
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:

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"...

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 ;

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

@safe this(Type type = cast(Type)0);
@trusted this(bool value, Type type = cast(Type)1);
@trusted this(ulong value, Type type = cast(Type)2);
@trusted this(long value, Type type = cast(Type)3);
@trusted this(real value, Type type = cast(Type)4);
@trusted this(Value[] value, Type type = cast(Type)5);
@trusted this(Value[Value] value, Type type = cast(Type)6);
@trusted this(ubyte[] value, Type type = cast(Type)7);

Constructs a Value with arguments.

Params:

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

T as (T)();
T as (T)();
T as (T)();
T as (T)();
T as (T)();
T as (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);
T as (T)();

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	arguments to class constructor(class only).

Returns:
converted value.

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

Special method called by Packer .

Params:

packer

a MessagePack serializer.

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

Comparison for equality. @trusted for union.

struct Unpacked ;

Unpacked is a Range wrapper for stream deserialization result

Value value ;

deserialized value

@safe 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");

@safe this(const(ubyte[]) target, const(ulong) bufferSize = cast(const(ulong))8192);

Constructs a StreamingUnpacker .

Params:

const(ubyte[]) target	byte buffer to deserialize
const(ulong) 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.

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	the contents to serialize.

Returns:
a serialized data.

Unpacked unpack (Tdummy = void)(in ubyte[] buffer);

Deserializes buffer using stream deserializer.

Params:

buffer

the buffer to deserialize.

Returns:
a Unpacked contains deserialized object.

Throws:
UnpackException if deserialization doesn't succeed.

void unpack (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:

buffer	the buffer to deserialize.
args	the references of values to assign.

template MessagePackable (Members...)

Handy helper for creating MessagePackable object.

toMsgpack / fromMsgpack are special methods for serialization / deserialization. This template provides those methods to struct/class.

Example:

 struct S
 {
     int num; string str;

     // http://d.puremagic.com/issues/show_bug.cgi?id = 1099
     mixin MessagePackable;  // all members
     // mixin MessagePackable!("num");  // num only
 }

Defines those methods manually if you treat complex data-structure.

const void toMsgpack (Packer)(ref Packer packer, bool withFieldName = false);

Serializes members using packer.

Params:

packer

the serializer to pack.

void fromMsgpack (Value value);

Deserializes MessagePack object to members using Value.

Params:

Value value

the MessagePack value to unpack.

Throws:
MessagePackException if value is not an Array type.

void fromMsgpack (ref Unpacker unpacker);

Deserializes MessagePack object to members using direct-conversion deserializer.

Params:

value

the reference to direct-conversion deserializer.

Throws:
MessagePackException if the size of deserialized value is mismatched.