JSON

Overview

The JSON API allows encoding and decoding of JSON encoded strings. This is used by some devices for their control protocol. For more information see https://www.json.org/json-en.html

Usage

To use, you must add the following to your script:

json = require('json')

JSON

	Type	Comment
`json.encode(object)`	Function	Encodes the object as a JSON string.
`json.decode(jsonString, startPos)`	Function	Decodes a JSON string returning a Lua object.
`json.null()`	Function	Used for null values in associative arrays.

json.encode(object)

Encodes the object which can be a table, string, Boolean, number, nil or json.null, returning a JSON-encoded string.

test = {name='Julie',color='Red',children={"Bob","Beth","Bruce"}}
encodedString = json.encode(test)
print(encodedString)

>> {"children":["Bob","Beth","Bruce"],"name":"Julie","color":"Red"}

json.decode(jsonString, startPos)

Decodes a JSON string and returns the decoded value as a Lua data structure / value.

encodedString = '{"name":"Julie", "color":"Red", "children":["Bob", "Beth", "Bruce"]}'

decoded = json.decode(encodedString)

Optionally, the starting position where the JSON string is located can be provided. Defaults to 1.

encodedString = 'My JSON String: {"name":"Julie", "color":"Red", "children":["Bob", "Beth", "Bruce"]}'

decoded = json.decode(encodedString, 16)

A second value is returned which is the position of the first character after the scanned JSON object.

encodedString = 'My JSON String: {"name":"Julie","color":"Red","children":["Bob","Beth","Bruce"]} Something Else'

decoded, nextPosition = json.decode(encodedString, 16)
print(nextPosition)                       >> 81

json.null()

The function allows one to specify a null value in an associative array (which is otherwise discarded if you set the value with 'nil' in Lua.

t = { first=json.null() }

note: json.null or json.null() may be interchangeably used.

Examples

The following examples illustrate how these can be used:

Example 1 - Encoding and Decoding

The following example, encodes a table then decodes it, printing the results for review

json = require('json')
test = {name='Julie',color='Red',children={"Bob","Beth","Bruce"}}
encodedString = json.encode(test)
print(encodedString)

decoded = json.decode(encodedString)

for i, k in pairs(decoded) do
    if type(k) ~= "table" then
        print(i, k)
    else
        print(i)
        for m, n in pairs(k) do
            print("  ", m, n)
        end
    end
end

You’ll see something like the following output in the Debug Output File:

{"name":"Julie","color":"Red","children":["Bob","Beth","Bruce"]}
name  Julie
color Red
children
    1     Bob
    2     Beth
    3     Bruce

Note the order of the returned table items may be different because Lua tables have no order. The above also presents a good example for printing a multi dimensional table.

Example 2 - nil vs json.null

As described above, json.null allows one to specify a null value in an associative array. This would have been otherwise discarded if you set the value with 'nil' in Lua. Using this allows the key to remain when encoded in JSON as shown in the example below.

user1 = {firstName="Jack", lastName=nil}
user2 = {firstName="Jill", lastName=json.null}

encodedUser1 = json.encode(user1)
encodedUser2 = json.encode(user2)

print("encoded user1: " .. encodedUser1)
print("encoded user1: " .. encodedUser2)

>> encoded user1: {"firstName":"Jack"}
>> encoded user1: {"firstName":"Jill","lastName":null}

You can see the key for user1 was discarded while user2 retains the key and it is set to “null” in the JSON encoding.