# LibTmux::Filter

- **Module:** LibTmux
- **Package:** LibTmux
- **Language:** Perl
- **Kind:** class
- **Source:** https://github.com/libtmux/libtmux-perl/blob/352715a4fa66a96eed7763b90daaa536aa2f121d/packages/core/lib/LibTmux/Filter.pm#L1
- **Page:** https://libtmux.org/en/perl/latest/reference/libtmux-filter/

```
package LibTmux::Filter;
```

Validated, reusable local criteria and explicit wire data


## SYNOPSIS


```perl
    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`](/en/perl/latest/reference/libtmux-server-snapshot/) for explicit acquisition and [`LibTmux::X`](/en/perl/latest/reference/libtmux-x/) for machine-readable failures.



## Members

### Other members

- [`entity`](/en/perl/latest/reference/libtmux-filter-entity/) (method): Return the declared entity-kind string. It remains known for an empty [`LibTmux::Selection`](/en/perl/latest/reference/libtmux-selection/).
- [`from_data`](/en/perl/latest/reference/libtmux-filter-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`](/en/perl/latest/reference/libtmux-filter-from_json/) (method): `from_json($json_octets)` decodes bounded JSON using core booleans and calls [`"from_data"`](/en/perl/latest/reference/libtmux-filter-from_data/). Invalid JSON throws [`InvalidFilter`](/en/perl/latest/reference/libtmux-x-invalidfilter/).
- [`matches`](/en/perl/latest/reference/libtmux-filter-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`](/en/perl/latest/reference/libtmux-x-unloaded/); they never become null or false through negation. Evaluation performs no I/O.
- [`new`](/en/perl/latest/reference/libtmux-filter-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`](/en/perl/latest/reference/libtmux-x-invalidfilter/) with precise paths, even for unreachable branches.
- [`normalized_where`](/en/perl/latest/reference/libtmux-filter-normalized_where/) (method): Return an independent copy of normalized Perl criteria. Editing it does not change the compiled filter.
- [`register_adapter`](/en/perl/latest/reference/libtmux-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`](/en/perl/latest/reference/libtmux-schema/).
- [`to_data`](/en/perl/latest/reference/libtmux-filter-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`](/en/perl/latest/reference/libtmux-filter-to_json/) (method): Return canonical-key UTF-8 JSON octets using [JSON::PP](https://perldoc.perl.org/5.44.0/JSON::PP). Non-UTF-8 opaque path bytes throw [`UnsupportedValue`](/en/perl/latest/reference/libtmux-x-unsupportedvalue/). This is reproducible key order, not semantic canonicalization of arbitrary Boolean trees.

## Guides

Pages that discuss `Filter`.

- [Filtering](/en/perl/latest/guides/filtering/)