Json

Json binds the WpSpaJson C API, which represents values in SPA-JSON — the format WirePlumber's configuration files are written in. Scripts encounter it whenever they read a configuration section with Conf.get_section_as_json() or a setting with Settings.get().

JsonUtils provides the rules matching engine on top of it, which is what makes *.rules configuration sections work.

Constructors

Json.Null()

Json.Boolean(value)

Json.Int(value)

Json.Float(value)

Json.String(value): Construct a JSON value of the corresponding primitive type.

Json.Array(table)

Constructs a JSON array from a Lua table. Only the integer-keyed entries of the table are used. Values may be booleans, numbers, strings or other Json objects.

local empty = Json.Array {}
local list = Json.Array { "a", "b", "c" }

Json.Object(value)

Constructs a JSON object either from a Lua table, using only its string-keyed entries, or from a Properties object.

local obj = Json.Object { ["node.name"] = "my-node", ["priority.session"] = 1000 }

Json.Raw(string)

Constructs a JSON value by parsing a SPA-JSON string directly.

Parameters:: string (string) -- the SPA-JSON text to parse

Inspecting values

Json.is_null(self)

Json.is_boolean(self)

Json.is_int(self)

Json.is_float(self)

Json.is_string(self)

Json.is_array(self)

Json.is_object(self)

Test the type of the value.

Returns:: true if the value is of the corresponding type
Return type:: boolean

Json.parse(self, n_recursions)

Converts the JSON value into the equivalent Lua value: a boolean, number or string for primitives, or a table for arrays and objects.

Parameters:: n_recursions (integer) -- (optional) how many levels deep to convert nested containers; by default the whole value is converted
Returns:: the converted value

Json.to_string(self)

Returns the SPA-JSON text of this value, and nothing else.

Returns:: the SPA-JSON text representation of the value
Return type:: string

Json.get_size(self)

Returns:: the size in bytes of the SPA-JSON text representation of the value
Return type:: integer

Json.merge(self, other)

Merges two JSON containers. Both values must be arrays, or both must be objects; merging anything else raises an error.

Parameters:: other (Json) -- the value to merge into a copy of self
Returns:: the merged value
Return type:: Json

JsonUtils — matching rules

A rules configuration section is an array of objects, each with a matches list of conditions and an actions object describing what to do when a condition matches. This is the mechanism behind monitor.alsa.rules, monitor.v4l2.rules, stream.rules and the other *.rules sections.

JsonUtils.match_rules_update_properties(rules, properties)

Binds wp_json_utils_match_rules_update_properties()

Applies the update-props action of every matching rule to properties. This is by far the most common use of the rules engine: a monitor reads its rules section once, then runs every object's properties through this function before creating the object.

config.rules = Conf.get_section_as_json ("monitor.bluez.rules", Json.Array {})
-- ...
properties = JsonUtils.match_rules_update_properties (config.rules, properties)

Parameters:

rules (Json) -- the rules array
properties -- a table or Properties object to match against and update

Returns:

the updated properties, and the number of properties that were changed

Return type:

Properties, integer

JsonUtils.match_rules(rules, properties, callback)

Binds wp_json_utils_match_rules()

The general form: for every rule whose matches conditions are satisfied by properties, calls callback with the action name and its value. Use this when the rules define actions other than update-props.

Parameters:

rules (Json) -- the rules array
properties -- a table or Properties object to match against
callback (function) -- called as callback(action, value) for each matching action

Returns:

true if the rules were processed successfully, plus an error message string if not

Return type:

boolean, string