Версия:

Модуль json

Модуль json

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

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

Индекс

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

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

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

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

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

Rtype:

string

Пример:

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)

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

Параметры:
  • string (string) – строка в формате JSON.
Возврат:

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

Rtype:

таблица

Пример:

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

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

Пример:

-- When nil is assigned to a Lua-table field, the field is null
tarantool> {nil, 'a', 'b'}
---
- - null
  - a
  - b
...
-- When json.NULL is assigned to a Lua-table field, the field is json.NULL
tarantool> {json.NULL, 'a', 'b'}
---
- - null
  - a
  - b
...
-- When json.NULL is assigned to a JSON field, the field is null
tarantool> json.encode({field2 = json.NULL, field1 = 'a', field3 = 'c'})
---
- '{"field2":null,"field1":"a","field3":"c"}'
...

The JSON output structure can be specified with __serialize:

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

Serializing „A“ and „B“ with different __serialize values causes different results:

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"})})
   ---
   - '[[]]'
   ...

Параметры конфигурации

There are configuration settings which affect the way that Tarantool encodes invalid numbers or types. They are all boolean true/false values

  • cfg.encode_invalid_numbers (default is true) – allow nan and inf
  • cfg.encode_use_tostring (default is false) – use tostring for unrecognizable types
  • cfg.encode_invalid_as_nil (default is false) – use null for all unrecognizable types
  • cfg.encode_load_metatables (default is false) – load metatables

For example, the following code will interpret 0/0 (which is «not a number») and 1/0 (which is «infinity») as special values rather than nulls or errors:

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

The result of the json.encode() request will look like this:

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

The same configuration settings exist for json, for MsgPack, and for YAML.