Core LibraryAPI Reference

Choose documentation 1

latest

Current version

latest
English

Prerelease This site documents an alpha of libtmux. Its structure, URLs and APIs are subject to change.

method libtmux-scala latest

Pane.awaitText

Package io.github.libtmux.scaladsl.cats.Pane.awaitText io.github.libtmux.scaladsl.cats

Waits until text appears, or timeout passes first.

View as Markdown

Source and package
Module
io.github.libtmux.scaladsl.cats
Declared in
Pane
Package
io.github.libtmux:libtmux-scala_3
Source
libtmux-scala-cats/src/main/scala/io/github/libtmux/scaladsl/cats/Handles.scala
Scala extension methods Adds methods callable on the receiver type without changing its definition. Language documentation [F[_]](self: Pane[F])(using F: Async[F]) Scala method declarations Declares a method, with its name, parameter lists and return type. Language documentation awaitText( text: String, timeout: scala.concurrent.duration.FiniteDuration ): F[io.github.libtmux.TextOutcome] Scala extension methods Adds methods callable on the receiver type without changing its definition. Language documentation [F[_]](self: Pane[F])(using F: Async[F]) Scala method declarations Declares a method, with its name, parameter lists and return type. Language documentation awaitText( text: String, timeout: scala.concurrent.duration.FiniteDuration, every: scala.concurrent.duration.FiniteDuration ): F[io.github.libtmux.TextOutcome]
methodoverload2 overloads [source]

Examples#

Send input and wait for output before capturing the pane. 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:

Terminal window
$ 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/Capture.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,
SessionSpec,
TextOutcome
}
import java.nio.file.Path
import io.github.libtmux.scaladsl.cats.*
import scala.concurrent.duration.*
import _root_.cats.effect.{ExitCode, IO, IOApp}
import _root_.cats.syntax.all.*
/** Send input and wait for output before capturing the pane. */
object Capture 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 {
session <- server.newSession(
SessionSpec
.builder()
.named("api-capture")
.running("/bin/sh")
.build()
)
pane = session.windows.head.panes.head
_ <- pane.sendKeys(Vector("printf 'api-%s\\n' keys", "Enter"))
keys <- pane.awaitText("api-keys", 5.seconds)
_ <- IO.raiseWhen(keys.equals(TextOutcome.TIMED_OUT))(
new IllegalStateException("timed out waiting for keys output")
)
_ <- pane.sendLine("printf 'api-%s\\n' line")
line <- pane.awaitText("api-line", 5.seconds)
_ <- IO.raiseWhen(line.equals(TextOutcome.TIMED_OUT))(
new IllegalStateException("timed out waiting for line output")
)
lines <- pane.capture()
_ <- Vector("api-keys", "api-line").traverse_ { expected =>
IO.raiseUnless(lines.exists(_.trim.equals(expected)))(
new IllegalStateException("capture is missing " + expected)
) *> IO.println(expected)
}
} 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:

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

Expected output:

api-keys
api-line
Parameters
Esc

Type to search.