tmux_command (libtmux for Erlang v0.0.1)
View SourceBuild 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.
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
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.
-type source() :: stdin | binary().
Standard input, or one literal absolute POSIX byte path with no NUL.
Native parse-only and quiet-missing-file flags; both default to false.
-opaque t()
A validated command or flat sequence. Rendering and execution remain separate. Domain builders retain a captured endpoint origin; raw values are unbound.
-type wait_action() :: wait | signal | lock | unlock.
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.
-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.
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.
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.
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.
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.
-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">>,<<"--">>,<<"-">>]
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.
Revalidate a command value at a submission boundary. Returns a compact validated command or a tagged shape/argument/resource error, without I/O.
-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">>]