C++ API

function libtmux-cxx latest

capture_lines

The lines are views into the text, so text that dies at the semicolon takes them with it — and pane.capture() returns its output by value, which makes capture_lines(*pane.capture()) the natural thing to write and a use-after-free to run.

Source and package

Qualified name: libtmux::capture_lines
Namespace: libtmux
Package: libtmux-cxx
Source: include/libtmux/capture.hpp

template <typename Text> requires std::same_as<std::remove_cvref_t<Text>, std::string> && (!std::is_lvalue_reference_v<Text>) std::vector<std::string_view> capture_lines(Text&&) = delete;[[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]] std::vector<std::string_view> capture_lines(std::string_view output); function overload 2 overloads [source] ¶

Description#

Deleted for an rvalue string only: an lvalue string converts as before, and so does a literal.

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

Type parameters

Text # for capture_lines(Text &&)

Parameters

Text && # for capture_lines(Text &&)
output (std::string_view) # for capture_lines(output)

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

capture_lines

Description#

Examples#