Core LibraryunreleasedAPI Reference

Choose documentation 2

latest

Current version

latest
English

Unreleased LibTmux has not been released. Its API may change during development. This site's structure and URLs may change too.

class libtmux-perl latest

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

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::Server for explicit acquisition and LibTmux::X for 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) eq
join(',', 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 next returns 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 as LibTmux::PaneSelection; an empty instance retains that schema.
  • one method 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 method one_or_undef($criteria?) returns an entity or undef for absence. A second matching occurrence still throws MultipleMatches.
  • 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.
Esc

Type to search.

Reference previewOpen reference