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:

Examples of typed and local filters:

// Filter locally with the standard library:
let editors = try await server.panes().filter { $0.currentCommand == "nvim" }

// Or build a filter that travels: stored, sent, replayed elsewhere:
let expression = try FilterExpr<Pane>.where(\.currentCommand, .isIn(["nvim", "vim"]))
let matching = try await server.panes().filter(expression)

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.