Scala API

class libtmux-scala latest

Server

Package i.g.l.s.cats io.github.libtmux.scaladsl.cats

A tmux server whose operations run in the effect type F .

View as Markdown

Source and package

Module: io.github.libtmux.scaladsl.cats
Package: io.github.libtmux:libtmux-scala_3
Source: libtmux-scala-cats/src/main/scala/io/github/libtmux/scaladsl/cats/Server.scala
Other languages: Python Ruby Lua TypeScript Rust Go Java C#C++Swift Kotlin F#

final class Server[F[_]]object Server class [source] ¶

Description#

Acquire it with Server.resource , or borrow a Java client with Server.fromJava . Releasing the Resource cancels this scope's operations and closes an owned client. Cancellation does not roll back commands already sent to tmux, and closing the client does not stop the tmux server.

Examples#

Connect to a private tmux server. Use JDK 25, Git, and tmux 3.2a through 3.7c on Linux, with /bin/cat and /bin/sh available. In an empty directory, fetch the documented library revision:

$ git clone https://github.com/libtmux/libtmux-java.git libtmux-source && \
  git -C libtmux-source checkout f56392b5d9bc7f1f9c1631842333fb90f3d82d40

Save this consumer setup as settings.gradle.kts: View source

rootProject.name = "api-example"

includeBuild("libtmux-source") {
    dependencySubstitution {
        substitute(module("io.github.libtmux:libtmux-scala-cats_3"))
            .using(project(":libtmux-scala-cats"))
    }
}

Save this consumer setup as build.gradle.kts: View source

plugins {
    scala
    application
}

repositories { mavenCentral() }

dependencies {
    implementation("io.github.libtmux:libtmux-scala-cats_3:0.0.1-alpha.17-SNAPSHOT")
    implementation("org.scala-lang:scala3-library_3:3.9.0")
}

java { toolchain { languageVersion.set(JavaLanguageVersion.of(25)) } }

application { mainClass.set(providers.gradleProperty("exampleMain")) }

Save this consumer setup as gradle.properties: View source

org.gradle.jvmargs=-Xmx2g -XX:MaxMetaspaceSize=768m -Dfile.encoding=UTF-8
kotlin.daemon.jvmargs=-Xmx2g
org.gradle.workers.max=2

Save this launcher as run.sh. It creates and stops a private tmux server, including after program failure. A shutdown failure retains its socket directory and exits unsuccessfully. View source

#!/bin/sh
set -eu

if [ "$#" -eq 0 ]; then
    printf 'Usage: sh run.sh program [arguments...]\n' >&2
    exit 2
fi
binary=$(command -v "${TMUX_BIN:-tmux}")
mkdir -p /tmp/libtmux-java-dev
directory=$(mktemp -d /tmp/libtmux-java-dev/api.XXXXXX)
socket="$directory/tmux.sock"
config="$directory/tmux.conf"

alive() {
    "$binary" -S "$socket" display-message -p '#{pid}' >/dev/null 2>&1
}

cleanup() {
    status=$?
    trap - 0 HUP INT TERM
    if alive; then
        if ! "$binary" -S "$socket" kill-server; then
            printf 'Cannot stop tmux; kept %s\n' "$directory" >&2
            exit 1
        fi
        attempts=0
        while alive && [ "$attempts" -lt 100 ]; do
            sleep 0.05
            attempts=$((attempts + 1))
        done
        if alive; then
            printf 'tmux is still responding; kept %s\n' "$directory" >&2
            exit 1
        fi
    fi
    rm -rf "$directory" || exit 1
    exit "$status"
}
trap cleanup 0
trap 'exit 1' HUP INT TERM

unset TMUX TMUX_PANE
printf 'set-option -g default-shell /bin/sh\n' > "$config"
"$binary" -S "$socket" -f "$config" new-session -d -s work-one -n editor /bin/cat
"$binary" -S "$socket" split-window -h -t '=work-one:editor' /bin/cat
"$binary" -S "$socket" new-window -d -t '=work-one' -n logs /bin/cat
"$binary" -S "$socket" new-session -d -s work-two -n editor /bin/cat
"$@" "$binary" "$socket" "$config"
"$binary" -S "$socket" has-session -t '=work-one'
"$binary" -S "$socket" has-session -t '=work-two'

Save this complete program as src/main/scala/Connect.scala. It opens an ordinary client for the launcher's server; closing the client releases its transport. View source

package io.github.libtmux.examples.api.scalacats

import io.github.libtmux.{ServerConfig, ServerEndpoint}
import java.nio.file.Path
import io.github.libtmux.scaladsl.cats.*
import _root_.cats.effect.{ExitCode, IO, IOApp}
import _root_.cats.syntax.all.*

/** Connect to a private tmux server. */
object Connect extends IOApp {
  def run(args: List[String]): IO[ExitCode] = {
    val program = IO {
      require(args.length == 3, "expected: tmux-binary socket-path config-file")
      ServerConfig
        .builder()
        .binary(args(0))
        .endpoint(ServerEndpoint.socketPath(Path.of(args(1))))
        .configFile(Path.of(args(2)))
        .build()
    }.flatMap { config =>
      Server.resource[IO](config).use { server =>
        for {
          alive <- server.isAlive()
          _ <- IO.println(s"connected=$alive")
        } yield ()
      }
    }
    program.as(ExitCode.Success).handleErrorWith { error =>
      IO(System.err.println("Example failed: " + error.getMessage))
        .as(ExitCode.Error)
    }
  }
}

Build the minimal consumer and run the saved program with the private fixture. An operation or cleanup error makes the command exit unsuccessfully:

$ ./libtmux-source/gradlew --project-dir . --console=plain --quiet \
    installDist -PexampleMain=io.github.libtmux.examples.api.scalacats.Connect && \
  sh run.sh build/install/api-example/bin/api-example

Expected output:

connected=true

In other ports A tmux server

Python libtmux.Server
Ruby LibTmux::Server
Lua libtmux.Server
TypeScript server.Server
Rust server.Server
Go tmux.Server
Java io.github.libtmux.Server
C# LibTmux.Server
C++ libtmux::Server
Swift Server
Kotlin io.github.libtmux.kotlin.Server
F# No source-verified F# equivalent is recorded for this operation.

Members43 members#

Collections and queries6 members#

sessions method The sessions this expression matches, captured now.
windows method Captures every winlink, preserving each session and index placement.
panes method Captures every pane on the server.
clients method Captures every attached client.
buffers method The server's paste buffers, which every session shares.
snapshot method Captures the whole hierarchy in at most four listings, retrying once if the server is replaced.

Common operations4 members#

newSession method Creates a detached session and returns that exact session.
killServer method Ends the tmux server and every session on it.
resource method Owns a Java client, with one to four simultaneous facade calls. Release cancels queued and running operations before closing the client.
fromJava method Borrows Java without closing it. The bound covers this facade only; transport capacity and interruption remain the owner's responsibility.

Other members33 members#

admissionBound method How many tmux commands this server's transport runs at once, from ServerConfig#maxConcurrentCommands() for a server #opened here.
asJava property The Java client this wraps: the one escape hatch, as on every handle.
attachedSessions method Captures every session a client is attached to.
batch method An immutable batch plan; each run dispatches a fresh Java Batch through this server's Execution.
chain method An immutable chain plan using tmux's evolving current target; each run dispatches a fresh Java CommandChain through this server's Execution.
channel method One of tmux's wait-for channels, named once.
cmd method Runs one tmux command against this server.
commands method The commands this tmux knows.
config method How this server was configured.
environment method The server's environment, which every session inherits and every new process is given.
expand method Expands a tmux format against the server, and answers with what it came to.
globalOptions method The global session options every session inherits unless it sets its own.
hasSession method Whether a session with this name exists.
hooks method The global hooks every session inherits.
identity method Which server this is.
isAlive method Whether the server is running and answering.
keys method The server's key bindings: prefix when binding, every table when listing.
killSession method Ends the session with this name, and everything in it.
lock method Locks every client attached to this server.
messageLog method The server's message log.
options method The server-wide options, the ones tmux keeps once per server.
pane method The one pane this expression matches, captured now, or empty when none does.
paneFields method Chosen fields for every pane on the server, from one listing.
prompt method The command prompt's history.
requireAlive method Requires a running tmux daemon that answers the liveness probe.
run method Runs a command that is expected to work, and raises when it did not.
session method The one session this expression matches, captured now, or empty when none does.
shell method Shell commands run by tmux, and tmux commands chosen by a shell exit status.
sourceFile method Runs a file of tmux commands, as a configuration file would be run.
toBuilder method A builder holding every configuration and ownership choice this server made.
variables method Reads only validated tmux variable names, never caller-authored format syntax.
version method Which tmux this server is running.
window method The one window link this expression matches, captured now, or empty when none does.

Scripting & web

Compiled & native

JVM

.NET

tmux

Server

Description#

Examples#

Members43 members#

Collections and queries6 members#

Common operations4 members#

Other members33 members#

Description#

Examples#

Members43 members#

Collections and queries6 members#

Common operations4 members#

Other members33 members#

Related types#