Source at 4d73c9795adca3e49eea74d1d2cbbbbdcbea0b6c
SHA-256: e71ac56dab19886495cae801a1a83d85123e519de1c10ba8eb4128c8ff33db48
-module(tmux_pane). -moduledoc """ Create, observe and rearrange panes using registered physical IDs. `split/2` accepts a pane or a window; a window means its active pane at execution. Options (`t:split_options/0`) are direction (horizontal or vertical), size ({cells, N} or {percent, N}), before, full_size, zoom, cwd, env, launch and detach. It defaults to a detached vertical split. `get/2` returns newly observed fields; existing rows remain unchanged. Reads span several commands and do not claim atomicity. Launch and environment options follow `tmux_session:create/2`. An absent or zero tmux pane_pid is represented as none. A captured positive PID is an observation, not a guarantee that the process remains alive. A successful split followed by a failed observation retains the completed mutation and command result in its error. `kill/1` returns the command result. Detached or stale references cannot act. `resize_command/2` builds a reusable value without tmux I/O; the other calls perform I/O after validation. `send_text/2` sends up to 2,000 literal bytes, including NUL, in one command using tmux's hexadecimal key form. It adds no Enter key and never splits a large input into partially applied commands. `send_keys/2` accepts up to 256 named keys, single UTF-8 characters, {function, 1..12} and {control, <<Letter>>}. Named keys are enter, tab, escape, backspace, space, up, down, left, right, home, 'end', insert, delete, page_up, page_down and back_tab. Terminal modes still govern how input is consumed; command completion does not mean a program processed it. `capture/2` returns stdout bytes unchanged, including final newlines. Options (`t:capture_options/0`) are start and 'end' (line integers or all), join_lines, escape_sequences, escape_control, retain_trailing_spaces, alternate, pending and quiet. Defaults are tmux's current-screen capture without escapes, joined wraps or padding. The endpoint's output limit applies; an oversized capture returns an error. Use `join/3`, `move/3` and `swap/3` to rearrange existing panes without respawning their processes. `break/4` takes an explicit source window link: breaking a window's only pane moves that membership, while breaking one of several panes creates a new physical window. The [topology guide](panes.md) shows the distinction. Use `get/2` or a new snapshot for updated parents and indexes; actions leave captured values unchanged. `pipe/3` connects a tmux-owned shell process to pane output, input or both. It protects the shell text from tmux hash/strftime expansion; shell quoting remains the caller's responsibility. `stop_pipe/1` closes that native pipe. These actions do not create an Erlang output subscription or transfer process ownership to the endpoint. Use an application acknowledgement for consumer readiness, delivered bytes and job completion. """. -export([split/2, get/2, kill/1, resize/2, respawn/2, send_text/2, send_keys/2, capture/2, break/4, join/3, move/3, swap/3, pipe/3, stop_pipe/1]). -export([resize_command/2]). -export_type([split_options/0, capture_options/0, resize_options/0, respawn_options/0, coordinate/0, key/0, break_options/0, join_options/0, swap_options/0, pipe_command/0, pipe_options/0]). -doc "Explicit shell code: a nonempty NUL-free binary, with no tmux format or strftime expansion.". -type pipe_command() :: #{shell := binary()}. -doc "Pipe direction defaults to output. toggle defaults false; true closes an existing pipe instead of replacing it.". -type pipe_options() :: #{direction => output | input | both, toggle => boolean()}. -doc """ Break placement: explicit destination index, optional literal window name. detach defaults true. """. -type break_options() :: #{index := tmux_window_link:index(), name => binary(), detach => boolean()}. -doc """ Join/move geometry: detach true, vertical split by default. before and full_size follow tmux layout rules. """. -type join_options() :: #{direction => horizontal | vertical, size => {cells,1..2147483647} | {percent,1..100}, detach => boolean(), before => boolean(), full_size => boolean()}. -doc """ Swap controls: detach defaults true; zoom maps to tmux -Z to retain zoom. """. -type swap_options() :: #{detach => boolean(), zoom => boolean()}. -doc "Split geometry, placement and explicit launch options. Defaults to a detached vertical split.". -type split_options() :: #{direction => horizontal | vertical, size => {cells,1..2147483647} | {percent,1..100}, before => boolean(), full_size => boolean(), zoom => boolean(), cwd => binary(), env => #{binary() => binary()}, launch => tmux_command:launch_spec(), detach => boolean()}. -doc "Requested absolute pane dimensions in cells. Supply at least one dimension; tmux can clamp it to fit the layout.". -type resize_options() :: #{width := 1..65535, height => 1..65535} | #{width => 1..65535, height := 1..65535}. -doc "Respawn options. Defaults: force false, launch previous, saved cwd. Environment augments tmux's resolved session environment for this spawn.". -type respawn_options() :: #{force => boolean(), launch => tmux_command:respawn_spec(), cwd => binary(), env => #{binary() => binary()}}. -doc "A capture line coordinate, or all for tmux's full available range.". -type coordinate() :: -2147483648..32767 | all. -doc "Capture range and rendering flags. Byte output and its final newline are preserved.". -type capture_options() :: #{start => coordinate(), 'end' => coordinate(), join_lines => boolean(), escape_sequences => boolean(), escape_control => boolean(), retain_trailing_spaces => boolean(), alternate => boolean(), pending => boolean(), quiet => boolean()}. -doc "A validated named key, single UTF-8 character, function key or control-letter key.". -type key() :: binary() | enter | tab | escape | backspace | space | up | down | left | right | home | 'end' | insert | delete | page_up | page_down | back_tab | {function,1..12} | {control,binary()}. -doc """ Split a pane, or the supplied window's active pane, and observe the new pane. Defaults to a detached vertical split. Options and launch semantics are described in the module docs. Performs I/O; a post-creation read error retains the completed mutation rather than pretending that no pane was created. """. -spec split(tmux_model:pane() | tmux_model:window(), split_options()) -> {ok, tmux_model:pane()} | {error, map()}. split(Row, Options) -> maybe {ok, Flags, Launch} ?= tmux_args:launch_options(Options, [{direction, direction, <<>>}, {size, size, <<"-l">>}, {before, flag, <<"-b">>}, {full_size, flag, <<"-f">>}, {zoom, flag, <<"-Z">>}]), {ok, Server, Target} ?= tmux_target:resolve([pane, window], Row), {ok, Result} ?= tmux_target:run(Server, <<"split-window">>, [<<"-P">>, <<"-F">>, <<"#{pane_id}">>, <<"-t">>, Target] ++ Flags ++ [<<"--">> | Launch]), tmux_observe:created(Server, pane, Result) end. -doc """ Read fresh fields for a physical pane ID. Performs I/O and returns target_gone for a vanished pane. A captured PID remains an observation, not a live-process guarantee. """. -spec get(tmux_server:t(), tmux_model:pane_id()) -> {ok, tmux_model:pane()} | {error, map()}. get(Server, Id) -> tmux_observe:get(Server, pane, Id). -doc """ Destroy this registered pane. Performs I/O after validating its origin and stable ID; it never falls back to a positional target. """. -spec kill(tmux_model:pane()) -> {ok, map()} | {error, map()}. kill(Pane) -> tmux_target:act(pane, Pane, <<"kill-pane">>, []). -doc """ Connect a shell process to this registered physical pane, performing I/O. An explicit nonempty `#{shell => Command}` is required (`t:pipe_command/0`). tmux hash formats and strftime directives are escaped so the shell receives the supplied text. This does not quote values interpolated into shell code; the caller owns that quoting. Executable argv is not accepted by this shell-only native command. Encoding follows `tmux_command:literal_format/2` in time mode. A percent-bearing command above its native 8191-byte intermediate limit returns `format_limit` before dispatch, preserving any existing pipe. `direction` (`t:pipe_options/0`) is `output` (default: pane output to child stdin), `input` (child stdout to pane input) or `both`. `toggle` defaults false, replacing any existing pipe. True maps to native `-o`: close an existing pipe without starting another, or open one when none exists. A stopped pipe and replacement can discard pending output. Await consumer acknowledgements before closing if delivered bytes matter. This is a live PTY byte stream, not rendered capture text or replay of terminal history; terminal modes affect its bytes. The child is started by tmux through `/bin/sh -c`. Its stderr is discarded; unused directions are routed to the native null device. No pane cwd or environment copying is promised. A successful command result does not prove exec success, readiness, delivery or child exit. The process is tmux-owned; `tmux_server:close/1` preserves the borrowed pane and its pipe. This is not an Erlang subscription with library flow control. Use `stop_pipe/1` to close the pipe; stopping is not process cancellation or a wait for job completion. """. -spec pipe(tmux_model:pane(), pipe_command(), pipe_options()) -> {ok, map()} | {error, map()}. pipe(Pane, #{shell := Shell} = Command, Options) when map_size(Command) =:= 1, is_binary(Shell), byte_size(Shell) > 0 -> maybe {ok, Flags} ?= tmux_args:options(Options, [{direction, pipe_direction, <<>>}, {toggle, flag, <<"-o">>}], #{direction => output}), {ok, Literal} ?= tmux_command:literal_format(Shell, time), {ok, Server, Target} ?= tmux_target:resolve(pane, Pane), tmux_target:run(Server, <<"pipe-pane">>, Flags ++ [<<"-t">>, Target, <<"--">>, Literal]) end; pipe(_, _, _) -> {error, #{code => invalid_pipe_command}}. -doc """ Close this registered pane's native pipe, performing I/O. On a live pane, closing an already closed pipe succeeds. An exited pane can produce a native command error; a vanished ID returns `target_gone`. Closing can discard pending bytes. It neither kills nor waits for an arbitrary shell job started by `pipe/3`; applications must verify consumption and process completion themselves. The endpoint does not own that shell process. """. -spec stop_pipe(tmux_model:pane()) -> {ok, map()} | {error, map()}. stop_pipe(Pane) -> tmux_target:act(pane, Pane, <<"pipe-pane">>, []). -doc """ Break a physical pane through its explicit source membership into a destination session/index. Source, link and session must have the same registered owner. The source link's expected window and the pane's observed parent are checked before dispatch. The source selector also includes the stable pane ID, never its positional index. Preflight and action are not atomic. With multiple panes, tmux creates a new physical window. With only one pane, it moves the selected source membership, preserving the existing window and its other links. Moving the final membership out can remove the source session. Pane IDs and processes remain; indexes and option inheritance can change. name is a literal UTF-8 argument, subject to native name cleaning. An occupied destination index is refused. detach defaults true; false selects the destination membership. Session groups retain native synchronization. Returns the command result consistently for both cases. Use `get/2` or `tmux_window_link:get/3` for fresh observations. Even an eventual native error can unzoom a window; this is not a transaction and is never retried. """. -spec break(tmux_model:pane(), tmux_model:window_link(), tmux_model:session(), break_options()) -> {ok, tmux_operation:completed()} | {error, map()}. break(Pane, SourceLink, Session, Options) -> maybe {ok, Index, Flags} ?= break_options(Options), {ok, Server} ?= tmux_target:same_owner(pane, Pane, window_link, SourceLink), {ok, Server} ?= tmux_target:same_owner(pane, Pane, session, Session), {ok, Source} ?= tmux_target:linked_pane(Server, Pane, SourceLink), {ok, SessionTarget} ?= tmux_target:selector(session, tmux_model:get(id, Session)), Target = <<SessionTarget/binary, Index/binary>>, tmux_target:run(Server, <<"break-pane">>, Flags ++ [<<"-s">>, Source, <<"-t">>, Target]) end. -doc """ Move a source pane into a split beside the destination pane. Both physical IDs must belong to the same registered owner and must differ. Geometry follows `t:join_options/0`. Existing processes and pane IDs survive; dimensions, indexes and inherited window options can change. Removing a window's last pane destroys that physical window and its links, and can remove sessions. Default detach true avoids selecting the resolved destination session; false uses tmux's resolved session context for the destination pane. Shared physical windows affect all their memberships. Returns the command result without refreshing either row. Use `get/2` for current fields. No retry is performed. """. -spec join(tmux_model:pane(), tmux_model:pane(), join_options()) -> {ok, tmux_operation:completed()} | {error, map()}. join(Source, Destination, Options) -> relocate(<<"join-pane">>, Source, Destination, Options). -doc """ Rearrange a source pane beside the destination, including within one window. Uses native move-pane, whose placement and lifetime behavior follow `join/3`. Both calls use explicit physical IDs and leave captured rows unchanged. """. -spec move(tmux_model:pane(), tmux_model:pane(), join_options()) -> {ok, tmux_operation:completed()} | {error, map()}. move(Source, Destination, Options) -> relocate(<<"move-pane">>, Source, Destination, Options). -doc """ Exchange two panes' layout positions within or across physical windows. Preserves their IDs and processes; parent windows, dimensions, indexes and inherited options can change. Both rows require the same registered owner. detach defaults true; active positions can still receive different panes. zoom maps to native -Z. Identical IDs do not exchange panes, but native zoom handling still runs; the default can unzoom even a same-pane swap. Returns the command result; `get/2` observes the resulting values explicitly. """. -spec swap(tmux_model:pane(), tmux_model:pane(), swap_options()) -> {ok, tmux_operation:completed()} | {error, map()}. swap(Source, Destination, Options) -> maybe {ok, Flags} ?= tmux_args:options(Options, [{detach, flag, <<"-d">>}, {zoom, flag, <<"-Z">>}], #{detach => true}), {ok, Server, From, To} ?= pane_targets(Source, Destination), tmux_target:run(Server, <<"swap-pane">>, Flags ++ [<<"-s">>, From, <<"-t">>, To]) end. relocate(Command, Source, Destination, Options) -> maybe {ok, Flags} ?= tmux_args:options(Options, [{detach, flag, <<"-d">>}, {direction, direction, <<>>}, {size, size, <<"-l">>}, {before, flag, <<"-b">>}, {full_size, flag, <<"-f">>}], #{detach => true}), {ok, Server, From, To} ?= pane_targets(Source, Destination), ok ?= case From =:= To of true -> {error, #{code => same_pane}}; false -> ok end, tmux_target:run(Server, Command, Flags ++ [<<"-s">>, From, <<"-t">>, To]) end. pane_targets(Source, Destination) -> maybe {ok, Server} ?= tmux_target:same_owner(pane, Source, pane, Destination), {ok, From} ?= tmux_target:selector(pane, tmux_model:get(id, Source)), {ok, To} ?= tmux_target:selector(pane, tmux_model:get(id, Destination)), {ok, Server, From, To} end. break_options(Options) when is_map(Options) -> maybe {ok, Index} ?= case maps:find(index, Options) of {ok, Value} when is_integer(Value, 0, 2147483647) -> {ok, integer_to_binary(Value)}; {ok, _} -> {error, #{code => invalid_option, path => [index]}}; error -> {error, #{code => missing_option, path => [index]}} end, {ok, Flags} ?= tmux_args:options(maps:remove(index, Options), [{detach, flag, <<"-d">>}, {name, text, <<"-n">>}], #{detach => true}), {ok, Index, Flags} end; break_options(_) -> {error, #{code => invalid_options, path => []}}. -doc """ Request an absolute width, height or both for this registered physical pane. Performs I/O after validating dimensions and origin. tmux can clamp the request to its layout constraints and can resize neighboring panes. Resizing a tiled pane unzooms its window. Use `get/2` for actual dimensions; the input row is unchanged. The accepted library range is not a promise that every server accepts every dimension: tmux versions can impose tighter limits and return a command error. An empty request is rejected before dispatch: ```erlang 1> tmux_pane:resize(invalid_row, #{}). {error,#{code => empty_resize}} ``` """. -spec resize(tmux_model:pane(), resize_options()) -> {ok, tmux_operation:completed()} | {error, tmux_operation:failure()}. resize(Pane, Options) -> maybe {ok, Command} ?= resize_command(Pane, Options), tmux_target:execute(Command) end. -doc """ Build a resize command without tmux I/O. Uses the dimensions and validation rules of `resize/2`, preserving the row's captured origin and stable pane ID. Endpoint liveness and native layout constraints are checked during execution. Submit through `tmux_server:command/3` or `tmux_operation:start/3`. ```erlang 1> tmux_pane:resize_command(invalid_row, #{}). {error,#{code => empty_resize}} ``` """. -spec resize_command(tmux_model:pane(), resize_options()) -> {ok, tmux_command:t()} | {error, map()}. resize_command(Pane, Options) -> maybe {ok, Flags} ?= tmux_args:options(Options, [{width, dimension, <<"-x">>}, {height, dimension, <<"-y">>}]), ok ?= case Flags of [] -> {error, #{code => empty_resize}}; _ -> ok end, {ok, Origin, Target} ?= tmux_target:captured_target(pane, Pane), tmux_command:generated(pane_resize, Origin, Flags ++ [<<"-t">>, Target]) end. -doc """ Respawn this registered physical pane, keeping its pane ID. force defaults false and a running pane normally returns command_error. force = true lets tmux close its existing PTY before spawning again. This acknowledges the tmux command, not former-job termination or successful application initialization. The old PTY can already be closed if a later spawn step fails. launch defaults to previous, reusing tmux's saved argv or shell. An explicit argv or shell map replaces that command. default_shell is invalid here because absent respawn arguments mean saved-command reuse. Omitted cwd retains the saved launch directory, rather than the program's current directory. env augments the session environment tmux resolves for this physical pane; a captured membership does not pin that context. Prior per-spawn overrides are not automatically reapplied. Other launch rules follow `tmux_session:create/2`. Performs I/O after validation. Existing rows retain their observations; use `get/2` and an application readiness condition to inspect the new process. An uncertain result is not permission to replay this mutation automatically. Unsupported launch modes fail before dispatch: ```erlang 1> tmux_pane:respawn(invalid_row, #{launch => default_shell}). {error,#{code => invalid_launch}} ``` """. -spec respawn(tmux_model:pane(), respawn_options()) -> {ok, tmux_operation:completed()} | {error, tmux_operation:failure()}. respawn(Pane, Options) -> maybe {ok, Flags, Launch} ?= tmux_args:respawn_options(Options), {ok, Server, Target} ?= tmux_target:resolve(pane, Pane), tmux_target:run(Server, <<"respawn-pane">>, Flags ++ [<<"-t">>, Target, <<"--">> | Launch]) end. -doc """ Send at most 2,000 literal bytes as hexadecimal tmux keys. Adds no Enter key and does not invoke a shell. Performs I/O in one command; oversized input is rejected before partial submission. Completion does not prove that a terminal program processed the input. """. -spec send_text(tmux_model:pane(), binary()) -> {ok, map()} | {error, map()}. send_text(Pane, Bytes) when is_binary(Bytes), byte_size(Bytes) =< 2000 -> Hex = [integer_to_binary(Byte, 16) || <<Byte>> <= Bytes], send(Pane, [<<"-H">>], Hex); send_text(_, Bytes) when is_binary(Bytes) -> {error, #{code => command_limit}}; send_text(_, _) -> {error, #{code => invalid_text}}. -doc """ Send at most 256 validated key tokens. Named keys, single UTF-8 characters, function keys and control-letter tuples are supported. Performs I/O; terminal modes determine the resulting input bytes. Use `send_text/2` for arbitrary bytes. """. -spec send_keys(tmux_model:pane(), [key()]) -> {ok, map()} | {error, map()}. send_keys(Pane, Keys) -> maybe {ok, Arguments} ?= keys(Keys, 256, []), send(Pane, [], Arguments) end. -doc """ Capture terminal bytes, preserving final newlines. Options select line range, joined wraps, escapes, alternate screen and padding; defaults follow tmux current-screen capture. Performs I/O and returns an explicit output-limit error instead of silently truncating. """. -spec capture(tmux_model:pane(), capture_options()) -> {ok, binary()} | {error, map()}. capture(Pane, Options) -> maybe {ok, Flags} ?= tmux_args:options(Options, [{start, coordinate, <<"-S">>}, {'end', coordinate, <<"-E">>}, {join_lines, flag, <<"-J">>}, {escape_sequences, flag, <<"-e">>}, {escape_control, flag, <<"-C">>}, {retain_trailing_spaces, flag, <<"-N">>}, {alternate, flag, <<"-a">>}, {pending, flag, <<"-P">>}, {quiet, flag, <<"-q">>}]), {ok, Server, Target} ?= tmux_target:resolve(pane, Pane), {ok, #{stdout := Bytes}} ?= tmux_target:run(Server, <<"capture-pane">>, [<<"-p">>, <<"-t">>, Target | Flags]), {ok, Bytes} end. send(Pane, Flags, Arguments) -> maybe {ok, Server, Target} ?= tmux_target:resolve(pane, Pane), tmux_target:run(Server, <<"send-keys">>, [<<"-t">>, Target] ++ Flags ++ [<<"--">> | Arguments]) end. keys([], _, Acc) -> {ok, lists:reverse(Acc)}; keys([_ | _], 0, _) -> {error, #{code => command_limit}}; keys([Key | Rest], Remaining, Acc) -> maybe {ok, Encoded} ?= key(Key), keys(Rest, Remaining - 1, [Encoded | Acc]) end; keys(_, _, _) -> {error, #{code => invalid_keys}}. key({function, N}) when is_integer(N, 1, 12) -> {ok, <<$F, (integer_to_binary(N))/binary>>}; key({control, <<C>>}) when C >= $a, C =< $z -> {ok, <<"C-", C>>}; key(Bytes) when is_binary(Bytes), byte_size(Bytes) =< 4 -> case unicode:characters_to_list(Bytes) of [Codepoint] when Codepoint >= 32, Codepoint =/= 127 -> {ok, Bytes}; _ -> {error, #{code => invalid_key}} end; key(Name) -> Names = #{enter => <<"Enter">>, tab => <<"Tab">>, escape => <<"Escape">>, backspace => <<"BSpace">>, space => <<"Space">>, up => <<"Up">>, down => <<"Down">>, left => <<"Left">>, right => <<"Right">>, home => <<"Home">>, 'end' => <<"End">>, insert => <<"IC">>, delete => <<"DC">>, page_up => <<"PPage">>, page_down => <<"NPage">>, back_tab => <<"BTab">>}, case maps:find(Name, Names) of {ok, Value} -> {ok, Value}; error -> {error, #{code => invalid_key}} end.