# LibTmux::Query

- **Package:** LibTmux
- **Language:** Raku
- **Kind:** module
- **Source:** https://github.com/libtmux/libtmux-raku/blob/e76160bcce6e03976d49424da15b7c31afb2c68e/lib/LibTmux/Query.rakumod#L2
- **Page:** https://libtmux.org/en/raku/latest/reference/libtmux-query/

# Validated local criteria

` Filter.compile(%criteria, :entity<pane>) ` validates and copies one
criterion before any entity is read. ` matches($view) ` and native smartmatching
through ` ACCEPTS ` use the same evaluator. The view protocol has four fixed
methods: ` entity `, ` state($name) `, ` value($name) ` and ` relation($name) `.
Names are checked against the catalogue; input keys never become method calls.

Field values abbreviate equality. Operator mappings support ` equals `,
` not-equals `, ` in `, ` not-in `, numeric ` lt/lte/gt/gte `, literal ` contains `,
` starts-with `, ` ends-with `, and nullable fields' ` is-null `. Operators and
fields at the same level are conjoined. Numeric operands exclude Bool and
non-finite values. Text is NFC normalized and literal matching compares
codepoints, including positions inside a grapheme. Invalid UTF8-C8 bytes are
refused; byte comparison belongs to a separate interface.

` AND ` and ` OR ` accept collections of complete criteria. ` NOT ` accepts one
criterion. Empty criteria and AND are true; empty OR and in are false; empty
not-in is true. Boolean evaluation short-circuits after schema validation.
For example, an OR whose first branch matches does not read an unloaded field
in its second branch. Unknown fields in either branch still fail compilation.

To-many relations support ` some `, ` every ` and ` none `. One ` some ` requires
one child to satisfy its complete subtree. Separate existential subtrees may
use different children. Loaded empty relations yield false, true and true,
respectively. To-one relations support ` is `, ` is-not `, and ` is-null ` where
the relation is nullable. No evaluation performs I/O.

KnownNull satisfies only an explicit null test. For example,
` dead-status => %(not-equals => 0) ` is false when status is KnownNull;
` NOT => %(dead-status => %(not-equals => 0)) ` is true. Likewise a
null group fails both ` is ` and ` is-not `. Unsupported, Unavailable and Unloaded
states throw MissingData when evaluated. They are never empty relations,
empty strings, zero or false.

` criteria ` exposes normalized nested Maps and Lists. ` ast ` exposes immutable
nodes for source planning: kind, entity, name, wire-name, operator, field-kind,
target, operand and children. Cloning a Filter is refused; compile changed data
to preserve validation. Native callbacks, Junctions, regexes, type objects,
lazy collections and cycles are not criterion data.



# Proposed JSON representation

` to-json ` and ` Filter.from-json(Str|Blob) ` use JSON::Fast and the proposed
` libtmux.where/v1 ` envelope with exactly ` schema `, ` entity ` and ` where `.
This is a Raku proposal, not a claim of tested cross-port wire compatibility.
Catalogue wire names are stable camelCase names; compound operator names use
camelCase too, such as ` notEquals `, ` startsWith `, ` isNull ` and ` isNot `.
JSON::Fast uses the last value for a duplicate object key.
The bounded preflight also rejects malformed numeric spellings and raw control
characters in strings; parsing remains delegated to JSON::Fast.

Wire numbers use finite binary64 values bounded in absolute magnitude by
` 2**53-1 `, with integers in that safe range kept exact. Decimal JSON operands
are interpreted as binary64. Export of an exact Rat or FatRat requires a
power-of-two denominator, a numerator below 2**53 in absolute magnitude and
a lossless nonzero binary64 conversion. In particular, local ` 1/3 ` criteria
remain valid but cannot be serialized by rounding to ` 0.333333 `. JSON numeric
tokens are limited to 64 characters and exponents to absolute value 324;
overflow and nonzero underflow are refused.

Limits defaults are 1 MiB wire input/output, depth 32, 4096 copied value nodes
and 1024 membership operands. Byte length and structural JSON depth are checked
before parsing while respecting quoted strings and escapes. Native and decoded
criteria then share bounded recursive validation. Supply an immutable Limits
value to compile or from-json to choose tighter limits.

## Members

### Other members

- [`Filter`](/en/raku/latest/reference/libtmux-query-filter/) (class): A schema-validated local matcher with copied, immutable criteria and AST.
- [`Limits`](/en/raku/latest/reference/libtmux-query-limits/) (class): Immutable resource limits applied before recursive validation or JSON parsing.
- [`Plan`](/en/raku/latest/reference/libtmux-query-plan/) (module)