Erlang API

module libtmux-erlang latest

tmux_hook

Store builtin hook commands and run them in an explicit observed context.

Source and package

tmux_hook module libtmux_erlang [source] ¶: Description#

set/3 replaces one indexed entry. append/3 uses tmux's first vacant index; clear/2 leaves an empty local array and unset/2 restores inheritance. get/3 reads local values unless inheritance is requested. Commands are tmux_command:t/0 values, rendered by tmux_command:to_config/1 before tmux parses and stores them. A successful write confirms registration, while later hook effects need their own completion evidence.
Table scope and execution context are separate. run/2 selects a session, checked window link or checked pane/link pair. Physical windows can belong to several sessions; a link preserves the chosen session and index. Preflight and dispatch are separate observations, with no atomic compare-and-act guarantee. Known restarts and closed owners invalidate references. Captured rows never refresh during these actions.
Names and table scopes use the exact source-derived version catalogue from tmux_option:catalogue/1. User options, prefixes and aliases are rejected. The native custom-event and monitor interfaces are outside this API. Deliberate raw integration remains available through tmux_command:raw/2. Calls perform I/O after validation and never retry uncertain mutations. The hook guide demonstrates registration and an effect acknowledgement.

Members10#

set/3 function Replace one {Name, Index} entry with validated command values. An explicit index is required; other entries remain. Indexes range from zero to 2147483647. The rendered command text is bounded before dispatch. Native commands still interpret their arguments and formats when the hook later runs. Use append/3 for native vacant-index selection and clear/2 to mask inherited hooks with an empty local array.
get/3 function Read a builtin hook array or indexed entry. Options follow tmux_option:read_options/0: local-only by default, inherit = true follows its parent tables. Missing local arrays or entries return none; an empty local array returns {ok, #{}} and masks inheritance.
run/2 function Request native set-hook -R in the explicit context/0. tmux resolves the hook through that context's effective tables; global table flags do not select a separate execution scope. A session uses its current window and pane. A window link fixes the observed session/index and expected physical window; a pane context additionally checks that pane's observed parent.

append/3 function Store commands at tmux's first vacant local index for the unindexed name. A new local array starts independently of inherited entries; this does not copy the parent's array. The command result does not report the chosen index; get/3 observes current entries separately. Performs I/O with the parsing and unknown-outcome semantics of set/3.
clear/2 function Leave an empty local hook array, masking inherited entries. This differs from unset/2, which restores inheritance. Global clear empties that defaults table. Performs I/O; existing effects already queued by tmux are not cancelled.
commands/0 typealias One validated command or a nonempty list; at most 256 commands and 32 KiB rendered text.
context/0 typealias A session's current context, one observed membership, or a pane in that membership.
scope/0 typealias A registered local table or explicit global session/window defaults; see tmux_option:scope/0.
unset/2 function Remove one indexed entry or the whole local array. Removing an entry leaves its local array, possibly empty. Removing the whole array restores inheritance; unsetting a global builtin resets its native default. Missing local values are a successful native no-op. Performs I/O; queued hook effects are unaffected.
value/0 typealias Canonical native command-list text, or a sparse map of indexes to that text.

Pages that discuss tmux_hook.