Skip to main content

JSON API

JSON parsing and serialization helpers are available under ptool.json and p.json.

ptool.json.parse​

v0.3.0 - Introduced.

ptool.json.parse(input) parses a JSON string into a Lua value.

  • input (string, required): The JSON text.
  • Returns: The parsed Lua value. The root can be any JSON type.

Type mapping:

  • JSON object -> Lua table
  • JSON array -> Lua sequence table (1-based)
  • JSON string -> Lua string
  • JSON integer that fits in i64 -> Lua integer
  • Other JSON number -> Lua number
  • JSON boolean -> Lua boolean
  • JSON null -> Lua nil

Error behavior:

  • An error is raised if input is not a string.
  • A JSON syntax error raises an error whose message includes the parser detail from serde_json.

Example:

local data = p.json.parse('{"name":"ptool","features":["json","repl"],"stars":42}')

print(data.name)
print(data.features[1])
print(data.stars)

ptool.json.stringify​

v0.3.0 - Introduced.

ptool.json.stringify(value[, options]) converts a Lua value to a JSON string.

  • value (JSON-compatible Lua value, required): The value to encode.
  • options (table, optional): Serialization options.
  • options.pretty (boolean, optional): When true, output pretty-printed JSON. Defaults to false.
  • Returns: The encoded JSON string.

Behavior:

  • Default output is compact JSON with no extra whitespace.
  • Pretty output uses indented multi-line JSON.
  • Values must be JSON-compatible. Functions, threads, userdata, and other non-serializable Lua values raise an error.

Example:

local text = p.json.stringify({
  name = "ptool",
  features = {"json", "repl"},
  stable = true,
}, { pretty = true })

print(text)

Notes:

  • nil values inside Lua tables follow mlua's serde conversion behavior and are not preserved as JSON object fields.
  • Array/object detection for Lua tables follows mlua's serde conversion rules.