C++ API

method libtmux-cxx latest

Pane.wait_for_text

Wait until this pane produces wanted, rather than until it merely appears on screen.

Source and package

Qualified name: libtmux::Pane::wait_for_text
Namespace: libtmux
Declared in: Pane
Package: libtmux-cxx
Source: include/libtmux/entities.hpp

[[C++ nodiscard attributeAsks the compiler to warn when a result is discarded. An explicit cast to void acknowledges that the result is intentionally ignored.Language documentation]] expected<WaitResult, CommandFailure> wait_for_text(std::string_view wanted, const WaitOptions& options = {}) const; method readonly [source] ¶

Description#

Prefers the control stream's %output and falls back to re-reading the screen when no connection can be opened; WaitOptions says which, and WaitResult::path says which answered. A caller that typed the text it is waiting for names it in WaitOptions::sent, or the shell's echo of its own command is credited to the pane as output.

Examples#

Send input and capture confirmed output. Start a small shell reader with terminal echo disabled, wait for readiness, send one line, and capture its response. The two bounded waits prevent startup races and confirm output from the program. The final cat keeps the pane available for capture until cleanup. libtmux-cxx is not published to a package registry yet, so this builds it from its repository. Use Clang 18 or newer with libc++, CMake 3.25 or newer, Ninja, Git, and tmux 3.3a or newer on Linux. In an empty directory, fetch the documented library revision:

$ git clone https://github.com/libtmux/libtmux-cxx.git libtmux-source && \
  git -C libtmux-source checkout 542fdc204ff3cfa56f5484327cda0c69bad2307d

Build and install the C++23 library and its public testing component into this directory:

$ cmake -S libtmux-source -B libtmux-build -G Ninja \
    -DCMAKE_TOOLCHAIN_FILE="$PWD/libtmux-source/cmake/toolchains/clang-libcxx.cmake" \
    -DCMAKE_C_COMPILER=clang \
    -DCMAKE_CXX_COMPILER=clang++ \
    -DCMAKE_BUILD_TYPE=Release \
    -DLIBTMUX_BUILD_TESTS=OFF \
    -DLIBTMUX_BUILD_EXAMPLES=OFF \
    -DLIBTMUX_BUILD_TESTING_LIBRARY=ON && \
  cmake --build libtmux-build --parallel 2 && \
  cmake --install libtmux-build --prefix "$PWD/libtmux-prefix"

Save this complete consumer project as CMakeLists.txt: View source

cmake_minimum_required(VERSION 3.25)
project(libtmux_api_example LANGUAGES CXX)

find_package(libtmux REQUIRED COMPONENTS testing)

add_executable(api_example main.cpp)
target_link_libraries(api_example PRIVATE libtmux::libtmux libtmux::testing)

Save this complete program as main.cpp. ScopedTmuxServer owns a private daemon and stops it when the program exits. Ordinary applications use Server for their own socket; these examples use the fixture until setup moves to ordinary server objects. View source

#include <algorithm>
#include <chrono>
#include <cstdio>
#include <ranges>

#include <libtmux/libtmux.hpp>
#include <libtmux/testing/scoped_server.hpp>

int main() {
  // The fixture owns this private server and cleans it up on every return path.
  auto fixture = libtmux::test::ScopedTmuxServer::start({
      .session_name = "api",
      .socket_namespace = libtmux::test::SocketNamespace::consumer("api"),
  });
  if (!fixture.has_value()) {
    std::fprintf(stderr, "%s\n", fixture.error().c_str());
    return 1;
  }
  auto server = libtmux::Server::at_socket_path(fixture->socket_path());
  if (!server.has_value()) {
    std::fprintf(stderr, "%s\n", server.error().diagnostic.c_str());
    return 1;
  }

  const auto sessions = server->sessions();
  if (!sessions.has_value()) {
    std::fprintf(stderr, "%s\n", sessions.error().diagnostic.c_str());
    return 1;
  }
  if (sessions->size() != 1) {
    std::fputs("expected one session\n", stderr);
    return 1;
  }
  const auto window = sessions->front().new_window(libtmux::NewWindowOptions{
      .name = "reader",
      .shell_command = R"(exec sh -c '
        stty -echo
        printf "ready\n"
        IFS= read -r line
        printf "got:%s\n" "$line"
        exec cat >/dev/null
      ')",
  });
  if (!window.has_value()) {
    std::fprintf(stderr, "%s\n", window.error().diagnostic.c_str());
    return 1;
  }
  const auto pane = window->active_pane();
  if (!pane.has_value()) {
    std::fprintf(stderr, "%s\n", pane.error().diagnostic.c_str());
    return 1;
  }
  const auto ready = pane->wait_for_text("ready", {.timeout = std::chrono::seconds{5}});
  if (!ready.has_value()) {
    std::fprintf(stderr, "%s\n", ready.error().diagnostic.c_str());
    return 1;
  }
  if (!ready->matched) {
    std::fputs("reader did not become ready\n", stderr);
    return 1;
  }
  const auto text = pane->send_text("hello ");
  if (!text.has_value()) {
    std::fprintf(stderr, "%s\n", text.error().diagnostic.c_str());
    return 1;
  }
  const auto line = pane->send_line("C++");
  if (!line.has_value()) {
    std::fprintf(stderr, "%s\n", line.error().diagnostic.c_str());
    return 1;
  }
  const auto answered =
      pane->wait_for_text("got:hello C++", {.timeout = std::chrono::seconds{5}});
  if (!answered.has_value()) {
    std::fprintf(stderr, "%s\n", answered.error().diagnostic.c_str());
    return 1;
  }
  if (!answered->matched) {
    std::fputs("reader did not confirm the input\n", stderr);
    return 1;
  }
  const auto captured = pane->capture();
  if (!captured.has_value()) {
    std::fprintf(stderr, "%s\n", captured.error().diagnostic.c_str());
    return 1;
  }
  // The captured string outlives the line views returned by capture_lines.
  const auto lines = libtmux::capture_lines(*captured);
  if (std::ranges::find(lines, "got:hello C++") == std::ranges::end(lines)) {
    std::fputs("captured output does not contain the response\n", stderr);
    return 1;
  }
  std::puts("got:hello C++");
  return 0;
}

Build against the installed library and run the saved program. An operation error produces a failing exit status:

$ cmake -S . -B build -G Ninja \
    -DCMAKE_PREFIX_PATH="$PWD/libtmux-prefix" \
    -DCMAKE_CXX_COMPILER=clang++ \
    -DCMAKE_CXX_FLAGS=-stdlib=libc++ && \
  cmake --build build --parallel 2 && \
  ./build/api_example

Expected output:

got:hello C++

Parameters

wanted (std::string_view) #
options (const WaitOptions &) #

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

Pane.wait_for_text

Description#

Examples#

Description#

Examples#

Related types#