MessagePack

---

Reference

pack( data )

Serialize a data.

unpack( str )

Deserialize a string.

unpacker( src )

Accept a string or a ltn12.source and returns a iterator.

The iterator gives a couple of values, the interesting value is the second.

set_number( str )

Configures the behaviour of pack. The valid options are 'double' and 'float'. The default is usually 'double'.

set_integer( str ) DEPRECATED

Configures the behaviour of pack. The valid options are 'signed' and 'unsigned'. The default is 'unsigned'.

set_array( str )

Configures the behaviour of pack. The valid options are 'without_hole', 'with_hole' and 'always_as_map'. The default is 'without_hole'.

set_string( str )

Configures the behaviour of pack. The valid options are 'string', 'string_compat' and 'binary'. The default is 'string_compat' in order to be compatible with old implementation.

Data Conversion

• The following Lua types could be converted : nil, boolean, number, string and table.
• A Lua number is converted into an MessagePack integer if math.floor(num) == num, otherwise it is converted into the MessagePack float or double (see set_number).
• When a MessagePack 64 bits integer is converted to a Lua number it is possible that the resulting number will not represent the original number but just an approximation.
• A Lua table is converted into a MessagePack array only if all the keys are composed of strictly positive integers, without hole or with holes (see set_array). Otherwise it is converted into MessagePack map.
• An empty table is always converted into a MessagePack array.
• With set_array'always_as_map', all Lua table are converted into a MessagePack map.
• Lua does not allow nil and NaN (0/0) as table index, by default, the deserialization of this kind of MessagePack map skips the key/value pair. The value could preserved by defining the module member sentinel which is used as key.
• LIMITATION : MessagePack cannot handle data with cyclic reference.

Extensions

There are introduced with MessagePack specification v5.

During deserialization, unknown extensions are skipped and evaluated as a Lua nil.

The following example shows how to create a new module which extends MessagePack with the serialization/deserialization of Lua function (obviously, the emitter and receiver MUST use the same version of Lua).

local loadstring = loadstring or load
local mp = require 'MessagePack'
local EXT_FUNCTION = 7

mp.packers['function'] = function (buffer, fct)
    mp.packers['ext'](buffer, EXT_FUNCTION, assert(string.dump(fct)))
end

mp.build_ext = function (tag, data)
    if tag == EXT_FUNCTION then
        return assert(loadstring(data))
    end
end

return mp

Advanced usages

The following Lua hack allows to have several instances of the module MessagePack, each one with its own settings.

local mp1 = require 'MessagePack'
package.loaded['MessagePack'] = nil     -- the hack is here
local mp2 = require 'MessagePack'

mp1.set_array'without_hole'
mp2.set_array'always_as_map'

When global settings are not enough, the following recipe allows to use a specific encoding for only a part of a data structure.

local mp = require 'MessagePack'
mp.packers['function'] = function (buffer, fct)
    fct(buffer)
end

local function BINARY (str)
    return function (buffer)
        mp.packers['binary'](buffer, str)
    end
end

local function FLOAT (n)
    return function (buffer)
        mp.packers['float'](buffer, n)
    end
end

mp.pack { 'encoded_with_global_settings', BINARY'encoded_as_binary', 42, FLOAT(42) }

Examples

Basic usage

local mp = require 'MessagePack'

mp.set_number'float'
mp.set_array'with_hole'
mp.set_string'string'

mpac = mp.pack(data)
data = mp.unpack(mpac)

local ltn12 = require 'ltn12'
src = ltn12.source.file(io.open('file', 'r'))
for _, v in mp.unpacker(src) do
    print(v)
end