tmux_filter (libtmux for Erlang v0.0.1)
View SourceConstruct 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 explains their different execution boundaries.
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)).
1Wire 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.
Summary
Types
Normalized data expressions with stable field IDs, used by internal planners; not the wire grammar.
A cached evaluator bound to one captured observation and schema context.
Portable normalized predicate data for one schema entity; contains no executable state.
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.
Functions
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.
Return the schema entity this portable filter accepts, without I/O.
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.
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.
Validate criteria or reuse an already normalized filter for the same entity.
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.
Return a Boolean function bound to the prepared observation context.
Bind a filter to one snapshot and check all required coverage first.
Derive every field and complete relationship needed for faithful evaluation. The complete requirement set is checked before short-circuiting any row.
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.
Types
-type expr() :: {all | any, [expr()]} | {negate, expr()} | {field, binary(), atom(), term()} | {relation, binary(), atom(), expr()} | {count, binary(), [{atom(), term()}]}.
Normalized data expressions with stable field IDs, used by internal planners; not the wire grammar.
-opaque prepared()
A cached evaluator bound to one captured observation and schema context.
-opaque t()
Portable normalized predicate data for one schema entity; contains no executable state.
-type wire_document() :: #{binary() => json:encode_value()}.
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.
Functions
-spec decode_json(binary()) -> {ok, json:decode_value()} | {error, map()}.
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.
-spec entity(t()) -> tmux_schema:entity().
Return the schema entity this portable filter accepts, without I/O.
-spec from_wire(tmux_schema:entity(), term()) -> {ok, t()} | {error, map()}.
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.
-spec matches(prepared(), tmux_model:row()) -> {ok, boolean()} | {error, map()}.
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.
-spec new(tmux_schema:entity(), map() | t()) -> {ok, t()} | {error, map()}.
Validate criteria or reuse an already normalized filter for the same entity.
1> {ok, F} = tmux_filter:new(pane, #{width => #{gte => 120.0}}), ok.
ok
2> tmux_filter:new(pane, F) =:= {ok, F}.
true
3> tmux_filter:new(pane, #{active => #{contains => <<"yes">>}}).
{error,#{code => unsupported_operator,path => [active,contains],allowed => [equals,'not',in,not_in]}}
-spec new_or_error(tmux_schema:entity(), map() | t()) -> t().
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.
-spec predicate(prepared()) -> fun((tmux_model:row()) -> boolean()).
Return a Boolean function bound to the prepared observation context.
Rows outside that context raise {prepared_context_mismatch, Detail}. Regex
evaluation errors raise {filter_evaluation_failed, Detail}. Use matches/2
for tagged errors. This does not run callbacks.
-spec prepare(t(), tmux_snapshot:t()) -> {ok, prepared()} | {error, map()}.
Bind a filter to one snapshot and check all required coverage first.
The prepared value can match only unmodified rows captured in that snapshot. It remains usable after the endpoint closes. It cannot refresh observations.
1> {ok, F} = tmux_filter:new(pane, #{width => #{gte => 80}}), ok.
ok
2> tmux_filter:requirements(F).
[{collection,pane},{field,pane,width}]
-spec requirements(t()) -> [tmux_snapshot:requirement()].
Derive every field and complete relationship needed for faithful evaluation. The complete requirement set is checked before short-circuiting any row.
-spec to_wire(t()) -> wire_document().
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.