Json

Reads, encodes, decodes and converts JSON. `Json.decode` turns JSON text into Lua tables and `Json.encode` does the reverse. Lua has no null: a JSON `null` becomes `nil`, so object keys with a null value are absent from the decoded table and a null array item leaves a hole in it. When encoding, a table is written as an array if it has a key `1` (or is empty) and as an object otherwise. Object keys must be strings, arrays must not have holes, and objects are written in Lua's table order, which is neither alphabetical nor the order the keys were added.

• Kind Library, a global in every script
• Category APIs & Data
• Functions 6

Functions

• open any Reads a JSON file and decodes it like `Json.decode`.
• encode string Encodes a table as JSON text, pretty-printed with two spaces of indentation.
• decode any Decodes JSON text.
• format string Re-indents JSON text with two spaces without turning it into a table, so the order of the keys is kept.
• xml string Converts XML text to JSON text.
• toXml string Converts JSON text to XML text with an XML declaration.

open()

Json.open(file: string)→any

Reads a JSON file and decodes it like `Json.decode`. The file is parsed first with a standard JSON parser, so its parse errors are the ones you see. Throws `Failed to read JSON file` when the file is missing or is not valid JSON. An empty file gives `nil`.

Parameters

file string

JSON file to read, relative to the workspace

Returns

any The decoded value: a table for an object or array, otherwise a string, number or boolean

Example runs in CI

Fl.write("config.json", '{"name": "demo", "retries": 3, "tags": ["a", "b"]}')
local config = Json.open("config.json")
print(config.name, config.retries, config.tags[2])

encode()

Json.encode(table: table)→string

Encodes a table as JSON text, pretty-printed with two spaces of indentation. An empty table gives `{}`. Throws when the argument is not a table, when an object has non-string keys or an array has holes, when a table contains itself, and for values JSON cannot hold (functions, `NaN`, infinity). Write the result to a file with `Fl.write(path, text, false, false)`.

Parameters

table table

Table to encode: an array or an object with string keys

Returns

string The JSON text

decode()

Json.decode(json: string)→any

Decodes JSON text. Objects and arrays become tables, numbers become Lua numbers and unicode escapes (backslash, u and four hex digits, including surrogate pairs) become UTF-8 text. `null` becomes `nil`. Throws an error naming the line and column when the text is not valid JSON, including when anything other than whitespace follows the value.

Parameters

json string

JSON text to decode

Returns

any The decoded value: a table for an object or array, otherwise a string, number or boolean

Example runs in CI

local data = Json.decode('{"name": "Alice", "tags": ["a", "b"]}')
print(data.name, data.tags[2])
print(Json.encode({ answer = 42 }))

format()

Json.format(js: string)→string

Re-indents JSON text with two spaces without turning it into a table, so the order of the keys is kept. Throws a parser error when the text is not valid JSON.

Parameters

js string

JSON text to format

Returns

string The formatted JSON text

Example runs in CI

print(Json.format('{"b":1,"a":[1,2]}'))

xml()

Json.xml(xml: string)→string

Converts XML text to JSON text. Pass the result to `Json.decode` to get a table. Attributes become keys that start with `-`, element text becomes `#text` when the element also has attributes, repeated elements become an array and empty elements get `"-self-closing": "true"`. All values are strings. Throws when the text is not valid XML. `Json.toXml` converts back.

Parameters

xml string

XML text to convert

Returns

string The JSON text

Example runs in CI

local json = Json.xml("<order id='7'><item>Widget</item><item>Gadget</item></order>")
local order = Json.decode(json).order
print(order["-id"], #order.item)

toXml()

Json.toXml(js: string)→string

Converts JSON text to XML text with an XML declaration. The single top-level key becomes the root element; with several top-level keys (or an array) a `root` element is added. Array items become repeated elements, keys that start with `-` become attributes and `#text` the text of the element. Numbers, booleans and nulls get an attribute `number="true"`, `boolean="true"` or `null="true"`. Throws `Not a valid JSON string` when the text cannot be parsed.

Parameters

js string

JSON text to convert

Returns

string The XML text

Example runs in CI

print(Json.toXml('{"order": {"-id": "7", "item": ["Widget", "Gadget"]}}'))