jansson

jansson#

local JSON = require 'jansson'

The jansson Module provides JSON parsing, manipulation, and serialization. It is a thin wrapper of the Jansson library.

Functions#

jansson.loads(jsonstring[, flags])#

Load JSON from a string.

Parameters:

  • jsonstring (string) – String to parse.

  • flags (integer) – (Optional) Load flags, see below.

Returns:

A parsed JSON

Return type:

jansson.json

Load Flags

jansson.JSON_REJECT_DUPLICATES#

Issue a decoding error if any JSON object in the input text contains duplicate keys. Without this flag, the value of the last occurrence of each key ends up in the result. Key equivalence is checked byte-by-byte, without special Unicode comparison algorithms.

jansson.JSON_DECODE_ANY#

By default, the decoder expects an array or object as the input. With this flag enabled, the decoder accepts any valid JSON value.

jansson.JSON_DISABLE_EOF_CHECK#

By default, the decoder expects that its whole input constitutes a valid JSON text, and issues an error if there’s extra data after the otherwise valid JSON input. With this flag enabled, the decoder stops after decoding a valid JSON array or object, and thus allows extra data after the JSON text.

jansson.JSON_DECODE_INT_AS_REAL#

JSON defines only one number type. Jansson distinguishes between ints and reals. For more information see Real vs. Integer. With this flag enabled the decoder interprets all numbers as real values. Integers that do not have an exact double representation will silently result in a loss of precision. Integers that cause a double overflow will cause an error.

jansson.JSON_ALLOW_NUL#
Example#
local jsonstr = [[
{
    "Key": "value",
    "anotherKey": 1234
}
]]

-- with no flags
local data = JSON.loads(jsonstr)

-- with flags
local data = JSON.loads(jsonstr, JSON.JSON_REJECT_DUPLICATES | JSON.JSON_DECODE_INT_AS_REAL)

Version History

Version

Notes

0.0.1

Added
jansson.loadfile(filename[, flags])#

Load JSON from a string.

Parameters:

  • filename (string)

  • flags (integer) – (Optional) Load flags, see below.

Returns:

A parsed JSON

Return type:

jansson.json

Load Flags

jansson.JSON_REJECT_DUPLICATES

Issue a decoding error if any JSON object in the input text contains duplicate keys. Without this flag, the value of the last occurrence of each key ends up in the result. Key equivalence is checked byte-by-byte, without special Unicode comparison algorithms.

jansson.JSON_DECODE_ANY

By default, the decoder expects an array or object as the input. With this flag enabled, the decoder accepts any valid JSON value.

jansson.JSON_DISABLE_EOF_CHECK

By default, the decoder expects that its whole input constitutes a valid JSON text, and issues an error if there’s extra data after the otherwise valid JSON input. With this flag enabled, the decoder stops after decoding a valid JSON array or object, and thus allows extra data after the JSON text.

jansson.JSON_DECODE_INT_AS_REAL

JSON defines only one number type. Jansson distinguishes between ints and reals. For more information see Real vs. Integer. With this flag enabled the decoder interprets all numbers as real values. Integers that do not have an exact double representation will silently result in a loss of precision. Integers that cause a double overflow will cause an error.

jansson.JSON_ALLOW_NUL
Example#
local jsonstr = [[
{
    "Key": "value",
    "anotherKey": 1234
}
]]

-- with no flags
local data = JSON.loads(jsonstr)

-- with flags
local data = JSON.loads(jsonstr, JSON.JSON_REJECT_DUPLICATES | JSON.JSON_DECODE_INT_AS_REAL)

Version History

Version

Notes

0.1.0

Added
jansson.dumps(json[, flags])#

Serialize a JSON to a string.

Parameters:
Returns:

The serialized string

Return type:

string

Dump Flags

jansson.JSON_INDENT(n)#

Pretty-print the result, using newlines between array and object items, and indenting with n spaces. The valid range for n is between 0 and 31 (inclusive), other values result in an undefined output. If JSON_INDENT is not used or n is 0, no newlines are inserted between array and object items.

The maximum indentation that can be used is 31.

jansson.JSON_COMPACT#

This flag enables a compact representation, i.e. sets the separator between array and object items to "," and between object keys and values to ":". Without this flag, the corresponding separators are ", " and ": " for more readable output.

jansson.JSON_ENSURE_ASCII#

If this flag is used, the output is guaranteed to consist only of ASCII characters. This is achieved by escaping all Unicode characters outside the ASCII range.

jansson.JSON_SORT_KEYS#

If this flag is used, all the objects in output are sorted by key. This is useful e.g. if two JSON texts are diffed or visually compared.

jansson.JSON_ENCODE_ANY#

Specifying this flag makes it possible to encode any JSON value on its own. Without it, only objects and arrays can be passed as the json value to the encoding functions.

jansson.JSON_ESCAPE_SLASH#

Escape the / characters in strings with \/.

jansson.JSON_REAL_PRECISION(n)#

Output all real numbers with at most n digits of precision. The valid range for n is between 0 and 31 (inclusive), and other values result in an undefined behavior.

By default, the precision is 17, to correctly and losslessly encode all IEEE 754 double precision floating point numbers.

jansson.JSON_EMBED#

If this flag is used, the opening and closing characters of the top-level array (‘[’, ‘]’) or object (‘{’, ‘}’) are omitted during encoding. This flag is useful when concatenating multiple arrays or objects into a stream.

Version History

Version

Notes

0.0.1

Added
jansson.array()#

Create a new empty JSON array.

Return type:

jansson.json

..versionhistory::
0.1.0:

Added

jansson.object()#

Create a new empty JSON object.

Return type:

jansson.json

Version History

Version

Notes

0.1.0

Added

Classes#

class jansson.json#

A JSON value. This is a wrapper around a Jansson json_t, but it is intended to function as a Lua table or sequence. As such the only json values a Lua user will enounter will be objects or arrays.

All other values are converted automatically to or from native Lua types when they are accessed or set.

Example#
local json = JSON.loads('{"foo": "bar"}')

-- 'bar'
local foo = json.foo

-- this is the same
foo = json['foo']

-- asignment works the same
json['foo'] = 'Hello JSON!'
json.foo = 'Hello JSON!'

-- assignment change change the value types, too
json.foo = 1234

-- new keys are created by assigning to them
json.bar = 'baz'

-- JSON objects function nearly exactly the same as tables
for k,v in pairs(json) do
    print(k .. ' = ' .. v)
end

-- arrays are similar but use integers for indexes
json = JSON.loads('["foo", "bar", "baz"]')

-- like Lua sequences, indexes start at 1
foo = json[1] -- 'foo'

-- and arrays also function like sequences
for i,v in ipairs(json) do
    print(i .. ' = ' .. v)
end

-- including appending values
table.insert(json, "Hello JSON!")

Version History

Version

Notes

0.0.1

Added