NAME
LibTmux::Filter - Validated, reusable local criteria and explicit wire data
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.
METHODS
new
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.
entity
Return the declared entity-kind string. It remains known for an empty LibTmux::Selection.
normalized_where
Return an independent copy of normalized Perl criteria. Editing it does not change the compiled filter.
matches
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.
register_adapter
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
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
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.
from_data
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
from_json($json_octets) decodes bounded JSON using core booleans and calls "from_data". Invalid JSON throws InvalidFilter.
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.