tmux_option
Read and change explicit tmux option tables through registered references.
Source and package
- Qualified name
-
tmux_option - Package
- libtmux_erlang
- Source
- apps/libtmux_erlang/src/tmux_option.erl
- tmux_option
-
Description#
Session, physical window and pane records from
tmux_modelselect 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_hookowns hook registration and execution; hooks are rejected here. Prefixes and aliases are rejected.get/3requires 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/3reads 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/2remains 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.
Members13#
Common operations2#
- get_many/3 function 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/0controls inheritance as inget/3. - describe/2 function 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.
Other members11#
- catalogue/1 function 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.
- get/3 function 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/4to write a value andunset/2to restore inheritance. - key/0 typealias Canonical binary name; arrays use a structured non-negative index, never bracket syntax.
- metadata/0 typealias Source-derived scope, parser type, array and executable-hook metadata.
- read_options/0 typealias Local-only unless inherit is true. Unknown options and non-Booleans are errors.
- scope/0 typealias A registered local entity or an explicitly selected global option table.
- set/3 function Set one scalar or indexed array entry with default write options. Performs I/O; see
set/4for append, only-if-unset, parsing and unknown-outcome semantics. - set/4 function 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/2 function 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.
- value/0 typealias Canonical tmux text bytes for a scalar/entry, or a sparse map for a whole array.
- write_options/0 typealias append maps to -a; only_if_unset maps to -o and reports already-set errors. Both default false.
Guides#
Pages that discuss tmux_option.