tmux_command (libtmux for Erlang v0.0.1)

View Source

Build tmux commands and bounded sequences without performing I/O.

Arguments remain binary values. Rendering protects trailing semicolons from tmux's command separator parser. This is distinct from shell quoting and from format expansion. A raw command is trusted application code; external services must apply their own command allowlist and write policy.

1> {ok, C} = tmux_command:raw(<<"list-panes">>, [<<"-a">>]), ok.
ok
2> tmux_command:argv(C).
[<<"list-panes">>,<<"-a">>]
3> tmux_command:literal_format(<<"api-#{pane_id}">>).
{ok,<<"api-##{pane_id}">>}
4> tmux_command:launch(#{argv => [<<"/bin/printf">>, <<"hello">>]}).
{ok,[<<"/bin/printf">>,<<"hello">>]}

Use literal_format/1 only for a whole argument that tmux expands as a format, such as a new name or cwd. It does not encode a value nested in a format expression. tmux's stored-name escaping and session-name substitutions still apply. Use literal_format/2 with mode time for commands such as display-message that also expand strftime percent directives. This protects one format-expansion pass, not later visual style rendering or recursive/nested expansion. No renderer reverses stored-name semantics.

launch/1 distinguishes executable argv from an explicitly requested shell command. A singleton argv uses the installed helper's exec-only mode because tmux otherwise passes one argument to its default shell. Empty argv is invalid; default_shell explicitly requests tmux's configured default command/shell. The internal helper uses an absolute path so a child's cwd does not change helper resolution. Relative executable arguments retain their native meaning.

Empty shell commands have command-specific lifetime. split-window creates a process-free pane. new-session executes an empty shell command and can remove the new object immediately. new-window does likewise before tmux 3.8; tmux 3.8 creates a process-free pane. Use a persistent job for parent sessions/windows that must remain available across supported versions.

Submit commands through tmux_server:command/3 or tmux_operation:start/3. sequence/1 combines flat command values for one-shot execution with combined output and a possible completed prefix on error. The job guide shows submission, completion and cancellation. tmux_session:rename_command/2 and tmux_pane:resize_command/2 build values bound to their row's captured origin. Execution through another endpoint returns different_owner before native work. Construction does not validate endpoint liveness or authorize an automatic mutation retry.

wait_for/2 builds native channel signals, waits and advisory locks. source_file/2 builds configuration loading from stdin or a literal absolute path. Both return command values without opening an endpoint or doing I/O. to_config/1 renders a command or bounded command list for native configuration input, preserving argument bytes through tmux's lexer.

Summary

Types

Explicit executable argv, an explicitly requested shell command, or tmux's configured default shell.

Reuse tmux's saved command/shell, or replace it with argv or a shell command. Used by tmux_pane:respawn/2 and tmux_window:respawn/2.

Standard input, or one literal absolute POSIX byte path with no NUL.

Native parse-only and quiet-missing-file flags; both default to false.

t()

A validated command or flat sequence. Rendering and execution remain separate. Domain builders retain a captured endpoint origin; raw values are unbound.

Native wait channel action. lock/unlock are explicit advisory operations, not owned leases.

Functions

Render a validated command into executable argv, protecting trailing tmux separators. Performs no I/O and raises for an invalid command value.

Render explicit executable argv, an explicitly requested shell command, or default_shell. Singleton argv uses the installed helper's exec-only mode to avoid tmux interpreting it as shell syntax. Performs no I/O.

Quote a complete literal argument for tmux format expansion. This does not encode operands nested inside another format expression. Performs no I/O.

Quote a complete literal format argument. Mode tmux protects hash expansion; mode time also protects strftime percent directives. Stored-name semantics remain tmux's own. This handles one expansion pass, not a nested operand, recursive expansion or later visual style rendering. Performs no I/O.

Validate one trusted command name and binary argv, without I/O. The renderer protects tmux separators; it does not provide shell or nested-format quoting. External services still need their own allowlists and write policy. Names are at most 128 bytes. NUL bytes are rejected, and at most 2,040 arguments fit within a 32 KiB command reservation including framing overhead.

Build one bounded native command sequence without I/O. Members must be a nonempty flat list of at most 256 command values. Their combined executable argv is limited to 2041 words and 32 KiB including separator overhead. Arguments keep the literal separator protection of raw/2; only boundaries between members become native command separators in argv/1.

Build configuration loading from stdin or one literal absolute path, without I/O. stdin renders source-file -; supply configuration bytes in the stdin option of tmux_server:command/3 or tmux_operation:start/3. Those APIs bound input to 256 KiB including their argument reservation.

Render validated commands as native configuration text, without I/O. Accepts one command, a sequence/1 value, or a nonempty flat list of at most 256 commands. Returns an ASCII binary of at most 32 KiB, without a final newline. Validation uses validate/1; escaping growth, command count and aggregate size can return command_limit. Lists use native command separators between independently quoted commands. Rendering does not execute them or provide atomic execution or rollback. The text carries no origin token; executing serialized configuration requires the caller to choose and validate its destination explicitly.

Revalidate a command value at a submission boundary. Returns a compact validated command or a tagged shape/argument/resource error, without I/O.

Build a native wait-for command without I/O. Channels are nonempty NUL-free binary names, subject to the command reservation in raw/2; neither shell nor format expansion occurs. Submit through tmux_operation:start/3 for a wait that leaves the caller free, or through tmux_server:command/3 to await it.

Types

launch_spec()

-type launch_spec() :: default_shell | #{argv := [binary(), ...]} | #{shell := binary()}.

Explicit executable argv, an explicitly requested shell command, or tmux's configured default shell.

respawn_spec()

-type respawn_spec() :: previous | #{argv := [binary(), ...]} | #{shell := binary()}.

Reuse tmux's saved command/shell, or replace it with argv or a shell command. Used by tmux_pane:respawn/2 and tmux_window:respawn/2.

source()

-type source() :: stdin | binary().

Standard input, or one literal absolute POSIX byte path with no NUL.

source_options()

-type source_options() :: #{parse_only => boolean(), quiet => boolean()}.

Native parse-only and quiet-missing-file flags; both default to false.

t()

-opaque t()

A validated command or flat sequence. Rendering and execution remain separate. Domain builders retain a captured endpoint origin; raw values are unbound.

wait_action()

-type wait_action() :: wait | signal | lock | unlock.

Native wait channel action. lock/unlock are explicit advisory operations, not owned leases.

Functions

argv(Command)

-spec argv(t()) -> [binary()].

Render a validated command into executable argv, protecting trailing tmux separators. Performs no I/O and raises for an invalid command value.

launch/1

-spec launch(launch_spec()) -> {ok, [binary()]} | {error, map()}.

Render explicit executable argv, an explicitly requested shell command, or default_shell. Singleton argv uses the installed helper's exec-only mode to avoid tmux interpreting it as shell syntax. Performs no I/O.

literal_format(Value)

-spec literal_format(binary()) -> {ok, binary()} | {error, map()}.

Quote a complete literal argument for tmux format expansion. This does not encode operands nested inside another format expression. Performs no I/O.

literal_format/2

-spec literal_format(binary(), tmux | time) -> {ok, binary()} | {error, map()}.

Quote a complete literal format argument. Mode tmux protects hash expansion; mode time also protects strftime percent directives. Stored-name semantics remain tmux's own. This handles one expansion pass, not a nested operand, recursive expansion or later visual style rendering. Performs no I/O.

Hash runs before [ stay unchanged because tmux preserves style-looking prefixes for a separate drawing step. Other hashes are doubled. In time mode, an argument containing percent bytes must fit tmux's 8191-byte strftime result limit after hash encoding and before percent doubling; larger values return format_limit with time_bytes and max_bytes. Arguments without percent bytes skip that native time-expansion limit. The encoded 32 KiB command limit still applies in either mode.

raw(Name, Arguments)

-spec raw(binary(), [binary()]) -> {ok, t()} | {error, map()}.

Validate one trusted command name and binary argv, without I/O. The renderer protects tmux separators; it does not provide shell or nested-format quoting. External services still need their own allowlists and write policy. Names are at most 128 bytes. NUL bytes are rejected, and at most 2,040 arguments fit within a 32 KiB command reservation including framing overhead.

sequence/1

-spec sequence([t(), ...]) -> {ok, t()} | {error, map()}.

Build one bounded native command sequence without I/O. Members must be a nonempty flat list of at most 256 command values. Their combined executable argv is limited to 2041 words and 32 KiB including separator overhead. Arguments keep the literal separator protection of raw/2; only boundaries between members become native command separators in argv/1.

Captured members must share an endpoint origin. That origin also binds the sequence; raw members use the caller's explicitly selected endpoint. Submit through tmux_server:command/3 or tmux_operation:start/3.

Execution is not atomic. A failed member can leave a completed prefix, and commands can wait or interleave with other work. The one-shot result contains combined bounded stdout/stderr and native exit status, without per-member completion attribution or rollback. Control-mode eligibility is separate. to_config/1 can serialize a sequence with the same origin-loss policy as other configuration text.

source_file(Source, Options)

-spec source_file(source(), source_options()) -> {ok, t()} | {error, map()}.

Build configuration loading from stdin or one literal absolute path, without I/O. stdin renders source-file -; supply configuration bytes in the stdin option of tmux_server:command/3 or tmux_operation:start/3. Those APIs bound input to 256 KiB including their argument reservation.

Paths are NUL-free POSIX byte binaries. Glob metacharacters and backslashes are escaped so only that filename is selected; format expansion is disabled. The combined encoded path and flags must fit raw/2 limits. The file is read by tmux at execution time; this builder does not open it or bound its size.

parse_only requests native -n parsing without executing the configuration's command list. quiet requests native -q missing-file suppression; it does not suppress syntax or execution errors. Both default to false. Configuration is trusted tmux code, with its own variable, directive and command semantics. Parse-only is not a sandbox. Execution can partially change server state before an error; cancellation cannot undo those effects. Completion does not prove that background jobs launched by the configuration have finished.

1> {ok, Source} = tmux_command:source_file(stdin, #{parse_only => true}), ok.
ok
2> tmux_command:argv(Source).
[<<"source-file">>,<<"-n">>,<<"--">>,<<"-">>]

to_config/1

-spec to_config(t() | [t(), ...]) -> {ok, binary()} | {error, map()}.

Render validated commands as native configuration text, without I/O. Accepts one command, a sequence/1 value, or a nonempty flat list of at most 256 commands. Returns an ASCII binary of at most 32 KiB, without a final newline. Validation uses validate/1; escaping growth, command count and aggregate size can return command_limit. Lists use native command separators between independently quoted commands. Rendering does not execute them or provide atomic execution or rollback. The text carries no origin token; executing serialized configuration requires the caller to choose and validate its destination explicitly.

Each argument is doublequoted. Quote, backslash, dollar, tilde, control and non-ASCII bytes use three-digit octal escapes. Empty arguments, semicolons, newlines and non-UTF-8 byte values remain argument data. The lexer does not expand their variables or tilde prefixes, strip newline indentation, or interpret them as directives, comments or additional commands.

Protection covers one lexer pass. Native command-string arguments, including bind-key and set-hook values, can be parsed again by the receiving command. Render each inner command string separately for its own parse boundary.

This is tmux configuration syntax, separate from argv/1 executable arguments and shell quoting. Native commands still interpret their values and expand formats as usual; literal_format/2 handles that separate boundary when literal format values are required. Load the text explicitly with source_file/2, or store it through a native command that accepts configuration text. The configuration guide uses this renderer with explicit execution and completion signals.

validate/1

-spec validate(term()) -> {ok, t()} | {error, map()}.

Revalidate a command value at a submission boundary. Returns a compact validated command or a tagged shape/argument/resource error, without I/O.

wait_for(Channel, Action)

-spec wait_for(binary(), wait_action()) -> {ok, t()} | {error, map()}.

Build a native wait-for command without I/O. Channels are nonempty NUL-free binary names, subject to the command reservation in raw/2; neither shell nor format expansion occurs. Submit through tmux_operation:start/3 for a wait that leaves the caller free, or through tmux_server:command/3 to await it.

signal wakes current waiters. On an unlocked channel with no waiters or pending wakeup, it retains one wakeup for a later wait. Signaling that channel again before a wait can clear the pending state. Signals are neither counted nor reliably coalesced events; send once per expected wait. Channel names are shared by all clients of the server. Use separate names for signaling and locking. lock acquires an advisory channel lock or waits for an explicit unlock; a completed command client's exit does not release its acquired lock. Unlocking an unlocked channel is a native command error.

Cancellation retires the library client. It does not undo a signal or release a lock that may already have been acquired; an uncertain lock outcome needs application coordination before another unlock. This is not an owned mutex.

1> {ok, Signal} = tmux_command:wait_for(<<"build-ready">>, signal), ok.
ok
2> tmux_command:argv(Signal).
[<<"wait-for">>,<<"-S">>,<<"--">>,<<"build-ready">>]