RapidJSON Lua Module
1. Overview
Lua wrapper for the RapidJSON library allowing for JSON-Schema validation and more efficient manipulation of large JSON structures where only a small amount of the data is consumed within the Lua script.
2. Module
2.1. Example Usage
require "rjson"
json = [[{"array":[1,"string",true,false,[3,4],{"foo":"bar"},null]}]]
doc = rjson.parse(json)
str = doc:find("array", 1);
-- str == "string"
2.2. Functions
2.2.1. parse
Creates a JSON Document from a string.
local ok, doc = pcall(rjson.parse, '{"foo":"bar"}')
assert(ok, doc)
Arguments
- JSON (string) - JSON string to parse
- validate_encoding (bool, default: false) - true to turn on UTF-8 validation
Return
- doc (userdata) - JSON document or an error is thrown
2.2.2. parse_schema
Creates a JSON Schema.
local ok, doc = pcall(rjson.parse_schema, '{"type":"array","minItems": 1,"oneOf": [{"items": {"type":"number"}}]}')
assert(ok, doc)
Arguments
- JSON (string) - JSON schema string to parse
Return
- schema (userdata) - JSON schema or an error is thrown
2.2.3. parse_message (Heka sandbox only)
Creates a JSON Document from a message variable.
local ok, doc = pcall(rjson.parse_message, "Fields[myjson]")
assert(ok, doc)
Arguments
- heka_stream_reader (userdata) - require only for Input plugins since there is no active message available.
- variableName (string)
- Payload
- Fields[name]
- fieldIndex (unsigned) - optional, only used in combination with the Fields variableName use to retrieve a specific instance of a repeated field name; zero indexed
- arrayIndex (unsigned) - optional, only used in combination with the Fields variableName use to retrieve a specific element out of a field containing an array; zero indexed
- validate_encoding (bool, default: false) - true to turn on UTF-8 validation
Return
- doc (userdata) - JSON document or an error is thrown
2.2.4. version
require "rjson"
local v = rjson.version()
-- v == "1.0.0"
Returns a string with the running version of rjson.
Arguments
- none
Return
- Semantic version string
2.3. JSON Document Methods
2.3.1. parse
2.3.2. parse_message (Heka sandbox only)
Re-uses the document object to avoid GC costs/lag. Same arguments/returns as the rjson functions.
2.3.3. validate
Checks that the JSON document conforms to the specified schema.
local ok, err, report = doc:validate(schema)
assert(ok, err)
Arguments
- heka_schema (userdata) - a compiled schema to validate against
Return
- ok (bool) - true if valid
- err (string/nil) - error message on failure
- report (string/nil) - schema violation report on failure
2.3.4. find
Searches for and returns a value in the JSON structure.
local v = doc:find("obj", "arr", 0, "foo")
assert(v, "not found")
Arguments
- value (lightuserdata) - optional, when not specified the function is applied to document
- key (string, number) - object key, or array index
- keyN (string, number) - final object key, or array index
Return
- value (lightuserdata) - handle to be passed to other methods, nil if not found
2.3.5. remove
Searches for and removes the resulting value in the JSON structure returning the removed value in new document (full copy).
local rv = doc:remove("obj", "arr")
assert(rv, "not found")
rv:size() -- number of elements in the extracted array
Arguments
- value (lightuserdata) - optional, when not specified the function is applied to document
- key (string, number) - object key, or array index
- keyN (string, number) - final object key, or array index
Return
- doc (userdata) - new document containing the removed value or nil
2.3.6. remove_shallow
Searches for and removes the resulting value in the JSON structure returning a reference to extracted JSON value (shallow copy).
local rv = doc:remove_shallow("obj", "arr")
assert(rv, "not found")
doc:size(rv) -- number of elements in the extracted array
Arguments
- value (lightuserdata) - optional, when not specified the function is applied to document
- key (string, number) - object key, or array index
- keyN (string, number) - final object key, or array index
Return
- value (lightuserdata) - value reference or nil
2.3.7. value
Returns the primitive value of the JSON element.
local v = doc:find("obj", "arr", 0, "foo")
local str = doc:value(v)
assert("bar" == str, tostring(str))
Arguments
- value (lightuserdata, nil) - optional, when not specified the function is applied to document (accepts nil for easier nesting without having to test the inner expression) e.g., str = doc:value(doc:find("foo")) or "my default"
Return
- primitive - string, number, bool, nil or throws an error if not convertible (object, array)
2.3.8. type
Returns the type of the value in the JSON structure.
local t = doc:type()
assert(t == "object", t)
Arguments
- value (lightuserdata, nil) - optional, when not specified the function is applied to document (accepts nil for easier nesting without having to test the inner expression)
Return
- type (string, nil) - "string", "number", "boolean", "object", "array" or "null"
2.3.9. iter
Retrieves an iterator function for an object/array.
local v = doc:find("obj", "arr")
for i,v in doc:iter(v) do
-- ...
end
Arguments
- value (lightuserdata, nil) - optional, when not specified the function is applied to document (accepts nil for API consistency)
Return
- iter (function, nil) - iterator function returning an index/value for arrays or a key/value for objects. Throws an error on primitive types.
2.3.10. size
Returns the size of the value.
local v = doc:find("obj", "arr")
local n = doc:size(v)
Arguments
- value (lightuserdata, nil) - optional, when not specified the function is applied to document (accepts nil for easier nesting without having to test the inner expression)
Return
- size (number, nil) - Number of element in an array/object or the length of the string. Throws an error on numeric, boolean and null types.
2.3.11. make_field (Heka sandbox only)
Helper function to wrap the lightuserdata so it can be used in a Heka inject_message field).
local msg = {Fields = {}}
local v = doc:find("obj", "arr")
msg.Fields.array = doc:make_field(v) -- set array to the JSON string representation of "arr"
inject_message(msg)
Arguments
- value (lightuserdata, nil) - optional, when not specified the function is applied to document (accepts nil for easier nesting without having to test the inner expression)
Return
- field (table, nil) - i.e.,
{value = v, userdata = doc, representation = "json"}