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 )
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
andtable
. - A Lua
number
is converted into aninteger
ifmath.floor(num) == num
, otherwise it is converted into the MessagePackfloat
ordouble
(seeset_number
). - When a MessagePack 64 bits
integer
is converted to a Luanumber
it is possible that the resulting number will not represent the original number but just an approximation. - A Lua
table
is converted into a MessagePackarray
only if all the keys are composed of positive integers greater than 1, without hole or with holes (seeset_array
). Otherwise it is converted into MessagePackmap
. - An empty
table
is always converted into a MessagePackarray
. - With
set_array'always_as_map'
, all Luatable
are converted into a MessagePackmap
. - Lua does not allow
nil
and NaN (0/0
) astable
index, by default, the deserialization of this kind of MessagePackmap
skips the key/value pair. The value could preserved by defining the module membersentinel
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