msgpack-d 1.0.5

MessagePack for D.


To use this package, run the following command in your project's root directory:

Manual usage
Put the following dependency into your project's dependences section:

CI

MessagePack for D

MessagePack is a binary-based JSON-like serialization library.

MessagePack for D is a pure D implementation of MessagePack.

Features

  • Small size and High performance
  • Zero copy serialization / deserialization
  • Streaming deserializer for non-contiguous IO situation
  • Supports D features (Ranges, Tuples, real type)

Note: The real type is only supported in D. Don't use the real type when communicating with other programming languages. Note that Unpacker will raise an exception if a loss of precision occurs.

Current Limitations

  • No circular references support
  • If you want to use the LDC compiler, you need at least version 0.15.2 beta2

Install

Use dub to add it as a dependency:

% dub install msgpack-d

Usage

Example code can be found in the example directory.

The documentation can be found here

pack / unpack

msgpack-d is very simple to use. Use pack for serialization, and unpack for deserialization:

import std.file;
import msgpack;

struct S { int x; float y; string z; }

void main()
{
    S input = S(10, 25.5, "message");

    // serialize data
    ubyte[] inData = pack(input);

    // write data to a file
    write("file.dat", inData);

    // read data from a file
    ubyte[] outData = cast(ubyte[])read("file.dat");

    // unserialize the data
    S target = outData.unpack!S();

    // verify data is the same
    assert(target.x == input.x);
    assert(target.y == input.y);
    assert(target.z == input.z);
}

Feature: Skip serialization/deserialization of a specific field.

Use the @nonPacked attribute:

struct User
{
    string name;
    @nonPacked int level;  // pack / unpack will ignore the 'level' field
}

Feature: Use your own serialization/deserialization routines for custom class and struct types.

msgpack-d provides the functions registerPackHandler / registerUnpackHandler to allow you to use custom routines during the serialization or deserialization of user-defined class and struct types. This feature is especially useful when serializing a derived class object when that object is statically typed as a base class object.

For example:

class Document { }
class XmlDocument : Document
{
    this() { }
    this(string name) { this.name = name; }
    string name;
}

void xmlPackHandler(ref Packer p, ref XmlDocument xml)
{
    p.pack(xml.name);
}

void xmlUnpackHandler(ref Unpacker u, ref XmlDocument xml)
{
    u.unpack(xml.name);
}

void main()
{
    /// Register the 'xmlPackHandler' and 'xmlUnpackHandler' routines for
    /// XmlDocument object instances.
    registerPackHandler!(XmlDocument, xmlPackHandler);
    registerUnpackHandler!(XmlDocument, xmlUnpackHandler);

    /// Now we can serialize/deserialize XmlDocument object instances via a
    /// base class reference.
    Document doc = new XmlDocument("test.xml");
    auto data = pack(doc);
    XmlDocument xml = unpack!XmlDocument(data);
    assert(xml.name == "test.xml");  // xml.name is "test.xml"
}

In addition, here is also a method using @serializedAs attribute:

import std.datetime: Clock, SysTime;
static struct SysTimePackProxy
{
    static void serialize(ref Packer p, ref in SysTime tim)
    {
        p.pack(tim.toISOExtString());
    }

    static void deserialize(ref Unpacker u, ref SysTime tim)
    {
        string tmp;
        u.unpack(tmp);
        tim = SysTime.fromISOExtString(tmp);
    }
}
static struct LogData
{
    string msg;
    string file;
    ulong  line;
    @serializedAs!SysTimePackProxy SysTime timestamp;

    this(string message, string file = __FILE__, ulong line = __LINE__)
    {
        this.msg = message;
        this.file = file;
        this.line = line;
        this.timestamp = Clock.currTime();
    }
}

void main()
{
    /// Now we can serialize/deserialize LogData
    LogData[] logs;
    logs ~= LogData("MessagePack is nice!");
    auto data = pack(logs);
    LogData[] datas = unpack!(LogData[])(data);
    assert(datas[0].timestamp.toString() == datas[0].timestamp.toString());
}

The PackerImpl / Unpacker / StreamingUnpacker types

These types are used by the pack and unpack functions.

See the documentation of PackerImpl, Unpacker and StreamingUnpacker for more details.

The official MessagePack protocol website.

Use this issue tracker to review and file bugs in msgpack-d.

Other language bindings and implementations of the msgpack protocol can be found here.

Copyright (c) 2010- Masahiro Nakagawa

License

Distributed under the Boost Software License, Version 1.0.

Authors:
  • Masahiro Nakagawa
Dependencies:
none
Versions:
1.0.5 2023-Mar-18
1.0.4 2022-Jun-12
1.0.3 2020-May-18
1.0.2 2019-Nov-11
1.0.1 2019-Jul-23
Show all 26 versions
Download Stats:
  • 16 downloads today

  • 182 downloads this week

  • 753 downloads this month

  • 249960 downloads total

Score:
4.8
Short URL:
msgpack-d.dub.pm