Module json

Module json

Overview

The json module provides JSON manipulation routines. It is based on the Lua-CJSON module by Mark Pulford. For a complete manual on Lua-CJSON please read the official documentation.

Index

Below is a list of all json functions and members.

Name Use
json.encode() Convert a Lua object to a JSON string
json.decode() Convert a JSON string to a Lua object
json.NULL Analog of Lua’s “nil”
json.cfg() Set global flags
json.encode(lua-value[, configuration])

Convert a Lua object to a JSON string.

Parameters:
  • lua_value – either a scalar value or a Lua table value.
  • configuration – see json.cfg
Return:

the original value reformatted as a JSON string.

Rtype:

string

Example:

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

Convert a JSON string to a Lua object.

Parameters:
  • string (string) – a string formatted as JSON.
  • configuration – see json.cfg
Return:

the original contents formatted as a Lua table.

Rtype:

table

Example:

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

See the tutorial Sum a JSON field for all tuples to see how json.decode() can fit in an application.

json.NULL

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

Example:

-- 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" for an array
  • __serialize="map" for a 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"})})
---
- '[[]]'
...
json.cfg(list of parameter assignments)

Set values affecting behavior of json.encode and json.decode.

The values are all either integers or boolean true/false values.

  • cfg.encode_deep_as_nil (default is false) – see below
  • cfg.encode_invalid_as_nil (default is false) – use null for all unrecognizable types
  • cfg.encode_invalid_numbers (default is true) – allow nan and inf
  • cfg.encode_load_metatables (default is false) – load metatables
  • cfg.encode_max_depth (default is 32) – maximum nesting depth in a structure
  • cfg.encode_number_precision (default is 14) – maximum post-decimal digits
  • cfg.encode_sparse_convert (default is true) – handle excessively sparse arrays as maps
  • cfg.encode_sparse_ratio (default is 2) – how sparse an array can be
  • cfg.encode_sparse_safe (default is 10) – how much can safely be sparse
  • cfg.encode_use_tostring (default is false) – use tostring for unrecognizable types
  • cfg.decode_invalid_numbers (default is true) – allow nan and inf
  • cfg.decode_load_metatables (default is false) – load metatables
  • cfg.decode_max_depth (default is 32) – maximum nesting depth in a structure
  • cfg.decode_save_metatables (default is true) – like encode_load_metatables
  • cfg.decode_sparse_convert (default is true) – like encode_sparse_convert
  • cfg.decode_use_tostring (default is false) – use tostring for unrecognizable types

For example, the following code will encode 0/0 as nan (“not a number”) and 1/0 as inf (“infinity”), rather than returning nil or an error message:

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

To achieve the same effect for only one call to json.encode() without changing the configuration persistently, one could say json.encode({1, x, y, 2}, {encode_invalid_numbers = true}).

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

Note

Behavior change: Before Tarantool version 1.10.4, if a nested structure was deeper than cfg.encode_max_depth, the deeper levels were cropped (encoded as nil).

Now, the result is an error suggesting that cfg.encode_max_depth is not deep enough. To return to the old behavior, say cfg.encode_deep_as_nil = true.

This option is ignored for YAML.