# tmux_filter

- **Package:** libtmux_erlang
- **Language:** Erlang
- **Kind:** module
- **Source:** https://github.com/libtmux/libtmux-erlang/blob/d1b6308440cf9eb8f6647e7ae434bce60e849368/apps/libtmux_erlang/src/tmux_filter.erl#L1
- **Page:** https://libtmux.org/en/erlang/latest/reference/tmux_filter/

Construct portable conditions and prepare them against captured values.

Local criteria use atom keys, binary text and schema-typed values. Fields and
operators conjoin. Boolean branches use 'and', 'or' and 'not'; relationships
use some/every/none/count or is/is_not. Validation examines the entire input
before evaluation. No function here performs tmux I/O. Use portable filters
with `tmux_select:where/2` or `tmux_query:where/2`; the [query
guide](querying.md) explains their different execution boundaries.

Wire version 1 uses generated camelCase field names, snake_case operators,
JSON null for known absence and {"base64": "..."} for byte operands. Byte
values never become text implicitly. Regex uses the restricted ASCII
portable_v1 dialect, absolute anchors and no flags. Preparation compiles each
pattern once. Non-ASCII subjects and exhausted match limits return errors.

Both input criteria and their normalized wire document must fit the grammar,
depth and byte limits. Resource errors can refer to the canonical wire path.

## Examples

```erlang
1> Fields = #{id => <<"%1">>, current_command => <<"vim">>}, ok.
ok
2> {ok, P} = tmux_model:pane(Fields), S = tmux_select:from_list(pane, [P]), ok.
ok
3> R = #{pattern => <<"^(vim|nvim)$">>, dialect => portable_v1}, ok.
ok
4> tmux_select:size(tmux_select:where(#{current_command => #{regex => R}}, S)).
1
```

## Members

### Common operations

- [`decode_json/1`](/en/erlang/latest/reference/tmux_filter-decode_json-1/) (function): Decode bounded external JSON with duplicate-key, trailing-input and depth checks. Returns tagged errors with input paths. Parsing does not execute tmux or choose application modules.
- [`new/2`](/en/erlang/latest/reference/tmux_filter-new-2/) (function): Validate criteria or reuse an already normalized filter for the same entity.
- [`prepare/2`](/en/erlang/latest/reference/tmux_filter-prepare-2/) (function): Bind a filter to one snapshot and check all required coverage first.

### Other members

- [`entity/1`](/en/erlang/latest/reference/tmux_filter-entity-1/) (function): Return the schema entity this portable filter accepts, without I/O.
- [`expr/0`](/en/erlang/latest/reference/t-tmux_filter-expr-0/) (typealias): Normalized data expressions with stable field IDs, used by internal planners; not the wire grammar.
- [`from_wire/2`](/en/erlang/latest/reference/tmux_filter-from_wire-2/) (function): Validate a versioned filter document using generated wire-name allowlists. Rejects unknown fields, operators, wrong entity/version and resource limits. No payload key becomes an atom; this does not execute a query.
- [`matches/2`](/en/erlang/latest/reference/tmux_filter-matches-2/) (function): Evaluate an unmodified captured row against a prepared filter. Returns a Boolean result or tagged context/regex resource error. It performs no tmux I/O and never converts evaluation failure into a nonmatch.
- [`new_or_error/2`](/en/erlang/latest/reference/tmux_filter-new_or_error-2/) (function): Construct a normalized portable filter, raising bad_filter on malformed trusted criteria. Performs no tmux I/O. External input should use `new/2` or `from_wire/2` for tagged validation errors.
- [`predicate/1`](/en/erlang/latest/reference/tmux_filter-predicate-1/) (function): Return a Boolean function bound to the prepared observation context.
- [`prepared/0`](/en/erlang/latest/reference/t-tmux_filter-prepared-0/) (typealias): A cached evaluator bound to one captured observation and schema context.
- [`requirements/1`](/en/erlang/latest/reference/tmux_filter-requirements-1/) (function): Derive every field and complete relationship needed for faithful evaluation. The complete requirement set is checked before short-circuiting any row.
- [`t/0`](/en/erlang/latest/reference/t-tmux_filter-t-0/) (typealias): Portable normalized predicate data for one schema entity; contains no executable state.
- [`to_wire/1`](/en/erlang/latest/reference/tmux_filter-to_wire-1/) (function): Export versioned JSON-compatible predicate data with generated wire names. Byte operands use base64 objects and known absence uses JSON null. Functions, compiled regexes and native record internals never enter this representation.
- [`wire_document/0`](/en/erlang/latest/reference/t-tmux_filter-wire_document-0/) (typealias): Version-one JSON-compatible filter envelope with binary keys version, entity and where. entity is the generated wire entity name; where contains Boolean, field and relationship conditions. Version is the integer 1. Keys and operators still require `from_wire/2` validation; the typespec alone does not authorize arbitrary fields or unbounded external input.

## Guides

Pages that discuss `tmux_filter`.

- [Native API documentation](/en/erlang/latest/guides/api-documentation/)