Crate tmux_interface

Expand description

tmux_interface is a library for communication with TMUX via CLI.

§On This Page

1. Description
1. Quick Start
1. Package Compilation Features
- 3.1. Tmux Version
- 3.2. Tmux Command Alias
- 3.3. Repository
  - 3.3.1 Using Crates Repository
  - 3.3.2 Using Local Repository
  - 3.3.3 Using Remote Repository
1. Modules Overview
1. Modules and Levels Hierarchy
- 5.1. Level Explanations and Examples
  - 5.1.0 Level 0: Operating System
  - 5.1.1 Level 1: Standard Library - Process
  - 5.1.2 Level 2: TmuxInterface Library - TmuxCommand
  - 5.1.3 Level 3: TmuxInterface Library - Tmux Command Structures
  - 5.1.4 Level 4: TmuxInterface Library - Options, Variables
  - 5.1.5 Level 5: TmuxInterface Library - Control Mode

§1. Description

Main purpose of the tmux_interface library is to implement simple sending and receiving data mechanisms for intercommunication with TMUX only via standard streams (stdin, stdout, stderr).

§2. Quick Start

Add a dependency in your Cargo.toml. Versions below 1.0.0 are mostly for development and testing purposes (use them in your projects on your own risk, further versions may have different API).
```
[dependencies]
tmux_interface = "1.0.0"
```
Add extern crate in your source file.
```
extern crate tmux_interface;
```

Use it’s functions

§Example 1

use tmux_interface::{HasSession, KillSession, NewSession, NewWindow, SplitWindow, Tmux};

let target_session = "example_1";

// tmux new -d -s example_1 ; neww ; splitw -v
Tmux::new()
    .add_command(NewSession::new().detached().session_name(target_session))
    .add_command(NewWindow::new())
    .add_command(SplitWindow::new().vertical())
    .output()
    .unwrap();

// tmux has -t example_1
let status = Tmux::with_command(HasSession::new().target_session(target_session))
    .status()
    .unwrap()
    .success();

assert!(status);

// tmux kill-session -t example_1
Tmux::with_command(KillSession::new().target_session(target_session))
    .output()
    .unwrap();

§3. Package Compilation Features

§3.1 Tmux Version

Different tmux versions may have incompatible CLI changes. Following versions features are currently supported:

Table 3.1: Cargo.toml features list with corresponding tmux versions

Feature Name	Tmux Version	CI Tests	Comment
`tmux_0_8`	`tmux 0.8`
`tmux_0_9`	`tmux 0.9`
`tmux_1_0`	`tmux 1.0`
`tmux_1_1`	`tmux 1.1`
`tmux_1_2`	`tmux 1.2`
`tmux_1_3`	`tmux 1.3`
`tmux_1_4`	`tmux 1.4`
`tmux_1_5`	`tmux 1.5`
`tmux_1_6`	`tmux 1.6`		Ubuntu 11.04 LTS Precise Pangolin, CentOS 6
`tmux_1_7`	`tmux 1.7`		Ubuntu 14.04 LTS Trusty Tahr, CentOS 7
`tmux_1_8`	`tmux 1.8`	x
`tmux_1_9`	`tmux 1.9`	x	Debian Jessie
`tmux_1_9a`	`tmux 1.9a`	x
`tmux_2_0`	`tmux 2.0`	x
`tmux_2_1`	`tmux 2.1`	x	Ubuntu 16.04 LTS Xenial Xerus
`tmux_2_2`	`tmux 2.2`	x
`tmux_2_3`	`tmux 2.3`	x	Debian Stretch
`tmux_2_4`	`tmux 2.4`	x
`tmux_2_5`	`tmux 2.5`	x
`tmux_2_6`	`tmux 2.6`	x	Ubuntu 18.04 LTS Bionic Beaver
`tmux_2_7`	`tmux 2.7`	x	CentOS 8
`tmux_2_8`	`tmux 2.8`	x	Debian Buster
`tmux_2_9`	`tmux 2.9`	x
`tmux_2_9a`	`tmux 2.9a`	x
`tmux_3_0`	`tmux 3.0`	x
`tmux_3_0a`	`tmux 3.0a`	x	Ubuntu 20.04 LTS Focal Fossa
`tmux_3_1`	`tmux 3.1`	x
`tmux_3_1a`	`tmux 3.1a`	x
`tmux_3_1b`	`tmux 3.1b`	x
`tmux_3_1c`	`tmux 3.1c`	x	Debian Bullseye
`tmux_3_2`	`tmux 3.2`	x
`tmux_3_2a`	`tmux 3.2a`	x	Ubuntu 22.04 LTS Jammy Jellyfish, CentOS 9
`tmux_3_3`	`tmux 3.3`	x
`tmux_3_3a`	`tmux 3.3a`	x	Debian Bookworm, Ubuntu 23.04 LTS Lunar Lobster
`tmux_3_4`	`tmux 3.4`	x	Debian experimental, Ubuntu 24.04 LTS Noble Numbat
`tmux_X_X`		x	tmux: `main` branch; library: `dev` branch

`tmux_stable`	`tmux 3.3`
`tmux_latest`	`tmux 3.3a`

[dependencies]
tmux_interface = {
 version = "^0.1.0",
 features = ["tmux_2_6"]
}

By default tmux_stable is used. It can be removed with --no-default-features cargo command line option or with default-features = false option in Cargo.toml You can also add features to your dependencies entry in Cargo.toml, if you want to specify the version of tmux you want to use.

[dependencies]
tmux_interface = {
 version = "^0.1.0",
 default-features = false,
 features = ["tmux_2_6"]
}

§3.2. Tmux Command Alias

cmd_alias use alias instead of full tmux command name (e.g. list-sessions -> ls). Enabled by default.

§3.3. Repository

§3.3.1. Using Crates Repository

[dependencies]
tmux_interface = {
 version = "0.0.7",
}

§3.3.2. Using Local Repository

[dependencies]
tmux_interface = {
 version = "0.0.7",
 path = "../tmux-interface"
}

§3.3.3. Using Remote Repository

tmux_interface = {
 git = "https://github.com/AntonGepting/tmux-interface-rs.git",
 branch = "dev"
}

§4. Modules Overview

Commands (commands)
- Clients and Sessions (clients_and_sessions)
- Windows and Panes (windows_and_panes)
- Key Bindings (key_bindings)
- Options (options)
- Hooks (hooks)
- Global and Session Environment (global_and_session_environment)
- Status Line (status_line)
- Buffers (buffers)
- Miscellaneous (miscellaneous)
- …
- Common (common)
- TmuxCommand (TmuxCommand), TmuxCommands (TmuxCommands)
- Tmux (Tmux)
- …
Modes
- Default Mode
- Control Mode (control_mode)
  - (unimplemented, draft)
- Copy Mode
  - (unimplemented, draft)
- Command Mode
  - (unimplemented)
- Clock Mode
  - (unimplemented)
Formats (formats)
- Formats
- FormatsOutput
- Variable
- VariableOutput
- …
Options (options)
Styles (styles)
- StyleList
- Style
- …
Target (target)
- TargetSession
- TargetWindow
- TargetPane
- …
Variables (variables)
- Sessions
- Session
- Windows
- Window
- Panes
- Pane
- …
Error (Error)
…

§5. Modules and Levels Hierarchy

5. Tmux Objects Controller
 +---------+     +-----------+                             +-----+
 | Options |     | Variables |                             | ... |
 +---------+     +-----------+                             +-----+
 ...

4. Tmux Objects Getter/Setter
 +-----------------+                                       +-----+
 | GetServerOption |                                       | ... |
 +-----------------+                                       +-----+
 ...

3. Command Builder
 +------+     +------------+      +---------------+        +-----+
 | Tmux |     | NewSession |      | AttachSession |        | ... |
 +------+     +------------+      +---------------+        +-----+

2. Tmux Command
 +-------------+                  +------------+
 | TmuxCommand |                  | TmuxOutput |
 +-------------+                  +------------+
 +-----------------+
 | TmuxCommands    |
 +-----------------+

1. Standard Library
 +---------------------------------------+
 |        std::process::Command          |
 +---------------------------------------+
 +-----------+ +-----------+ +-----------+
 | .output() | | .spawn()  | | .status() |
 +-----------+ +-----------+ +-----------+

 Platform specific (Windows, UNIX, ...)
 +---------------------------------------+
 |             sys::process              |
 +---------------------------------------+
 +-----------+ +-------------------------+
 | .output() | |        .spawn()         |
 +-----------+ +-------------------------+

0. OS
 +--------+                      +-----------------+       +-----+
 | fork() |                      | CreateProcess() |       | ... |
 +--------+                      +-----------------+       +-----+

Figure 5: Schematic Levels and Modules Hierarchy

and thereby:

Each level allows to build practically the same command, but with more or less effort and advantages
Each level has some abstraction and some limitations
Each level is based on top of the previous one (uses APIs of the previous one)

§5.1. Level Explanations and Examples

Tmux command invocation can be described and accessed on different levels:

1. syscall fork(...), CreateProcess(...) - Operating System level abstraction

std::process::Command - Rust standard library level abstraction

OS independence
comfortable working low level
manually build commands using literals
hard coded literals

§Examples

use std::process::Command;

// tmux -2 -uv new-session -ADEd -s example_5_1_1
let output = Command::new("tmux")
    .args(["-2", "-uv", "new-session", "-ADEd", "-s", "example_5_1_1"])
    .output()
    .unwrap();

assert!(output.status.success());

// tmux -2 -uv kill-session -t example_5_1_1
let output = Command::new("tmux")
    .args(["-2", "-uv", "kill-session", "-t", "example_5_1_1"])
    .output()
    .unwrap();

assert!(output.status.success());

Listing 5.1.1: build tmux commands using std::process::Command

TmuxCommand, TmuxCommands - custom command abstraction

additional functionality for std::process::Command
allows to store additional information about commands such as:
- command alias (new), beside command name (new-session)
- short flag name (-l) and long flag name (--long-flag)
- custom separator, hyphen, etc… ( , -, --, =, ``)
runtime mechanisms for deciding and building short or long commands

§Examples

use tmux_interface::TmuxCommand;

// new-session -ADEd -s example_5_1_2
let mut new_session = TmuxCommand::new();
new_session
    .name("new-session")
    .push_flag_short('A')
    .push_flag_short('D')
    .push_flag_short('E')
    .push_flag_short('d')
    .arg("-s", "example_5_1_2");

// tmux -2uv new-session -ADEd -s example_5_1_2
let mut tmux = TmuxCommand::new();
tmux.name("tmux")
    .push_flag_short('2')
    .push_flag_short('u')
    .push_flag_short('v')
    .push_cmd(new_session)
    .combine_short_flags();

let output = tmux.to_command().output().unwrap();

assert!(output.status.success());

// kill-session -t example_5_1_2
let mut kill_session = TmuxCommand::new();
kill_session.name("kill-session").arg("-t", "example_5_1_2");

// tmux -2uv kill-session -t example_5_1_2
let mut tmux = TmuxCommand::new();
tmux.name("tmux")
    .push_flag_short('2')
    .push_flag_short('u')
    .push_flag_short('v')
    .push_cmd(kill_session)
    .combine_short_flags();

let output = tmux.to_command().output().unwrap();

assert!(output.status.success());

Listing 5.1.2: build tmux commands using tmux_interface::TmuxCommand

Tmux, NewSession, AttachSession … - tmux commands builder

structures, traits, implementations and methods as abstraction from literals
near to tmux naming as possible
build tmux commands
tmux commands can include binary name and arguments or nor for control mode
order of arguments doesn’t matter
using macros

§Examples

use tmux_interface::{KillSession, NewSession, Tmux};

let session_name = "example_5_1_3";

// tmux -2uv new-session -ADEd -s example_5_1_3
let tmux = Tmux::with_command(
    NewSession::new()
        .attach()
        .detach_other()
        .not_update_env()
        .detached()
        .session_name(session_name),
)
.colours256()
.force_utf8()
.verbose_logging();

let output = tmux.output().unwrap();

assert!(output.success());

// tmux -2uv kill-session -t example_5_1_3
let tmux = Tmux::with_command(KillSession::new().target_session(session_name))
    .colours256()
    .force_utf8()
    .verbose_logging();

let output = tmux.output().unwrap();

assert!(output.success());

Listing 5.1.3: build tmux commands using tmux_interface::{Tmux, NewSession, KillSession} structures

use tmux_interface::{kill_session, new_session, tmux};

let session_name = "example_5_1_4";

// tmux -2uv new-session -ADEd -s example_5_1_4
let tmux = tmux!(-2, -u, -v, new_session!(-A, -D, -E, -d, -s session_name));

let output = tmux.output().unwrap();

assert!(output.success());

// tmux -2uv kill-session -t example_5_1_4
let tmux = tmux!(-2, -u, -v, kill_session!(-t session_name));

let output = tmux.output().unwrap();

assert!(output.success());

Listing 5.1.4: build tmux commands using tmux_interface::{tmux, new_session, kill_session} macros

Options, Variables, Formats - tmux objects control
- accessing and using internal tmux instances
  - formats
  - options
  - variables
  - …
§Example
```
unimplemented!();
```
TmuxInterface - tmux control
- setting/getting methods abstraction, just an object with it’s attributes
- offline/online working (default/control mode)
- mapping of whole tmux with it’s all internal instances as an object in Rust
§Example
```
unimplemented!();
```

Re-exports§

pub use error::Error;
pub use commands::*;
pub use control_mode::*;
pub use formats::*;
pub use options::*;
pub use styles::*;
pub use target::*;
pub use variables::*;

Modules§

commands: The commands module contains functions for building and executing tmux commands
control_mode: The control_mode module contains functions for working in control mode of tmux
copy_mode
error
formats: The formats module contains functions for working with tmux formats
options: Command builders and output parsers
styles
target: The target module contains functions for building targets for tmux commands
variables: The variables module contains functions for getting variables from tmux

Macros§

attach_session: Attach client to already existing session
bind_key: Bind key key to command
break_pane: Break src-pane off from its containing window to make it the only pane in dst-window
capture_pane: Capture the contents of a pane
choose_buffer: Structure for putting a pane into buffer mode
choose_client: Put a pane into client mode, allowing a client to be selected interactively from a list
choose_tree: Put a pane into tree mode, where a session, window or pane may be chosen interactively from a list
clear_history: Remove and free the history for the specified pane.
clear_prompt_history: Clear status prompt history
clock_mode: Display a large clock
command_prompt: Open the command prompt in a client
confirm_before: Ask for confirmation before executing command
copy_mode: Enter copy mode
customize_mode: Put a pane into customize mode
delete_buffer: Delete the buffer named buffer-name, or the most recently added automatically named buffer if not specified.
detach_client: Detach the current client
display_menu: Display a menu on target-client
display_message: Display a message
display_panes: Display a visible indicator of each pane shown by target-client
display_popup: Display a menu on target-client
find_window: Search for the fnmatch(3) pattern match-string in window names, titles, and visible content (but not history)
has_session: Report if the specified session exist
if_shell: Conditional commands executing
join_pane: Like split-window, but instead of splitting dst-pane and creating a new pane, split it and move src-pane into the space
kill_pane: Destroy the given pane
kill_server: Kill the tmux server and clients and destroy all sessions
kill_session: Destroy the given session
kill_window: Kill the current window or the window at target-window, removing it from any sessions to which it is linked
last_pane: Select the last (previously selected) pane
last_window: Select the last (previously selected) window
link_window: Link the window at src-window to the specified dst-window
list_buffers: List the global buffers.
list_clients: List all clients attached to the server
list_commands: List the syntax of all commands supported by tmux
list_keys: List key bindings
list_panes: List panes on the server
list_sessions: List all sessions managed by the server
list_windows: List windows on the server
load_buffer: Load the contents of the specified paste buffer from path.
lock_client: Lock target-client
lock_server: Lock each client individually
lock_session: Lock all clients attached to target-session
move_pane: Like join-pane, but src-pane and dst-pane may belong to the same window
move_window: This is similar to link-window, except the window at src-window is moved to dst-window
new_session: Create new session
new_window: Create new window
next_layout: Move a window to the next layout and rearrange the panes to fit
next_window: Move to the next window in the session
paste_buffer: Structure for inserting the contents of a paste buffer into the specified pane
pipe_pane: Pipe output sent by the program in target-pane to a shell command or vice versa
previous_layout: Move to the previous layout in the session
previous_window: Move to the previous window in the session
refresh_client: Refresh current client
rename_session: Rename the session to new-name
rename_window: Rename the current window, or the window at target-window if specified, to new-name
resize_pane: Resize a pane, up, down, left or right
resize_window: Resize a window, up, down, left or right
respawn_pane: Reactivate a pane in which the command has exited
respawn_window: Reactivate a window in which the command has exited
rotate_window: Rotate the positions of the panes within a window
run_shell: Execute shell-command using /bin/sh
save_buffer: Save the contents of the specified paste buffer to path.
select_layout: Choose a specific layout for a window
select_pane: Make pane target-pane the active pane in window target-window
select_window: Select the window at target-window.
send_keys: Send a key or keys to a window
send_prefix: Send the prefix key
server_access: Change the access or read/write permission of user
set_buffer: Set the contents of the specified buffer to data.
set_environment: Set or unset an environment variable
set_hook: Set or unset hook hook-name to command.
set_option: Set a pane/window/session/server option
show_buffer: Display the contents of the specified buffer.
show_environment: Display the environment variables
show_hooks: Shows hooks
show_messages: Show client messages or server information
show_options: Show options
show_prompt_history: Display status prompt history
source_file: Execute commands from path
split_window: Create a new pane by splitting target-pane
start_server: Start the tmux server, if not already running, without creating any sessions
suspend_client: Suspend a client by sending SIGTSTP (tty stop)
swap_pane: Swap two panes
swap_window: This is similar to link-window, except the source and destination windows are swapped
switch_client: Switch the current session for client target-client to target-session
tmux: man tmux
unbind_key: Unbind the command bound to key
unlink_window: Unlink target-window
wait_for: Prevent the client from exiting