tmux_hook (libtmux for Erlang v0.0.1)

View Source

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

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.

Summary

Types

One validated command or a nonempty list; at most 256 commands and 32 KiB rendered text.

A session's current context, one observed membership, or a pane in that membership.

A registered local table or explicit global session/window defaults; see tmux_option:scope/0.

Canonical native command-list text, or a sparse map of indexes to that text.

Functions

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.

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.

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.

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.

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.

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.

Types

commands()

-type commands() :: tmux_command:t() | [tmux_command:t(), ...].

One validated command or a nonempty list; at most 256 commands and 32 KiB rendered text.

context()

A session's current context, one observed membership, or a pane in that membership.

scope()

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

A registered local table or explicit global session/window defaults; see tmux_option:scope/0.

value()

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

Canonical native command-list text, or a sparse map of indexes to that text.

Functions

append(Scope, Name0, Commands)

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

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(Scope, Name0)

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

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.

get(Scope, Key, Options)

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

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.

Values are tmux's command-list serialization, including its quoting and escape sequences. They are neither the original input text nor individual decoded arguments. Reading does not execute them. Use set/3 for validated command values and unset/2 to restore inheritance. Performs I/O and preserves backend errors; a vanished target is not an absent hook.

run(Context, Name0)

-spec run(context(), binary()) -> {ok, tmux_operation:completed()} | {error, tmux_operation:failure()}.

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.

Performs I/O. The result is the native command outcome, not an acknowledgement of background work launched by its commands. A missing or empty effective hook can succeed without effects. Wait on an application completion condition when effects matter. Existence and membership checks precede dispatch. If the target disappears after preflight, tmux can still fall back to another context. This is not atomic compare-and-act. Use fresh links after known topology changes.

set(Scope, Key, Commands)

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

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.

Performs I/O. tmux parses commands before replacing an existing entry, but a failed first write can already create an empty local override. Registration and later execution are separate; this call promises no transaction, rollback or completion of future effects.

unset(Scope, Key)

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

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.