Selection
Native array selections with fixed query returns
Source and package
- Qualified name
-
LibTmux:: Selection - Module
- LibTmux
- Package
- LibTmux
- Source
- packages/core/lib/LibTmux/Selection.pm
- package Lib
Tmux:: ;Selection -
Description#
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::Serverfor explicit acquisition andLibTmux::Xfor machine-readable failures.Examples#
Complete installed-package program with an owned tmux fixture and result/cleanup assertions. View source
use v5.44;use FindBin;use lib "$FindBin::Bin/../scripts/lib";use LibTmuxFixture;use LibTmux::Filter;use List::Util qw(any first);LibTmuxFixture->run(sub ($server, $root) {my $session = $server->new_session(name => 'example',command => ['/bin/sleep', '120']);my $initial = $session->window_links->one->window->panes->one;$server->split_pane(pane => $initial,horizontal => true,command => ['/bin/sleep', '120']);my $snapshot = $server->snapshot;my $panes = $snapshot->panes->where({current_command => 'sleep'})->grep(sub ($pane) { $pane->width >= 1 });die 'expected two panes' unless $panes->count == 2;for my $pane ($panes->@*) {say $pane->id . ' ' . $pane->current_command;}my $only_active = $panes->one({active => true});die 'active pane unavailable' unless defined $only_active;my $has_active = any { $_->active } $panes->@*;my $first_active = first { $_->active } $panes->@*;die 'List::Util alternatives differ'unless $has_active && $first_active->id eq $only_active->id;my @ids = map { $_->id } $panes->@*;my @positive = grep { $_->width > 0 } $panes->@*;die 'ordinary Perl arrays differ' unless @ids == 2 && @positive == 2;my $filter =LibTmux::Filter->new(entity => 'pane', where => {active => true});my $decoded = LibTmux::Filter->from_json($filter->to_json);die 'wire filter changed meaning'unless $panes->where($decoded)->one->id eq $only_active->id;my $retained = do {my $observed = $server->snapshot;$observed->pane_by_id($only_active->id);};die 'retained graph lost a relationship'unless $retained->window->panes->count == 2;my $same_child = $snapshot->windows->where({panes => {-some => {-and => [{index => 0}, {index => 1}]}}});my $different_children = $snapshot->windows->where({-and => [{panes => {-some => {index => 0}}},{panes => {-some => {index => 1}}}]});die 'quantifiers conflated children'unless $same_child->count == 0 && $different_children->count == 1;my $where = {active => true, width => {-gte => 1}};my $local = $server->query_panes(where => $where, pushdown => 'never');my $verification;my $native = $server->query_panes(where => $where,pushdown => 'require',on_verification => sub ($report) { $verification = $report },);die 'native verification was not observed'unless $verification->{status} eq 'agreed'&& $verification->{comparison} eq 'exact_ids';die 'native/local disagreement'unless join(',', map { $_->id } @$local) eqjoin(',', map { $_->id } @$native);say 'selection, wire, graph lifetime, quantifiers, and query: ok';});
Members10#
- count method
count($criteria?)returns an integer. Empty input returns zero. Validate all members before evaluating the optional criterion; count every matching occurrence, including duplicates. - exists method
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 method
first($criteria?)returns the first matching entity or undef. Input order determines first; after membership validation, later field reads may be skipped. - grep method
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. - iterator method Return a fresh local cursor with a copy of current membership. Its
nextreturns an entity or undef only at exhaustion. Later native array edits do not alter this traversal; the selection remains replayable. - new method
new(@entities)creates a concrete blessed array reference and validates every member. Construct an entity-specific selection such asLibTmux::PaneSelection; an empty instance retains that schema. - one method
one($criteria?)returns one entity. Zero throwsNoMatch; a second occurrence throwsMultipleMatches, reporting at least two and their IDs. Two occurrences of one identity are still ambiguous. - one_or_undef method
one_or_undef($criteria?)returns an entity or undef for absence. A second matching occurrence still throwsMultipleMatches. - to_array method 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.
- where method
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.