Версия:

Модуль msgpack

Модуль msgpack

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

Модуль msgpack берет строки в формате MsgPack и декодирует их или берет ряд значений в ином формате и кодирует их в формат MsgPack. MsgPack интенсивно используется в Tarantool’е, поскольку кортежи хранятся в виде массивов в формате MsgPack.

Индекс

Ниже приведен перечень всех функций и элементов модуля msgpack.

Имя Использование
msgpack.encode() Конвертация Lua-объекта в MsgPack-строку
msgpack.decode() Конвертация MsgPack-строки в Lua-объект
msgpack.decode_unchecked() Конвертация MsgPack-строки в Lua-объект
msgpack.NULL Аналог «nil» в языке Lua
msgpack.encode(lua_value)

Конвертация Lua-объекта в MsgPack-строку.

Параметры:
  • lua_value – скалярное значение или значение из Lua-таблицы.
возвращается:

оригинальное значение, преобразованное в MsgPack-строку.

тип возвращаемого значения:
 

string (строка)

msgpack.decode(msgpack_string[, start_position])

Конвертация MsgPack-строки в Lua-объект.

Параметры:
  • msgpack_string (string) – строка в формате MsgPack.
  • start_position (integer) – where to start, minimum = 1, maximum = string length, default = 1.
возвращается:
  • (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.
тип возвращаемого значения:
 

table and number

msgpack.decode_unchecked(string)

Конвертация MsgPack-строки в Lua-объект. Поскольку проверка не проводится, decode_unchecked() может работать с указателями строки в буфере в отличие от decode(). Пример см. в модуле buffer.

Параметры:
  • string – строка в формате MsgPack.
возвращается:
  • оригинальное содержание в формате Lua-таблицы;
  • количество декодированных байтов.
тип возвращаемого значения:
 

Lua-объект.

msgpack.NULL

Значение, сопоставимое с нулевым значением «nil» в языке Lua, которое можно использовать в качестве объекта-заполнителя в кортеже.

Пример

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]
 ...

Структуру MsgPack-вывода можно указать с помощью __serialize:

  • __serialize = "seq" или "sequence" для массива
  • __serialize = "map" или "mapping" для ассоциативного массива

Сериализация „A“ и“ B“ различными значениями __serialize приводит к различным результатам. Чтобы показать различия, ниже приведена процедура кодирования {„A“,“B“} в массив и в ассоциативный массив с выводом каждого результата в виде шестнадцатеричного числа.

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))

Результат:

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

На странице спецификации MsgPack по ссылке Specification объясняется, что значение первого результата кодирования:

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

а значение второго результата кодирования:

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

Ниже приведены примеры всех стандартных типов: слева отображение в Lua-таблице, а справа – имя и кодировка в формате MsgPack.

Стандартные типы в MsgPack-кодировке

{} „fixmap“ = 80, если метатаблица – ассоциативный массив „map“, в противном случае, „fixarray“ = 90
„a“ „fixstr“ = a1 61
false (ложь) „false“ = c2
true „true“ = c3
127 „positive fixint“ = 7f
65535 „uint 16“ = cd ff ff
4294967295 „uint 32“ = ce ff ff ff ff
nil „nil“ = c0
msgpack.NULL то же, что и nil
[0] = 5 „fixmap(1)“ + „positive fixint“ (для ключа) + „positive fixint“ (для значения) = 81 00 05
[0] = nil „fixmap(0)“ = 80 – nil не хранится, если это отсутствующее значение ассоциативного массива
1,5 „float 64“ = cb 3f f8 00 00 00 00 00 00

Кроме того, некоторые параметры конфигурации MsgPack для кодировки можно изменить так же, как и для JSON.