C++ API

function libtmux-cxx latest

matching

matching(expr) is a range adaptor closure so it composes with std views.

Source and package

Qualified name: libtmux::matching
Namespace: libtmux
Package: libtmux-cxx
Source: include/libtmux/filter_expr.hpp

template <typename Entity> [[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]] auto libtmux::tmuxq::matching(FilterExpr<Entity> expr); function [source] ¶

Examples#

Filter snapshots and require one match. Filter a window snapshot with typed fields and standard ranges. exactly_one_owned copies a unique match, so the temporary view is safe. Missing and ambiguous matches have different CardinalityError values; these lookups make no tmux calls. 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 <cstdio>
#include <ranges>
#include <string>

#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;
  }
  for (const char* name : {"editor", "logs"}) {
    const auto made = sessions->front().new_window(
        libtmux::NewWindowOptions{.name = name, .shell_command = "exec cat"});
    if (!made.has_value()) {
      std::fprintf(stderr, "%s\n", made.error().diagnostic.c_str());
      return 1;
    }
  }
  const auto windows = server->windows();
  if (!windows.has_value()) {
    std::fprintf(stderr, "%s\n", windows.error().diagnostic.c_str());
    return 1;
  }
  const auto wanted =
      libtmux::window::name.starts_with("edit") || libtmux::window::name == "logs";
  auto matches = *windows | libtmux::matching(wanted);
  const auto editor = libtmux::exactly_one_owned(
      *windows | libtmux::matching(libtmux::window::name == "editor"));
  auto absent = *windows | libtmux::matching(libtmux::window::name == "absent");
  const auto missing = libtmux::exactly_one(absent);
  const auto ambiguous = libtmux::exactly_one(matches);
  if (!editor.has_value() || std::ranges::distance(matches) != 2 ||
      missing.has_value() ||
      missing.error() != libtmux::CardinalityError::none_matched ||
      ambiguous.has_value() ||
      ambiguous.error() != libtmux::CardinalityError::several_matched) {
    std::fputs("unexpected query cardinality\n", stderr);
    return 1;
  }
  std::printf("Selected %s; two matches; missing and ambiguous are distinct.\n",
              std::string{editor->name()}.c_str());
  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:

Selected editor; two matches; missing and ambiguous are distinct.

Type parameters

Entity #

Parameters

expr (FilterExpr<Entity>) #

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

matching

Examples#