# tmux_select

- **Package:** libtmux_erlang
- **Language:** Erlang
- **Kind:** module
- **Source:** https://github.com/libtmux/libtmux-erlang/blob/d1b6308440cf9eb8f6647e7ae434bce60e849368/apps/libtmux_erlang/src/tmux_select.erl#L1
- **Page:** https://libtmux.org/en/erlang/latest/reference/tmux_select/

Filter ordered captured rows without tmux I/O.

Use `panes/1`, `windows/1`,
`window_links/1` or `sessions/1` with a
`m:tmux_snapshot` to retain graph coverage. `from_list/2`
preserves supplied order, duplicates and row origins; it establishes only
fields present in every row and loads no relationships. Filtering and
`take/2` retain the original coverage even if no rows remain.

`where/2` accepts map criteria or a `t:tmux_filter:t/0` portable
filter. `filter/2` accepts a unary Boolean function, whose
exceptions propagate. Cardinality criteria validate the whole expression and
its coverage before stopping at sufficient evidence. Selections are opaque
values; use `to_list/1` for functions in `m:lists`.

A snapshot-backed selection retains the complete captured graph, including
rows removed by filtering. After relationship evaluation, store the result of
`to_list/1` and release other snapshot and selection references to allow that
context to be collected. Row extraction preserves the supplied field binaries;
caller-created subbinaries can still retain their backing allocation.

## Members

### Collections and queries

- [`sessions/1`](/en/erlang/latest/reference/tmux_select-sessions-1/) (function): Select captured sessions with their relationship and coverage context. Performs no I/O.
- [`windows/1`](/en/erlang/latest/reference/tmux_select-windows-1/) (function): Select unique captured physical windows with their complete graph context. Performs no I/O; session memberships remain separate window-link rows.
- [`panes/1`](/en/erlang/latest/reference/tmux_select-panes-1/) (function): Select captured physical panes while retaining snapshot graph and coverage. Performs no I/O and preserves the snapshot's deterministic order.

### Common operations

- [`filter/2`](/en/erlang/latest/reference/tmux_select-filter-2/) (function): Apply an ordinary unary Boolean function locally, preserving row order and context. Non-Booleans and callback failures propagate; they are not false matches. This is executable application code, not portable filter data.
- [`one/1`](/en/erlang/latest/reference/tmux_select-one-1/) (function): Return the sole current row or a no_match/multiple_matches error. Ambiguity reports at_least = 2 rather than computing a needless exact count.
- [`t/1`](/en/erlang/latest/reference/t-tmux_select-t-1/) (typealias): Ordered captured rows with observation and coverage context, not an extensible list protocol. The parameter describes the intended row type. OTP 29 Dialyzer can widen generic return variables to their declared bounds; it does not prove every entity relationship through `one/1` or `to_list/1`. Runtime schema, coverage and action checks remain necessary.
- [`from_list/2`](/en/erlang/latest/reference/tmux_select-from_list-2/) (function): Validate an ordinary list without rebinding, reordering or deduplicating it.

### Other members

- [`cardinality_error/0`](/en/erlang/latest/reference/t-tmux_select-cardinality_error-0/) (typealias)
- [`count/1`](/en/erlang/latest/reference/tmux_select-count-1/) (function): Return the current materialized row count without I/O.
- [`count/2`](/en/erlang/latest/reference/tmux_select-count-2/) (function): Return the exact local match count after full criteria and coverage validation. Performs no I/O.
- [`criteria/0`](/en/erlang/latest/reference/t-tmux_select-criteria-0/) (typealias)
- [`exists/1`](/en/erlang/latest/reference/tmux_select-exists-1/) (function): Return whether this materialized selection is nonempty, without I/O.
- [`exists/2`](/en/erlang/latest/reference/tmux_select-exists-2/) (function): Validate all criteria/coverage first, then stop at the first local match. Performs no I/O; an empty selection does not bypass validation.
- [`first/1`](/en/erlang/latest/reference/tmux_select-first-1/) (function): Return the first current row or none. Additional matches are allowed. Performs no I/O.
- [`first/2`](/en/erlang/latest/reference/tmux_select-first-2/) (function): Validate criteria and coverage, then stop at the first local match. Returns none when no row matches; performs no I/O.
- [`fold/3`](/en/erlang/latest/reference/tmux_select-fold-3/) (function): Fold over current rows in order without I/O, using the function, accumulator, selection argument order. Arbitrary results are ordinary Erlang values.
- [`matching/2`](/en/erlang/latest/reference/tmux_select-matching-2/) (function): Prepare a trusted behaviour once, then apply its Boolean predicate.
- [`one_or_error/1`](/en/erlang/latest/reference/tmux_select-one_or_error-1/) (function): Return the sole row directly, raising on zero or multiple matches. Use `one/1` for tagged cardinality errors.
- [`one_or_error/2`](/en/erlang/latest/reference/tmux_select-one_or_error-2/) (function): Filter locally with complete validation, then return the sole row directly. Raises on zero or multiple matches; performs no I/O.
- [`one_or_none/1`](/en/erlang/latest/reference/tmux_select-one_or_none-1/) (function): Return the sole current row, {ok, none} on absence, or a multiple-match error. Performs no I/O.
- [`one_or_none/2`](/en/erlang/latest/reference/tmux_select-one_or_none-2/) (function): Validate local criteria and return one row or known absence. A second match is an explicit ambiguity error; performs no I/O.
- [`one/2`](/en/erlang/latest/reference/tmux_select-one-2/) (function): Validate criteria and coverage, then stop after enough local matches to establish cardinality. Returns a tagged cardinality result; performs no I/O.
- [`size/1`](/en/erlang/latest/reference/tmux_select-size-1/) (function): Return the cached number of materialized rows in this selection without traversing tmux or re-evaluating criteria.
- [`summary/0`](/en/erlang/latest/reference/t-tmux_select-summary-0/) (typealias): Compact local inspection. size counts current materialized rows; coverage still describes the original captured context after filtering or take. snapshot_id is none for a list-backed selection. Capture bounds and query diagnostics are included only when that source metadata exists.
- [`summary/1`](/en/erlang/latest/reference/tmux_select-summary-1/) (function): Return a compact Erlang diagnostic map with entity, size, capture identity, interval and coverage. Fetched queries include candidate/attempt information. Opaque snapshot references make this a diagnostic value, not a wire format.
- [`t/0`](/en/erlang/latest/reference/t-tmux_select-t-0/) (typealias): A selection over schema-defined native domain records.
- [`take/2`](/en/erlang/latest/reference/tmux_select-take-2/) (function): Keep the first N rows and retain the original observation and coverage. Performs no I/O; taking a subset cannot establish missing field coverage.
- [`to_list/1`](/en/erlang/latest/reference/tmux_select-to_list-1/) (function): Return the current ordered rows as an ordinary Erlang list without I/O. Use list functions or comprehensions for transformations to other value types. Returns the stored rows without copying their binary fields. Keeping only the list allows the selection's snapshot context to be collected; other references can still keep that context alive.
- [`try_where/2`](/en/erlang/latest/reference/tmux_select-try_where-2/) (function): Apply the same local criteria and coverage checks as `where/2`, returning tagged validation or evaluation errors. It does not catch arbitrary application callback exceptions and never performs tmux I/O.
- [`where/2`](/en/erlang/latest/reference/tmux_select-where-2/) (function): Validate portable criteria and coverage, then preserve matching rows in order. Performs no I/O. Malformed trusted criteria raise bad_filter; missing coverage and runtime evaluation failures remain distinct exceptions. Use `try_where/2` for tagged library errors.
- [`window_links/1`](/en/erlang/latest/reference/tmux_select-window_links-1/) (function): Select all captured session memberships, retaining repeated physical windows and session-relative indexes. Performs no I/O.

## Guides

Pages that discuss `tmux_select`.

- [Native API documentation](/en/erlang/latest/guides/api-documentation/)