Crate tmux_interface

source ·
Expand description

tmux_interface is a library for communication with TMUX via CLI.

On This Page

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

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

  2. Add extern crate in your source file.

    extern crate tmux_interface;

  3. 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 NameTmux VersionCI TestsComment
tmux_0_8tmux 0.8
tmux_0_9tmux 0.9
tmux_1_0tmux 1.0
tmux_1_1tmux 1.1
tmux_1_2tmux 1.2
tmux_1_3tmux 1.3
tmux_1_4tmux 1.4
tmux_1_5tmux 1.5
tmux_1_6tmux 1.6Ubuntu 11.04 LTS Precise Pangolin, CentOS 6
tmux_1_7tmux 1.7Ubuntu 14.04 LTS Trusty Tahr, CentOS 7
tmux_1_8tmux 1.8x
tmux_1_9tmux 1.9xDebian Jessie
tmux_1_9atmux 1.9ax
tmux_2_0tmux 2.0x
tmux_2_1tmux 2.1xUbuntu 16.04 LTS Xenial Xerus
tmux_2_2tmux 2.2x
tmux_2_3tmux 2.3xDebian Stretch
tmux_2_4tmux 2.4x
tmux_2_5tmux 2.5x
tmux_2_6tmux 2.6xUbuntu 18.04 LTS Bionic Beaver
tmux_2_7tmux 2.7xCentOS 8
tmux_2_8tmux 2.8xDebian Buster
tmux_2_9tmux 2.9x
tmux_2_9atmux 2.9ax
tmux_3_0tmux 3.0x
tmux_3_0atmux 3.0axDebian Bullseye
tmux_3_1tmux 3.1xDebian experimental
tmux_3_1atmux 3.1ax
tmux_3_1btmux 3.1bx
tmux_3_1ctmux 3.1cx
tmux_3_2tmux 3.2x
tmux_3_2atmux 3.2ax
tmux_3_3tmux 3.3x
tmux_3_3atmux 3.3ax
tmux_X_Xxtmux: main branch; library: dev branch
tmux_stabletmux 3.3
tmux_latesttmux 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

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

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

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

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

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

Modules

Macros