Filtering and queries

Use a collection filter to find matching sessions, windows, or panes. Use an exactly-one lookup when your next operation requires a single target.

• Filtering returns a collection; exactly-one lookup checks the result count. A filter returns zero or more matches. An exactly-one operation returns one object or reports a missing or ambiguous match.

• Choose where to filter. Filter a snapshot in your program when you need several queries over the same data. A tmux format filter can reduce the rows returned by a live read. The cost depends on the data and queries you need.

Typed and local filters¶

Typed field operations let the compiler reject incompatible comparisons:

Compose CFilterExpr values with &&, ||, and !. For example, mpane::command.starts_with("nv") && pane::active is valid, while pane::active.starts_with("x") fails to compile.

Examples of typed and local filters:

// A filter is a value built from typed fields; `window::active.starts_with(...)`
// would not compile: a flag has no string operations.
const auto interesting =
    libtmux::window::name.starts_with("e") || libtmux::window::name == "logs";

auto matched = *windows | libtmux::matching(interesting);

// "Exactly one, or say why not" is a question the library answers directly.
auto logs = *windows | libtmux::matching(libtmux::window::name == "logs");
if (const auto only = libtmux::exactly_one(logs); only.has_value()) {
  std::printf("exactly one: %s\n", std::string{only->get().id()}.c_str());
}

Result counts¶

Filtering and querying shows exactly-one lookups and their error handling. Do not index the first result until the operation has established that a match exists.