lua-MessagePack
a pure Lua implementation

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', 'float' and 'integer'. The default is usually 'double'.

set_integer( str )

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

set_array( str )

Configures the behaviour of pack. The valid options are 'without_hole' and 'with_hole'. 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 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 positive integers greater than 1, 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.
  • 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

Examples

local mp = require 'MessagePack'

mp.set_number'float'
mp.set_integer'unsigned'
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