Perl API

Up Root

class libtmux-perl latest

Filter

Validated, reusable local criteria and explicit wire data

Source and package

Qualified name: LibTmux::Filter
Module: LibTmux
Package: LibTmux
Source: packages/core/lib/LibTmux/Filter.pm

package LibTmux::Filter; class LibTmux [source] ¶

Description#

SYNOPSIS

    use v5.44;
    use LibTmux::Filter;
    my $filter = LibTmux::Filter->new(
        entity => 'pane', where => {width => {-gte => 120}},
    );
    my $matches = $snapshot->panes->where($filter);

CONTRACT

Compilation validates the entire tree and copies operands. Hash keys evaluate lexically; logical arrays retain input order. Missing reads throw; known-null ordering is false. String operators are literal. Relations use some/every/none and is/is_not with explicit dash prefixes in Perl data.

matches accepts entities, plain records, and registered adapters. to_data/to_json export copies in libtmux.where/v1; from_data/from_json validate input. Regex/coderefs/cycles and non-UTF-8 byte-path wire operands are refused. Perl regex remains available through Selection grep.

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.

Members9#

entity method Return the declared entity-kind string. It remains known for an empty LibTmux::Selection.
from_data method from_data($envelope) validates the version, entity, fields, operators, and operands, then returns a compiled filter. Reject executable values, unknown versions, cycles, and unsupported regex nodes.
from_json method from_json($json_octets) decodes bounded JSON using core booleans and calls "from_data". Invalid JSON throws InvalidFilter.
matches method matches($entity_or_record) returns a native Boolean. Accept captured entities, plain hash records, or registered adapters of the declared kind. Missing required reads throw Unloaded; they never become null or false through negation. Evaluation performs no I/O.
new method new(entity => kind, where => $hashref) validates the complete criteria tree and owns a normalized copy. Schemas choose comparison types; no scalar-history coercion or arbitrary method dispatch occurs. Errors throw InvalidFilter with precise paths, even for unreachable branches.
normalized_where method Return an independent copy of normalized Perl criteria. Editing it does not change the compiled filter.
register_adapter method register_adapter(class => name, entity => kind, readers => { field => coderef }) registers trusted field readers without inheritance. Only declared fields are accepted. Readers are executable local code; they never enter portable criteria. See LibTmux::Schema.
to_data method Return a fresh libtmux.where/v1 envelope using canonical wire field/operator names. Normalize strings, numbers, native booleans, null, objects, and arrays by schema. Aliases are currently absent; one canonical name is encoded.
to_json method Return canonical-key UTF-8 JSON octets using JSON::PP. Non-UTF-8 opaque path bytes throw UnsupportedValue. This is reproducible key order, not semantic canonicalization of arbitrary Boolean trees.

Guides#

Pages that discuss Filter.

Filtering

Scripting & web

Compiled & native

JVM

.NET

BEAM

tmux

Filter

Description#

Members9#

Guides#