tmux_pane (libtmux for Erlang v0.0.1)

View Source

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 (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 (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 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.

Summary

Types

Break placement: explicit destination index, optional literal window name. detach defaults true.

Capture range and rendering flags. Byte output and its final newline are preserved.

A capture line coordinate, or all for tmux's full available range.

Join/move geometry: detach true, vertical split by default. before and full_size follow tmux layout rules.

A validated named key, single UTF-8 character, function key or control-letter key.

Explicit shell code: a nonempty NUL-free binary, with no tmux format or strftime expansion.

Pipe direction defaults to output. toggle defaults false; true closes an existing pipe instead of replacing it.

Requested absolute pane dimensions in cells. Supply at least one dimension; tmux can clamp it to fit the layout.

Respawn options. Defaults: force false, launch previous, saved cwd. Environment augments tmux's resolved session environment for this spawn.

Split geometry, placement and explicit launch options. Defaults to a detached vertical split.

Swap controls: detach defaults true; zoom maps to tmux -Z to retain zoom.

Functions

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.

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.

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.

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 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.

Destroy this registered pane. Performs I/O after validating its origin and stable ID; it never falls back to a positional target.

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.

Connect a shell process to this registered physical pane, performing I/O. An explicit nonempty #{shell => Command} is required (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.

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.

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.

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.

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.

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.

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.

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.

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.

Types

break_options()

-type break_options() :: #{index := tmux_window_link:index(), name => binary(), detach => boolean()}.

Break placement: explicit destination index, optional literal window name. detach defaults true.

capture_options()

-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()}.

Capture range and rendering flags. Byte output and its final newline are preserved.

coordinate()

-type coordinate() :: -2147483648..32767 | all.

A capture line coordinate, or all for tmux's full available range.

join_options()

-type join_options() ::
          #{direction => horizontal | vertical,
            size => {cells, 1..2147483647} | {percent, 1..100},
            detach => boolean(),
            before => boolean(),
            full_size => boolean()}.

Join/move geometry: detach true, vertical split by default. before and full_size follow tmux layout rules.

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()}.

A validated named key, single UTF-8 character, function key or control-letter key.

pipe_command()

-type pipe_command() :: #{shell := binary()}.

Explicit shell code: a nonempty NUL-free binary, with no tmux format or strftime expansion.

pipe_options()

-type pipe_options() :: #{direction => output | input | both, toggle => boolean()}.

Pipe direction defaults to output. toggle defaults false; true closes an existing pipe instead of replacing it.

resize_options()

-type resize_options() ::
          #{width := 1..65535, height => 1..65535} | #{width => 1..65535, height := 1..65535}.

Requested absolute pane dimensions in cells. Supply at least one dimension; tmux can clamp it to fit the layout.

respawn_options()

-type respawn_options() ::
          #{force => boolean(),
            launch => tmux_command:respawn_spec(),
            cwd => binary(),
            env => #{binary() => binary()}}.

Respawn options. Defaults: force false, launch previous, saved cwd. Environment augments tmux's resolved session environment for this spawn.

split_options()

-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()}.

Split geometry, placement and explicit launch options. Defaults to a detached vertical split.

swap_options()

-type swap_options() :: #{detach => boolean(), zoom => boolean()}.

Swap controls: detach defaults true; zoom maps to tmux -Z to retain zoom.

Functions

break(Pane, SourceLink, Session, Options)

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.

capture(Pane, Options)

-spec capture(tmux_model:pane(), capture_options()) -> {ok, binary()} | {error, map()}.

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.

get(Server, Id)

-spec get(tmux_server:t(), tmux_model:pane_id()) -> {ok, tmux_model:pane()} | {error, map()}.

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.

join(Source, Destination, Options)

-spec join(tmux_model:pane(), tmux_model:pane(), join_options()) ->
              {ok, tmux_operation:completed()} | {error, map()}.

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 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.

kill(Pane)

-spec kill(tmux_model:pane()) -> {ok, map()} | {error, map()}.

Destroy this registered pane. Performs I/O after validating its origin and stable ID; it never falls back to a positional target.

move(Source, Destination, Options)

-spec move(tmux_model:pane(), tmux_model:pane(), join_options()) ->
              {ok, tmux_operation:completed()} | {error, map()}.

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.

pipe/3

-spec pipe(tmux_model:pane(), pipe_command(), pipe_options()) -> {ok, map()} | {error, map()}.

Connect a shell process to this registered physical pane, performing I/O. An explicit nonempty #{shell => Command} is required (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 (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.

resize(Pane, Options)

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:

1> tmux_pane:resize(invalid_row, #{}).
{error,#{code => empty_resize}}

resize_command(Pane, Options)

-spec resize_command(tmux_model:pane(), resize_options()) -> {ok, tmux_command:t()} | {error, map()}.

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.

1> tmux_pane:resize_command(invalid_row, #{}).
{error,#{code => empty_resize}}

respawn(Pane, Options)

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:

1> tmux_pane:respawn(invalid_row, #{launch => default_shell}).
{error,#{code => invalid_launch}}

send_keys(Pane, Keys)

-spec send_keys(tmux_model:pane(), [key()]) -> {ok, map()} | {error, map()}.

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.

send_text/2

-spec send_text(tmux_model:pane(), binary()) -> {ok, map()} | {error, map()}.

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.

split(Row, Options)

-spec split(tmux_model:pane() | tmux_model:window(), split_options()) ->
               {ok, tmux_model:pane()} | {error, map()}.

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.

stop_pipe(Pane)

-spec stop_pipe(tmux_model:pane()) -> {ok, map()} | {error, map()}.

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.

swap(Source, Destination, Options)

-spec swap(tmux_model:pane(), tmux_model:pane(), swap_options()) ->
              {ok, tmux_operation:completed()} | {error, map()}.

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.