Версия:

Модуль json

Модуль json

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

Модуль json определяет процедуры работы с форматом JSON. Он создан на основе модуля Lua-CJSON от Mark Pulford. Полное руководство по Lua-CJSON включено в официальную документацию.

Указатель

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

Имя Назначение
json.encode() Конвертация Lua-объекта в JSON-строку
json.decode() Конвертация JSON-строки в Lua-объект
json.NULL Аналог «nil» в языке Lua
json.cfg() Определение глобальных флагов
json.encode(lua-value[, configuration])

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

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

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

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

строка

Пример:

tarantool> json=require('json')
---
...
tarantool> json.encode(123)
---
- '123'
...
tarantool> json.encode({123})
---
- '[123]'
...
tarantool> json.encode({123, 234, 345})
---
- '[123,234,345]'
...
tarantool> json.encode({abc = 234, cde = 345})
---
- '{"cde":345,"abc":234}'
...
tarantool> json.encode({hello = {'world'}})
---
- '{"hello":["world"]}'
...
json.decode(string[, configuration])

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

Параметры:
  • string (string) – строка в формате JSON.
  • configuration – see json.cfg
возвращает:

оригинальное содержание в формате Lua-таблицы.

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

таблица

Пример:

tarantool> json = require('json')
---
...
tarantool> json.decode('123')
---
- 123
...
tarantool> json.decode('[123, "hello"]')
---
- [123, 'hello']
...
tarantool> json.decode('{"hello": "world"}').hello
---
- world
...

Чтобы увидеть применение json.decode() в приложении, см. практическое задание Подсчет суммы по JSON-полям во всех кортежах.

json.NULL

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

Пример:

-- Когда полю Lua-таблицы присваивается nil, это поле -- null
tarantool> {nil, 'a', 'b'}
---
- - null
  - a
  - b
...
-- Когда полю Lua-таблицы присваивается json.NULL, это поле --  json.NULL
tarantool> {json.NULL, 'a', 'b'}
---
- - null
  - a
  - b
...
-- Когда JSON-полю присваивается json.NULL, это поле -- null
tarantool> json.encode({field2 = json.NULL, field1 = 'a', field3 = 'c'})
---
- '{"field2":null,"field1":"a","field3":"c"}'
...

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

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

Сериализация „A“ и“ B“ различными значениями __serialize приводит к различным результатам:

tarantool> json.encode(setmetatable({'A', 'B'}, { __serialize="seq"}))
---
- '["A","B"]'
...
tarantool> json.encode(setmetatable({'A', 'B'}, { __serialize="map"}))
---
- '{"1":"A","2":"B"}'
...
tarantool> json.encode({setmetatable({f1 = 'A', f2 = 'B'}, { __serialize="map"})})
---
- '[{"f2":"B","f1":"A"}]'
...
tarantool> json.encode({setmetatable({f1 = 'A', f2 = 'B'}, { __serialize="seq"})})
---
- '[[]]'
...
json.cfg(list of parameter assignments)

Определяет значения, которые влияют на поведение json.encode и json.decode.

Задаются либо все целочисленные значения, либо все логические значения true/false (правда/ложь).

  • cfg.encode_deep_as_nil ((по умолчанию, false) – см. ниже
  • cfg.encode_invalid_as_nil (по умолчанию, false) – использовать null для всех нераспознаваемых типов
  • cfg.encode_invalid_numbers (по умолчанию, true) – разрешить nan и inf
  • cfg.encode_load_metatables (по умолчанию, false) – загрузить метатаблицы
  • cfg.encode_max_depth (по умолчанию, 32) – максимальная глубина вложенности в структуре
  • cfg.encode_number_precision (по умолчанию, 14) – максимальное количество цифр в дробной части
  • cfg.encode_sparse_convert (по умолчанию, true) – обрабатывать излишне разреженные массивы как ассоциативные массивы
  • cfg.encode_sparse_ratio (по умолчанию, 2) – допустимая разреженность массива
  • cfg.encode_sparse_safe (по умолчанию, 10) – безопасная разреженность массивы
  • cfg.encode_use_tostring (по умолчанию, false) – использовать tostring для нераспознаваемых типов
  • cfg.decode_invalid_numbers (по умолчанию, true) – разрешить nan и inf
  • cfg.decode_max_depth (по умолчанию, 32) – максимальная глубина вложенности в структуре
  • cfg.decode_save_metatables (по умолчанию, true) – как encode_load_metatables

Например, следующий код интерпретирует 0/0 как nan («не является числом»), а 1/0 – как inf («бесконечность»), вместо того, чтобы вернуть nil или ошибку:

json = require('json')
json.cfg{encode_invalid_numbers = true}
x = 0/0
y = 1/0
json.encode({1, x, y, 2})

Результат запроса json.encode() будет следующим:

tarantool> json.encode({1, x, y, 2})
---
- '[1,nan,inf,2]
...

Чтобы получить такой же эффект для одиночного вызова json.encode() без постоянного изменения конфигурации, можно вызвать json.encode({1, x, y, 2}, {encode_invalid_numbers = true}).

Такие параметры конфигурации применяются для формата JSON, для MsgPack и для YAML.

Примечание

Поведение изменилось: До версии 1.10.4 Tarantool’а, если глубина вложения структуры была больше, чем cfg.encode_max_depth, более глубокие уровни обрезаются (кодируются как nil).

Теперь результатом станет ошибка с указанием недостаточной глубины cfg.encode_max_depth. Чтобы вернуть старое поведение системы, выполните cfg.encode_deep_as_nil = true.

Этот параметр не учитывается для YAML.