tmux_option (libtmux for Erlang v0.0.1)

View Source

Read and change explicit tmux option tables through registered references.

Session, physical window and pane records from tmux_model select their local tables. Global tables use {server, Server}, {session_defaults, Server} or {window_defaults, Server}. Built-in canonical names and scopes are checked against pinned source metadata; tmux otherwise lets a name override the supplied scope flags. tmux_hook owns hook registration and execution; hooks are rejected here. Prefixes and aliases are rejected.

get/3 requires an explicit options map. Local-only reads are the default; inherit = true follows tmux's table parents (pane -> window -> window defaults, or session -> session defaults). Server options have no parent. A missing local value or array entry returns none; an empty binary or empty array is a value. Arrays return maps of indexes to binary values, preserving sparse indexes. There is no hidden capture refresh or cache of option values. get_many/3 reads the same scalar key from up to seven local rows through one bounded native sequence, retaining local-only semantics by default.

Values are NUL-free binary tmux text bytes, including non-UTF-8 bytes. No shell or format expansion is applied by this API. tmux still interprets a built-in option according to its type: formats, shell commands and command options may execute later when tmux uses them. This API is for trusted application code. Numeric and flag values are canonical binary text on reads, not Erlang numbers.

Built-in metadata covers every released version in the supported tmux 3.3a–3.8 range, including exact patch letters. Tracking and unknown versions fail closed. User options beginning @ do not need a built-in catalogue. The raw tmux_command:raw/2 remains available for deliberate newer-server integration. All mutations are one-shot I/O with observed identity checks, not transactions. Timeouts can leave an unknown remote outcome; mutations are never retried here. See the scoped options guide for ownership and inheritance.

Summary

Types

Canonical binary name; arrays use a structured non-negative index, never bracket syntax.

Source-derived scope, parser type, array and executable-hook metadata.

Local-only unless inherit is true. Unknown options and non-Booleans are errors.

A registered local entity or an explicitly selected global option table.

Canonical tmux text bytes for a scalar/entry, or a sparse map for a whole array.

append maps to -a; only_if_unset maps to -o and reports already-set errors. Both default false.

Functions

Return all canonical built-in option and hook metadata for one exact parsed version, without I/O. Catalogues cover every release from 3.3a through 3.8; historical 3.3 metadata remains available for source discovery. The generated reference records each release's source commit and file digests.

Return source metadata for a canonical built-in name and a parsed daemon version, without I/O. Unknown names, unavailable names, tracking builds and uncatalogued versions have distinct errors. The catalogue describes scopes and parser types; it does not qualify runtime behavior or authorize hook execution.

Read one option or array, performing I/O after validation. Missing local values and array entries return none; known empty strings and arrays return {ok, Value}. inherit = true reads through tmux's parent tables. Unknown fields are rejected. Errors retain backend diagnostics; a missing target never becomes absence. Use set/4 to write a value and unset/2 to restore inheritance.

Read one scalar option from one to seven local rows on the same registered endpoint. Performs one bounded native sequence after validating every scope. Results follow input order; each entry is binary text or none for a missing local value. read_options/0 controls inheritance as in get/3.

Set one scalar or indexed array entry with default write options. Performs I/O; see set/4 for append, only-if-unset, parsing and unknown-outcome semantics.

Set a literal binary value, after scope/version/owner validation. Array writes require {Name, Index}; this avoids tmux's whole-array separator grammar. append uses tmux's type-specific -a semantics. only_if_unset checks the local table; already-set is a backend error, with no suppressed errors or compare-and-swap guarantee. Values must be supplied explicitly; an empty flag value retains tmux's native toggle behavior. A successful result proves command completion, not later effects of a stored command or format. Performs I/O; never retries.

Remove a local option or one indexed entry. Removing a local option restores inheritance; removing an entry leaves a local array, possibly empty. Unsetting a global built-in resets tmux's default; user options are removed. Missing local values are a successful tmux no-op. No pane-wide -U action is implied. Performs I/O and returns the command result without refreshing captured rows.

Types

key()

-type key() :: binary() | {binary(), non_neg_integer()}.

Canonical binary name; arrays use a structured non-negative index, never bracket syntax.

metadata()

-type metadata() ::
          #{scopes := [server | session | window | pane],
            type := choice | colour | command | flag | key | number | string,
            array := boolean(),
            hook := boolean()}.

Source-derived scope, parser type, array and executable-hook metadata.

read_options()

-type read_options() :: #{inherit => boolean()}.

Local-only unless inherit is true. Unknown options and non-Booleans are errors.

scope()

-type scope() ::
          tmux_model:session() |
          tmux_model:window() |
          tmux_model:pane() |
          {server | session_defaults | window_defaults, tmux_server:t()}.

A registered local entity or an explicitly selected global option table.

value()

-type value() :: binary() | #{non_neg_integer() => binary()}.

Canonical tmux text bytes for a scalar/entry, or a sparse map for a whole array.

write_options()

-type write_options() :: #{append => boolean(), only_if_unset => boolean()}.

append maps to -a; only_if_unset maps to -o and reports already-set errors. Both default false.

Functions

catalogue(Version)

-spec catalogue(tmux_version:t()) -> {ok, #{binary() => metadata()}} | {error, map()}.

Return all canonical built-in option and hook metadata for one exact parsed version, without I/O. Catalogues cover every release from 3.3a through 3.8; historical 3.3 metadata remains available for source discovery. The generated reference records each release's source commit and file digests.

describe(Version, Name)

-spec describe(tmux_version:t(), binary()) -> {ok, metadata()} | {error, map()}.

Return source metadata for a canonical built-in name and a parsed daemon version, without I/O. Unknown names, unavailable names, tracking builds and uncatalogued versions have distinct errors. The catalogue describes scopes and parser types; it does not qualify runtime behavior or authorize hook execution.

1> {ok, V} = tmux_version:parse(<<"tmux 3.3a">>), ok.
ok
2> {ok, M} = tmux_option:describe(V, <<"exit-empty">>), ok.
ok
3> maps:get(scopes, M).
[server]

get(Scope, Key, Options)

-spec get(scope(), key(), read_options()) -> {ok, value()} | none | {error, map()}.

Read one option or array, performing I/O after validation. Missing local values and array entries return none; known empty strings and arrays return {ok, Value}. inherit = true reads through tmux's parent tables. Unknown fields are rejected. Errors retain backend diagnostics; a missing target never becomes absence. Use set/4 to write a value and unset/2 to restore inheritance.

get_many(Scopes, Name, Options)

-spec get_many([tmux_model:session() | tmux_model:window() | tmux_model:pane(), ...],
               binary(),
               read_options()) ->
                  {ok, [binary() | none]} | {error, map()}.

Read one scalar option from one to seven local rows on the same registered endpoint. Performs one bounded native sequence after validating every scope. Results follow input order; each entry is binary text or none for a missing local value. read_options/0 controls inheritance as in get/3.

Names use ASCII letters, digits, dots, underscores and hyphens, with an optional leading @ for user options. Global tables, arrays, indexed keys, hooks and command options are unsupported. Use get/3 for broader option reads and tmux_hook:get/3 for hooks. Invalid scopes, unsupported keys and different owners fail before dispatch.

Each read is bracketed by matching native target-ID observations. Unresolved or mismatched IDs reject the batch. The checks do not prove topology membership or completed destruction: older tmux may retain an unlinked pane through queued references. The sequence provides interval observations and the same server-incarnation guarantee as get/3. Ambient command configuration applies to both paths.

Stdout is bounded to 1 MiB and stderr to 64 KiB for the whole sequence, with the endpoint's 2500 ms command deadline. Seven 32 KiB values fit even under the qualified worst-case native quoting expansion. Larger external values may exceed that aggregate output bound. Any command, framing or decoding failure rejects the entire result, retaining native outcome and cleanup evidence. There is no partial-success result, hidden refresh or value cache.

set(Scope, Key, Value)

-spec set(scope(), key(), binary()) ->
             {ok, tmux_operation:completed()} | {error, tmux_operation:failure()}.

Set one scalar or indexed array entry with default write options. Performs I/O; see set/4 for append, only-if-unset, parsing and unknown-outcome semantics.

set(Scope, Key, Value, Options)

-spec set(scope(), key(), binary(), write_options()) ->
             {ok, tmux_operation:completed()} | {error, tmux_operation:failure()}.

Set a literal binary value, after scope/version/owner validation. Array writes require {Name, Index}; this avoids tmux's whole-array separator grammar. append uses tmux's type-specific -a semantics. only_if_unset checks the local table; already-set is a backend error, with no suppressed errors or compare-and-swap guarantee. Values must be supplied explicitly; an empty flag value retains tmux's native toggle behavior. A successful result proves command completion, not later effects of a stored command or format. Performs I/O; never retries.

unset(Scope, Key)

-spec unset(scope(), key()) -> {ok, tmux_operation:completed()} | {error, tmux_operation:failure()}.

Remove a local option or one indexed entry. Removing a local option restores inheritance; removing an entry leaves a local array, possibly empty. Unsetting a global built-in resets tmux's default; user options are removed. Missing local values are a successful tmux no-op. No pane-wide -U action is implied. Performs I/O and returns the command result without refreshing captured rows.