@spec default() :: t()

Returns the default Zenoh configuration as a JSON binary.

The returned configuration is valid input for Zenohex.Session.open/1.

Examples

Print the config in a readable form to check its contents.

iex> config = Zenohex.Config.default()
iex> config |> JSON.decode!() |> IO.inspect(pretty: true)

@spec from_env() :: {:ok, t()} | {:error, reason :: term()}

Loads configuration from the file path specified by the ZENOH_CONFIG environment variable.

Examples

### Set the environment variable and load the config
$ ZENOH_CONFIG=path/to/zenoh_config.json5 iex -S mix
iex> {:ok, config} = Zenohex.Config.from_env()
iex> is_binary(config)
true

### Set the environment variable in IEx
$ unset ZENOH_CONFIG && iex -S mix
iex> System.put_env("ZENOH_CONFIG", "path/to/zenoh_config.json5")
iex> {:ok, config} = Zenohex.Config.from_env()
iex> is_binary(config)
true

@spec from_file(String.t()) :: {:ok, t()} | {:error, reason :: term()}

Loads configuration from the file at the given path and returns it as a JSON string.

Examples

iex> {:ok, config} = Zenohex.Config.from_file("path/to/zenoh_config.json5")
iex> is_binary(config)
true

@spec from_json5(t()) :: {:ok, t()} | {:error, reason :: term()}

Parses a JSON5 configuration string and returns it as a JSON string.

This is useful when you already have configuration content in memory, such as text loaded from a file, template output, or environment-driven string construction.

Examples

iex> json5 = File.read!("path/to/zenoh_config.json5")
iex> {:ok, config} = Zenohex.Config.from_json5(json5)
iex> is_binary(config)
true

@spec get_json(t(), String.t()) :: {:ok, String.t()} | {:error, reason :: term()}

Returns the JSON string of the configuration value at key.

Examples

iex> config = Zenohex.Config.default()
iex> {:ok, value} = Zenohex.Config.get_json(config, "scouting/delay")
{:ok, "null"}

@spec insert_json5(t(), String.t(), String.t() | list()) ::
  {:ok, t()} | {:error, reason :: term()}

Inserts or updates a JSON5 configuration value at key, returning the updated config.

value should be a valid JSON5 string (e.g., "500", "true", or ""peer""). If value is not valid JSON5 format (for example, a plain string like "peer" missing its quotes), this function automatically quotes it (encodes as a JSON string) and retries the insertion.

A list value (e.g., ["tcp/localhost:7447"]) is also accepted and encoded as a JSON array before insertion. Printable ASCII charlist values (e.g., single-quoted text like 'peer') are rejected to avoid accidentally inserting a list of integer codepoints. Other non-ASCII charlists are treated as lists and may be encoded as JSON arrays of integers.

This function updates a configuration key directly. It does not interpret array-key/field=value as a field filter; use insert_json5_array_item/3 for that operation.

Examples

### Case 1: Insert numeric value
iex> config = Zenohex.Config.default()
iex> {:ok, updated1} = Zenohex.Config.insert_json5(config, "scouting/delay", "100")
iex> Zenohex.Config.get_json(updated1, "scouting/delay")
{:ok, "100"}

### Case 2: Insert valid JSON5 string (manually quoted)
iex> {:ok, updated2} = Zenohex.Config.insert_json5(updated1, "mode", ""peer"")
iex> Zenohex.Config.get_json(updated2, "mode")
{:ok, ""peer""}

### Case 3: Insert plain string (automatically quoted by this function)
iex> {:ok, updated3} = Zenohex.Config.insert_json5(updated2, "mode", "client")
iex> Zenohex.Config.get_json(updated3, "mode")
{:ok, ""client""}

### Case 4: Insert list as JSON array
iex> {:ok, updated4} = Zenohex.Config.insert_json5(updated3, "connect/endpoints", ["tcp/localhost:7447"])
iex> Zenohex.Config.get_json(updated4, "connect/endpoints")
{:ok, "["tcp/localhost:7447"]"}

### Past usage with `update_in/3`:
Zenohex.Config.update_in(config, ["scouting", "delay"], fn _ -> 100 end)
### Use `insert_json5/3` with the key path joined by `/`:
Zenohex.Config.insert_json5(config, "scouting/delay", "100")

@spec insert_json5_array_item(t(), String.t(), String.t()) ::
  {:ok, t()} | {:error, reason :: term()}

Inserts or updates a JSON5 object in an existing configuration array.

The key must use the array-key/field=value form, for example "qos/network/id=rule1". The value must be a JSON5 object containing the matching field. The object replaces the first matching item, or is appended when no matching item exists.

Returns {:error, :field_filter_required} when the key does not contain a field filter. This function is the field-filter counterpart to insert_json5/3; passing a field-filter key to insert_json5/3 is not supported.

Examples

iex> config = Zenohex.Config.default()
iex> {:ok, config} = Zenohex.Config.insert_json5(config, "qos/network", [])
iex> Zenohex.Config.insert_json5_array_item(config, "qos/network/id=rule1", "{id: \"rule1\", messages: [\"put\"], key_exprs: [\"**\"], overwrite: {priority: \"data\"}, flows: [\"egress\"]}")
{:ok, _updated_config}

@spec remove_json5_array_item(t(), String.t()) ::
  {:ok, t()} | {:error, reason :: term()}

Removes objects from an existing configuration array using a field filter.

The key must use the array-key/field=value form, for example "qos/network/id=rule1". All objects whose field matches the filter are removed.

Returns {:error, :field_filter_required} when the key does not contain a field filter. A successful result means the operation was recognized and applied, not necessarily that an object was removed.

Examples

iex> config = Zenohex.Config.default()
iex> {:ok, config} = Zenohex.Config.insert_json5(config, "qos/network", [%{id: "rule1", messages: ["put"], key_exprs: ["**"], overwrite: %{priority: "data"}, flows: ["egress"]}])
iex> Zenohex.Config.remove_json5_array_item(config, "qos/network/id=rule1")
{:ok, _updated_config}