JSON¶

Overview¶

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

Usage¶

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

json = require('json')

JSON¶

json.encode(object)¶

Encodes the object which can be a table, string, Boolean, number, nil or json.null, returning a JSON-encoded string. If the passed object is invalid JSON, this method may fail. Depending on the failure, an error message may or may not be shown in the debug output log.

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