tmux_session (libtmux for Erlang v0.0.1)

View Source

Create and observe sessions, or act on a session's registered stable ID.

create/2 accepts name, window_name, width, height, cwd, env, launch and detach. Creation defaults to detached with tmux's configured shell/command. launch is default_shell, an argv map, or an explicit shell map. env augments tmux's inherited environment. tmux supplies PATH, SHELL, PWD and TMUX_PANE after that merge, so those entries may be replaced. Names and cwd are literal format values; tmux's stored name rules still apply. Creation never adopts an existing session by name.

An empty shell command can exit immediately and remove its session. It does not request the empty-pane behavior of split-window. Use a running program when later operations require the session to remain alive.

create/2 and get/2 explicitly read the new/current row through several one-shot commands. These reads are not atomic. If creation succeeds but observation fails, the error retains mutation = completed and the original command result. rename/2 and kill/1 return command results without refreshing the input record. Detached rows require tmux_server:bind/2 before actions. rename_command/2 builds a reusable value without tmux I/O; the other calls perform I/O after validation.

select/2 switches one explicitly named attached client to a session. It never attaches a client or infers the current client. Use tmux_window_link:select/1 to select a session's window membership instead.

Summary

Types

Session creation options. Launch defaults to the configured shell; creation defaults to detached.

Session selection options. update_environment defaults to false, preserving the destination environment.

Functions

Create a detached session by default and explicitly observe the returned row. Options include name, window_name, dimensions, cwd, env and launch. Performs I/O; an observation failure after successful creation retains mutation = completed and the original command result. Existing names are not adopted.

Read fresh session fields through explicit one-shot commands. The session ID is stable within the observed server incarnation. Returns target_gone when tmux no longer has that session; it never refreshes an existing record.

Destroy this registered session. Performs I/O and returns the command result; this is a destructive session action, not endpoint cleanup. References must belong to a live registered owner.

Rename the registered session using a literal name and return the command result. Performs I/O. Previously captured records keep their old names; detached or stale references fail validation before the action.

Build a literal rename command without tmux I/O. Validates the row and keeps its captured origin; endpoint liveness is checked during execution. Submit the value to tmux_server:command/3 or tmux_operation:start/3 with its original endpoint. Existing session records retain their captured name.

Switch an explicitly named attached client to this registered session, preserving the session environment. Performs I/O. See select/3 for client lookup, environment updates and disconnection races.

Switch one attached client, selected by its literal native client name or TTY path, to the session's registered stable ID. Performs I/O and returns the command result; existing rows remain captured values. Obtain the name from the caller's own client context, such as tmux's client_name format. There is no default client and this call never attaches one.

Types

create_options()

-type create_options() ::
          #{name => binary(),
            window_name => binary(),
            width => 1..65535,
            height => 1..65535,
            cwd => binary(),
            env => #{binary() => binary()},
            launch => tmux_command:launch_spec(),
            detach => boolean()}.

Session creation options. Launch defaults to the configured shell; creation defaults to detached.

select_options()

-type select_options() :: #{update_environment => boolean()}.

Session selection options. update_environment defaults to false, preserving the destination environment.

Functions

create(Server, Options)

-spec create(tmux_server:t(), create_options()) -> {ok, tmux_model:session()} | {error, map()}.

Create a detached session by default and explicitly observe the returned row. Options include name, window_name, dimensions, cwd, env and launch. Performs I/O; an observation failure after successful creation retains mutation = completed and the original command result. Existing names are not adopted.

get(Server, Id)

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

Read fresh session fields through explicit one-shot commands. The session ID is stable within the observed server incarnation. Returns target_gone when tmux no longer has that session; it never refreshes an existing record.

kill(Session)

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

Destroy this registered session. Performs I/O and returns the command result; this is a destructive session action, not endpoint cleanup. References must belong to a live registered owner.

rename(Session, Name)

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

Rename the registered session using a literal name and return the command result. Performs I/O. Previously captured records keep their old names; detached or stale references fail validation before the action.

rename_command(Session, Name)

-spec rename_command(tmux_model:session(), binary()) -> {ok, tmux_command:t()} | {error, map()}.

Build a literal rename command without tmux I/O. Validates the row and keeps its captured origin; endpoint liveness is checked during execution. Submit the value to tmux_server:command/3 or tmux_operation:start/3 with its original endpoint. Existing session records retain their captured name.

Detached rows require tmux_server:bind/2 first. Building a command does not execute it or make a repeated mutation safe.

1> tmux_session:rename_command(invalid_row, <<"work">>).
{error,#{code => invalid_row,path => []}}

select(Session, Client)

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

Switch an explicitly named attached client to this registered session, preserving the session environment. Performs I/O. See select/3 for client lookup, environment updates and disconnection races.

An empty client name cannot select an implicit current client:

1> tmux_session:select(invalid_session, <<>>).
{error,#{code => invalid_client,path => [client]}}

select(Session, Client, Options)

-spec select(tmux_model:session(), binary(), select_options()) -> {ok, map()} | {error, map()}.

Switch one attached client, selected by its literal native client name or TTY path, to the session's registered stable ID. Performs I/O and returns the command result; existing rows remain captured values. Obtain the name from the caller's own client context, such as tmux's client_name format. There is no default client and this call never attaches one.

update_environment defaults to false (switch-client -E). When true, tmux updates the destination session environment using its update-environment option and that client's environment; listed variables absent from the client can be marked for removal. Running pane processes retain their environment.

Names are nonempty NUL-free binaries of at most 32 KiB. Trailing-colon aliases are rejected. Native lookup matches an exact name or TTY path, including its /dev/-relative alias; there is no prefix or pattern matching. A disconnected name returns client_not_found. Names and TTY paths can be reused by a later connection; this API does not identify a client incarnation atomically. A missing destination returns target_gone. See tmux_server:bind/2 for detached session rows and tmux_window_link:select/1 for window selection.