LibTmux.Query
Typed selection over detached tmux observations.
Source and package
- Qualified name
-
LibTmux. Query - Package
- libtmux-haskell
- Source
- src/LibTmux/Query.hs
- LibTmux.Query
-
Description#
Build a
Querywith a source andmatching, then userunQueryto read an existingSnapshotwithout IO.fetchexplicitly acquires a new snapshot. Ordinary lists and application predicates remain available throughLibTmux.Snapshot; portable expressions contain no callbacks.Import field modules qualified:
LibTmux.Query.Pane,LibTmux.Query.Session,LibTmux.Query.Window,LibTmux.Query.Link,LibTmux.Query.Occurrence,LibTmux.Query.Client,LibTmux.Query.ClientAttachmentandLibTmux.Query.ServerInfo. Field tokens describe captured values; reading them never contacts tmux.Query construction, operands and results are finite. Execution validates every declared requirement before filtering, stably ordering and limiting. The default source order and multiplicity come from the supplied snapshot. A result establishes what was observed, not current liveness or a reserved command target. See
exactlyOnebefore selecting an explicit reference.>>> exactlyOne [1 :: Integer]Right 1>>> exactlyOne ([] :: [Integer])Left NoMatches>>> atMostOne ([] :: [Integer])Right Nothing>>> atMostOne [1, 2 :: Integer]Left AtLeastTwoMatchesWhat is on here
Its exports fall into these groups, in export-list order:
- Ordered sources
- Scalar predicates
- Selection and ordering
- Inspect and evaluate
- Cardinality
Members48#
Collections and queries4#
- sessions function Physical sessions in numeric ID order.
- windows function Unique physical windows in numeric ID order, independent of their links.
- panes function Unique physical panes in numeric ID order; use
paneOccurrencesfor context. - clients function Captured clients in bytewise name order, then PID.
Common operations14#
- atMostOne function Permit absence but reject a second match, with the same traversal behavior
as
exactlyOne. Use ordinarylistToMaybewhen choosing the first is intended. - dimensionAtLeast function Compare a positive cell dimension to an Integer threshold, inclusively.
Negative and arbitrarily large thresholds are valid predicates; they do not
construct a command dimension. Use
not_for a strict opposite bound. - every function Existential, universal or absent matching children. A known empty
relationship yields False, True or True, respectively. The child expression
applies to one child at a time; put conditions inside one
allOfwhen the same child must satisfy them. Unavailable relationships remain errors. - exactlyOne function Require exactly one value. Uniqueness can require traversing the entire input; ambiguity is established at the second match without forcing its tail. This neither acquires data nor reserves a live command target.
- fetch function Acquire a complete fresh snapshot and evaluate the query against it.
Compiled evaluator support is checked before IO; version requirements are
checked against acquired server metadata. Operational failures propagate
as exceptions from
capture; usetryTmuxto retain their context and recovery owners. Cancellation propagates unchanged. - limit function Replace the final nonnegative limit, applied after filtering and ordering regardless of builder order. A zero limit still validates every requirement.
- matching function Conjoin a predicate with existing predicates without changing the source.
- none function Existential, universal or absent matching children. A known empty
relationship yields False, True or True, respectively. The child expression
applies to one child at a time; put conditions inside one
allOfwhen the same child must satisfy them. Unavailable relationships remain errors. - optionalRelated function Test a known optional target. Absence yields False, so negation includes absence as well as targets that fail the child predicate.
- orderBy function Replace the ordering keys. Sorting is stable and follows filtering; an empty key list retains source order. Limits are always applied afterward.
- paneOccurrences function Pane appearances in link order, then pane-index order within each window.
- requirements function Collect every declared field and relationship, including ordering and branches that may short-circuit. This is pure and does not contact tmux.
- runQuery function Validate and evaluate against the supplied complete snapshot. Every requirement is checked before reading rows, including empty sources and zero limits. Consuming a successful result performs only pure processing of owned observations. No acquisition, pushdown or refresh occurs.
- some function Existential, universal or absent matching children. A known empty
relationship yields False, True or True, respectively. The child expression
applies to one child at a time; put conditions inside one
allOfwhen the same child must satisfy them. Unavailable relationships remain errors.
Other members30#
- allOf function Finite conjunction and disjunction. Empty lists mean True and False, respectively. Validation checks every branch before evaluation short-circuits.
- anyOf function Finite conjunction and disjunction. Empty lists mean True and False, respectively. Validation checks every branch before evaluation short-circuits.
- ascending function Order by the declared field's Ord instance in ascending or descending order. Text and byte-bearing types retain their own comparison semantics.
- CardinalityError data type Selection cardinality without retaining observations or counting ambiguity.
- contains function Exact, case-sensitive Text substring matching. Byte-bearing fields are deliberately excluded; use typed equality for their retained values.
- descending function Order by the declared field's Ord instance in ascending or descending order. Text and byte-bearing types retain their own comparison semantics.
- dimensionAtMost function Compare a positive cell dimension to an Integer threshold, inclusively.
Negative and arbitrarily large thresholds are valid predicates; they do not
construct a command dimension. Use
not_for a strict opposite bound. - eq function Exact equality in the field's declared type. No Unicode normalization, case folding or byte-to-text conversion is implicit.
- Expr data type A pure predicate description for one row type. Field and relationship tokens retain their identity; arbitrary application functions stay outside this portable representation. Nominal roles prevent cross-row coercion.
- Field data type Fields belong to physical rows or contextual links, never both implicitly.
- ge function Compare a mathematical Integer field with an unbounded threshold: greater-or-equal, greater, less-or-equal or less, respectively.
- gt function Compare a mathematical Integer field with an unbounded threshold: greater-or-equal, greater, less-or-equal or less, respectively.
- le function Compare a mathematical Integer field with an unbounded threshold: greater-or-equal, greater, less-or-equal or less, respectively.
- lt function Compare a mathematical Integer field with an unbounded threshold: greater-or-equal, greater, less-or-equal or less, respectively.
- not_ function Logical negation, preserving the expression's validation requirements.
- oneOf function Membership using exact equality against a finite operand list. An empty list never matches, but its field requirement is still validated.
- Order data type One ascending or descending field ordering. Combine keys with
orderBy. - paneIndexAtLeast function Inclusive bounds on a pane index, without narrowing or constructing an index.
- paneIndexAtMost function Inclusive bounds on a pane index, without narrowing or constructing an index.
- Query data type A source, predicate, stable ordering and optional final limit. Building a
query performs no IO and retains no Server handle. Use
LibTmux.Queryto evaluate. - QueryError data type Pure validation or navigation failure. Operational acquisition failures remain exceptions at the Server boundary rather than becoming empty results.
- QueryRequirements data type Inspectable dependencies, not a serialized query or an optimization plan.
- related function Test the required related observation in the supplied snapshot.
A failed lookup returns
RelationshipLookupFailed, never False or absence. - serverInfo function The single captured daemon-metadata observation.
- ToMany data type A closed one-to-many relationship. Obtain tokens from the entity field
modules and use
some,everyornone. Constructors are private. - ToOne data type A required relationship in a validated graph, used with
related. - ToOptional data type An observed optional relationship, used with
optionalRelated. Known absence is separate from an unavailable relationship. - windowIndexAtLeast function Inclusive bounds on a contextual window index, using Integer thresholds.
- windowIndexAtMost function Inclusive bounds on a contextual window index, using Integer thresholds.
- windowLinks function Contextual links in session-ID then window-index order, retaining multiplicity.
Guides#
Pages that discuss LibTmux.Query.