# 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