tmux_window_link (libtmux for Erlang v0.0.1)
View SourceAct on a physical window's observed membership in a particular session.
A window link is identified by session ID, window index and expected physical window ID. It has no stable tmux link ID. These calls check that the observed membership still names the expected window before dispatching an action. Missing or replaced membership returns stale_link. A link that moves away and back to the same coordinates and physical window cannot be distinguished.
The preflight and action use separate one-shot commands. Concurrent changes after preflight can still affect the action; this is not atomic compare-and-act. All input rows must belong to the same registered owner. Re-read or explicitly bind rows when using another owner. Closed owners and known restarts invalidate their rows. Every call performs explicit I/O after validating its arguments.
Use tmux_window:kill/1 to destroy a physical window across all memberships.
Use unlink/2 to remove one membership. Existing rows and
snapshots are never refreshed by actions; use get/3 or a
new snapshot for current memberships.
Summary
Types
An explicit tmux window index; relative and next-free selectors are not accepted.
Destination index is required. Defaults: detach true, replace false. Replacement may destroy the destination window.
Maps detach to tmux's -d flag, default true.
Force defaults false. Force permits unlinking the last membership and destroying its physical window.
Functions
Read a current membership at the explicit session ID and index. The returned native row carries its registered owner and a new observation identity. Returns target_gone if the session or index is absent. This read does not make later actions atomic and does not refresh previously captured links.
Add another membership of this link's physical window to the destination
session and explicit index. Defaults to detached and refuses an occupied
index. replace = true maps to tmux -k and can destroy the occupied window.
Returns the command result; use get/3 to observe the new membership. The
source membership remains. Session groups and renumber-windows retain their
tmux semantics. Performs I/O after owner and membership checks.
Move this membership to the destination session and explicit index, leaving
its physical window's other links intact. Placement options follow link/3.
Moving the final window out of a session can destroy that session; automatic
renumbering and session groups can change other memberships. Captured rows
remain unchanged. Returns the command result after observed preflight.
Select this membership as its session's current window after checking the expected physical window. Performs I/O and returns the command result.
Swap the physical windows at two checked memberships. Other links to either window remain intact. detach maps to tmux -d and defaults true. tmux applies its session-selection and group-synchronization rules. Returns the command result; old rows still name their original expected windows and can become stale. Performs I/O, with the documented gap between preflight and action.
Remove one checked membership. force defaults false, retaining tmux's protection for windows linked to only one session. force = true permits removing the last link, destroying that physical window and possibly its session. Duplicate links within one session retain tmux's native protection rules. Performs I/O and returns the command result without refreshing rows.
Types
-type index() :: 0..2147483647.
An explicit tmux window index; relative and next-free selectors are not accepted.
Destination index is required. Defaults: detach true, replace false. Replacement may destroy the destination window.
-type swap_options() :: #{detach => boolean()}.
Maps detach to tmux's -d flag, default true.
-type unlink_options() :: #{force => boolean()}.
Force defaults false. Force permits unlinking the last membership and destroying its physical window.
Functions
-spec get(tmux_server:t(), tmux_model:session_id(), index()) -> {ok, tmux_model:window_link()} | {error, map()}.
Read a current membership at the explicit session ID and index. The returned native row carries its registered owner and a new observation identity. Returns target_gone if the session or index is absent. This read does not make later actions atomic and does not refresh previously captured links.
Invalid indexes are rejected before I/O:
1> tmux_window_link:get(invalid_server, <<"$0">>, -1).
{error,#{code => invalid_option,path => [index]}}
-spec link(tmux_model:window_link(), tmux_model:session(), placement_options()) -> {ok, tmux_operation:completed()} | {error, tmux_operation:failure()}.
Add another membership of this link's physical window to the destination
session and explicit index. Defaults to detached and refuses an occupied
index. replace = true maps to tmux -k and can destroy the occupied window.
Returns the command result; use get/3 to observe the new membership. The
source membership remains. Session groups and renumber-windows retain their
tmux semantics. Performs I/O after owner and membership checks.
-spec move(tmux_model:window_link(), tmux_model:session(), placement_options()) -> {ok, tmux_operation:completed()} | {error, tmux_operation:failure()}.
Move this membership to the destination session and explicit index, leaving
its physical window's other links intact. Placement options follow link/3.
Moving the final window out of a session can destroy that session; automatic
renumbering and session groups can change other memberships. Captured rows
remain unchanged. Returns the command result after observed preflight.
-spec select(tmux_model:window_link()) -> {ok, tmux_operation:completed()} | {error, tmux_operation:failure()}.
Select this membership as its session's current window after checking the expected physical window. Performs I/O and returns the command result.
-spec swap(tmux_model:window_link(), tmux_model:window_link(), swap_options()) -> {ok, tmux_operation:completed()} | {error, tmux_operation:failure()}.
Swap the physical windows at two checked memberships. Other links to either window remain intact. detach maps to tmux -d and defaults true. tmux applies its session-selection and group-synchronization rules. Returns the command result; old rows still name their original expected windows and can become stale. Performs I/O, with the documented gap between preflight and action.
-spec unlink(tmux_model:window_link(), unlink_options()) -> {ok, tmux_operation:completed()} | {error, tmux_operation:failure()}.
Remove one checked membership. force defaults false, retaining tmux's protection for windows linked to only one session. force = true permits removing the last link, destroying that physical window and possibly its session. Duplicate links within one session retain tmux's native protection rules. Performs I/O and returns the command result without refreshing rows.