Модуль msgpack¶

Общие сведения¶

The msgpack module takes strings in MsgPack format and decodes them, or takes a series of non-MsgPack values and encodes them. Tarantool makes heavy internal use of MsgPack because tuples in Tarantool are stored as MsgPack arrays.

Индекс¶

Below is a list of all msgpack functions and members.

msgpack.encode(lua_value)¶

Convert a Lua object to a MsgPack string.

Параметры:	lua_value – either a scalar value or a Lua table value.
Return:	the original value reformatted as a MsgPack string.
Rtype:	string

msgpack.decode(msgpack_string[, start_position])¶

Convert a MsgPack string to a Lua object.

Параметры:	msgpack_string (string) – a string formatted as MsgPack. start_position (integer) – where to start, minimum = 1, maximum = string length, default = 1.
Return:	(if msgpack_string is in valid MsgPack format) the original contents of msgpack_string, formatted as a Lua table, (otherwise) a scalar value, such as a string or a number; «next_start_position». If decode stops after parsing as far as byte N in msgpack_string, then «next_start_position» will equal N + 1, and decode(msgpack_string, next_start_position) will continue parsing from where the previous decode stopped, plus 1. Normally decode parses all of msgpack_string, so «next_start_position» will equal string.len(msgpack_string) + 1.
Rtype:	table and number

msgpack.decode_unchecked(string)¶

Convert a MsgPack string to a Lua object. Because checking is skipped, decode_unchecked() can operate with string pointers to buffers which decode() cannot handle. For an example see the buffer module.

Параметры:	string – a string formatted as MsgPack.
Return:	the original contents formatted as a Lua table; the number of bytes that were decoded.
Rtype:	lua object

msgpack.NULL¶

A value comparable to Lua «nil» which may be useful as a placeholder in a tuple.

Пример¶

tarantool> msgpack = require('msgpack')
---
...
tarantool> y = msgpack.encode({'a',1,'b',2})
---
...
tarantool> z = msgpack.decode(y)
---
...
tarantool> z[1], z[2], z[3], z[4]
---
- a
- 1
- b
- 2
...
tarantool> box.space.tester:insert{20, msgpack.NULL, 20}
---
- [20, null, 20]
...

The MsgPack output structure can be specified with __serialize:

• __serialize = "seq" or "sequence" for an array
• __serialize = "map" or "mapping" for a map

Serializing „A“ and „B“ with different __serialize values causes different results. To show this, here is a routine which encodes {„A“,“B“} both as an array and as a map, then displays each result in hexadecimal.

function hexdump(bytes)
    local result = ''
    for i = 1, #bytes do
        result = result .. string.format("%x", string.byte(bytes, i)) .. ' '
    end
    return result
end

msgpack = require('msgpack')
m1 = msgpack.encode(setmetatable({'A', 'B'}, {
                             __serialize = "seq"
                          }))
m2 = msgpack.encode(setmetatable({'A', 'B'}, {
                             __serialize = "map"
                          }))
print('array encoding: ', hexdump(m1))
print('map encoding: ', hexdump(m2))

Result:

array encoding: 92 a1 41 a1 42
map encoding:   82 01 a1 41 02 a1 42

The MsgPack Specification page explains that the first encoding means:

fixarray(2), fixstr(1), "A", fixstr(1), "B"

and the second encoding means:

fixmap(2), key(1), fixstr(1), "A", key(2), fixstr(2), "B"

Here are examples for all the common types, with the Lua-table representation on the left, with the MsgPack format name and encoding on the right.

Also, some MsgPack configuration settings for encoding can be changed, in the same way that they can be changed for JSON.