LibTmux.Query

Description#

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.