NAME

LibTmux::Selection - Native array selections with fixed query returns

METHODS

new

new(@entities) creates a concrete blessed array reference and validates every member. Construct an entity-specific selection such as LibTmux::PaneSelection; an empty instance retains that schema.

Members may come from separate captures of the same server generation; each retains its own observation. Mixing servers or daemon generations throws "InvalidSelection" in LibTmux::X. Combining captures does not reconcile their times.

where

where($criteria_or_filter) eagerly returns a new selection of the same concrete class in scalar, list, or void context. Complete validation precedes evaluation, including on empty input. See "new" in LibTmux::Filter. Order and duplicate occurrences are preserved.

grep

grep($callback) returns a new same-class selection. Invoke the callback in scalar context with exactly one entity argument and a localized $_. Both bindings hold copies of the reference: assignment cannot replace a source slot. Restore $_ and propagate the original thrown value even on failure. Predicates must not edit the traversed sequence.

count

count($criteria?) returns an integer. Empty input returns zero. Validate all members before evaluating the optional criterion; count every matching occurrence, including duplicates.

exists

exists($criteria?) returns a native Boolean. Empty input returns false. After validating the entire membership, stop at the first matching entity. A reference itself remains true even when empty.

first

first($criteria?) returns the first matching entity or undef. Input order determines first; after membership validation, later field reads may be skipped.

one

one($criteria?) returns one entity. Zero throws NoMatch; a second occurrence throws MultipleMatches, reporting at least two and their IDs. Two occurrences of one identity are still ambiguous.

one_or_undef

one_or_undef($criteria?) returns an entity or undef for absence. A second matching occurrence still throws MultipleMatches.

iterator

Return a fresh local cursor with a copy of current membership. Its next returns an entity or undef only at exhaustion. Later native array edits do not alter this traversal; the selection remains replayable.

to_array

Return a fresh, unblessed array reference containing the same entity references. Editing its membership cannot corrupt graph adjacency or this selection. Captured entity values remain read-only through public readers.

EXECUTION

All methods in this module operate on local captured data and perform no tmux I/O. Ordering is deterministic; public query methods do not mutate membership. Typed validation/evaluation errors propagate. See "snapshot" in LibTmux::Server for explicit acquisition and LibTmux::X for machine-readable failures.