# LibTmux.Query - **Package:** libtmux-haskell - **Language:** Haskell - **Kind:** module - **Source:** https://github.com/libtmux/libtmux-haskell/blob/663e212622a02aa74a9bdc8ff71e2b45fcb1d4d5/src/LibTmux/Query.hs - **Page:** https://libtmux.org/en/haskell/latest/reference/libtmux-query/ Typed selection over detached tmux observations. Build a [`Query`](/en/haskell/latest/reference/libtmux-query-t-query/) with a source and [`matching`](/en/haskell/latest/reference/libtmux-query-v-matching/), then use [`runQuery`](/en/haskell/latest/reference/libtmux-query-v-runquery/) to read an existing [`Snapshot`](/en/haskell/latest/reference/libtmux-snapshot-t-snapshot/) without IO. [`fetch`](/en/haskell/latest/reference/libtmux-query-v-fetch/) explicitly acquires a new snapshot. Ordinary lists and application predicates remain available through [`LibTmux.Snapshot`](/en/haskell/latest/reference/libtmux-snapshot/); portable expressions contain no callbacks. Import field modules qualified: [`LibTmux.Query.Pane`](/en/haskell/latest/reference/libtmux-query-pane/), [`LibTmux.Query.Session`](/en/haskell/latest/reference/libtmux-query-session/), [`LibTmux.Query.Window`](/en/haskell/latest/reference/libtmux-query-window/), [`LibTmux.Query.Link`](/en/haskell/latest/reference/libtmux-query-link/), [`LibTmux.Query.Occurrence`](/en/haskell/latest/reference/libtmux-query-occurrence/), [`LibTmux.Query.Client`](/en/haskell/latest/reference/libtmux-query-client/), [`LibTmux.Query.ClientAttachment`](/en/haskell/latest/reference/libtmux-query-clientattachment/) and [`LibTmux.Query.ServerInfo`](/en/haskell/latest/reference/libtmux-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 [`exactlyOne`](/en/haskell/latest/reference/libtmux-query-v-exactlyone/) before selecting an explicit reference. ```haskell >>> exactlyOne [1 :: Integer] Right 1 >>> exactlyOne ([] :: [Integer]) Left NoMatches >>> atMostOne ([] :: [Integer]) Right Nothing >>> atMostOne [1, 2 :: Integer] Left AtLeastTwoMatches ``` # What is on here Its exports fall into these groups, in export-list order: **Descriptions** [`Field`](/en/haskell/latest/reference/libtmux-query-t-field/), [`Expr`](/en/haskell/latest/reference/libtmux-query-t-expr/), [`Query`](/en/haskell/latest/reference/libtmux-query-t-query/), [`Order`](/en/haskell/latest/reference/libtmux-query-t-order/), [`ToMany`](/en/haskell/latest/reference/libtmux-query-t-tomany/), [`ToOne`](/en/haskell/latest/reference/libtmux-query-t-toone/), [`ToOptional`](/en/haskell/latest/reference/libtmux-query-t-tooptional/) **Ordered sources** [`sessions`](/en/haskell/latest/reference/libtmux-query-v-sessions/), [`windows`](/en/haskell/latest/reference/libtmux-query-v-windows/), [`panes`](/en/haskell/latest/reference/libtmux-query-v-panes/), [`windowLinks`](/en/haskell/latest/reference/libtmux-query-v-windowlinks/), [`paneOccurrences`](/en/haskell/latest/reference/libtmux-query-v-paneoccurrences/), [`clients`](/en/haskell/latest/reference/libtmux-query-v-clients/), [`serverInfo`](/en/haskell/latest/reference/libtmux-query-v-serverinfo/) **Scalar predicates** [`eq`](/en/haskell/latest/reference/libtmux-query-v-eq/), [`oneOf`](/en/haskell/latest/reference/libtmux-query-v-oneof/), [`contains`](/en/haskell/latest/reference/libtmux-query-v-contains/), [`ge`](/en/haskell/latest/reference/libtmux-query-v-ge/), [`gt`](/en/haskell/latest/reference/libtmux-query-v-gt/), [`le`](/en/haskell/latest/reference/libtmux-query-v-le/), [`lt`](/en/haskell/latest/reference/libtmux-query-v-lt/), [`dimensionAtLeast`](/en/haskell/latest/reference/libtmux-query-v-dimensionatleast/), [`dimensionAtMost`](/en/haskell/latest/reference/libtmux-query-v-dimensionatmost/), [`paneIndexAtLeast`](/en/haskell/latest/reference/libtmux-query-v-paneindexatleast/), [`paneIndexAtMost`](/en/haskell/latest/reference/libtmux-query-v-paneindexatmost/), [`windowIndexAtLeast`](/en/haskell/latest/reference/libtmux-query-v-windowindexatleast/), [`windowIndexAtMost`](/en/haskell/latest/reference/libtmux-query-v-windowindexatmost/) **Logic and relationships** [`allOf`](/en/haskell/latest/reference/libtmux-query-v-allof/), [`anyOf`](/en/haskell/latest/reference/libtmux-query-v-anyof/), [`not_`](/en/haskell/latest/reference/libtmux-query-v-not_/), [`some`](/en/haskell/latest/reference/libtmux-query-v-some/), [`every`](/en/haskell/latest/reference/libtmux-query-v-every/), [`none`](/en/haskell/latest/reference/libtmux-query-v-none/), [`related`](/en/haskell/latest/reference/libtmux-query-v-related/), [`optionalRelated`](/en/haskell/latest/reference/libtmux-query-v-optionalrelated/) **Selection and ordering** [`matching`](/en/haskell/latest/reference/libtmux-query-v-matching/), [`orderBy`](/en/haskell/latest/reference/libtmux-query-v-orderby/), [`ascending`](/en/haskell/latest/reference/libtmux-query-v-ascending/), [`descending`](/en/haskell/latest/reference/libtmux-query-v-descending/), [`limit`](/en/haskell/latest/reference/libtmux-query-v-limit/) **Inspect and evaluate** [`QueryRequirements`](/en/haskell/latest/reference/libtmux-query-t-queryrequirements/), [`requirements`](/en/haskell/latest/reference/libtmux-query-v-requirements/), [`QueryError`](/en/haskell/latest/reference/libtmux-query-t-queryerror/), [`runQuery`](/en/haskell/latest/reference/libtmux-query-v-runquery/), [`fetch`](/en/haskell/latest/reference/libtmux-query-v-fetch/) **Cardinality** [`CardinalityError`](/en/haskell/latest/reference/libtmux-query-t-cardinalityerror/), [`exactlyOne`](/en/haskell/latest/reference/libtmux-query-v-exactlyone/), [`atMostOne`](/en/haskell/latest/reference/libtmux-query-v-atmostone/) ## Members ### Collections and queries - [`sessions`](/en/haskell/latest/reference/libtmux-query-v-sessions/) (function): Physical sessions in numeric ID order. - [`windows`](/en/haskell/latest/reference/libtmux-query-v-windows/) (function): Unique physical windows in numeric ID order, independent of their links. - [`panes`](/en/haskell/latest/reference/libtmux-query-v-panes/) (function): Unique physical panes in numeric ID order; use :obj:`paneOccurrences ` for context. - [`clients`](/en/haskell/latest/reference/libtmux-query-v-clients/) (function): Captured clients in bytewise name order, then PID. ### Common operations - [`atMostOne`](/en/haskell/latest/reference/libtmux-query-v-atmostone/) (function): Permit absence but reject a second match, with the same traversal behavior as :obj:`exactlyOne `. Use ordinary `listToMaybe` when choosing the first is intended. - [`dimensionAtLeast`](/en/haskell/latest/reference/libtmux-query-v-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 :obj:`not_ ` for a strict opposite bound. - [`every`](/en/haskell/latest/reference/libtmux-query-v-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 :obj:`allOf ` when the same child must satisfy them. Unavailable relationships remain errors. - [`exactlyOne`](/en/haskell/latest/reference/libtmux-query-v-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`](/en/haskell/latest/reference/libtmux-query-v-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 :obj:`capture `; use :obj:`tryTmux ` to retain their context and recovery owners. Cancellation propagates unchanged. - [`limit`](/en/haskell/latest/reference/libtmux-query-v-limit/) (function): Replace the final nonnegative limit, applied after filtering and ordering regardless of builder order. A zero limit still validates every requirement. - [`matching`](/en/haskell/latest/reference/libtmux-query-v-matching/) (function): Conjoin a predicate with existing predicates without changing the source. - [`none`](/en/haskell/latest/reference/libtmux-query-v-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 :obj:`allOf ` when the same child must satisfy them. Unavailable relationships remain errors. - [`optionalRelated`](/en/haskell/latest/reference/libtmux-query-v-optionalrelated/) (function): Test a known optional target. Absence yields False, so negation includes absence as well as targets that fail the child predicate. - [`orderBy`](/en/haskell/latest/reference/libtmux-query-v-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`](/en/haskell/latest/reference/libtmux-query-v-paneoccurrences/) (function): Pane appearances in link order, then pane-index order within each window. - [`requirements`](/en/haskell/latest/reference/libtmux-query-v-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`](/en/haskell/latest/reference/libtmux-query-v-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`](/en/haskell/latest/reference/libtmux-query-v-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 :obj:`allOf ` when the same child must satisfy them. Unavailable relationships remain errors. ### Other members - [`allOf`](/en/haskell/latest/reference/libtmux-query-v-allof/) (function): Finite conjunction and disjunction. Empty lists mean True and False, respectively. Validation checks every branch before evaluation short-circuits. - [`anyOf`](/en/haskell/latest/reference/libtmux-query-v-anyof/) (function): Finite conjunction and disjunction. Empty lists mean True and False, respectively. Validation checks every branch before evaluation short-circuits. - [`ascending`](/en/haskell/latest/reference/libtmux-query-v-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`](/en/haskell/latest/reference/libtmux-query-t-cardinalityerror/) (data type): Selection cardinality without retaining observations or counting ambiguity. - [`contains`](/en/haskell/latest/reference/libtmux-query-v-contains/) (function): Exact, case-sensitive Text substring matching. Byte-bearing fields are deliberately excluded; use typed equality for their retained values. - [`descending`](/en/haskell/latest/reference/libtmux-query-v-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`](/en/haskell/latest/reference/libtmux-query-v-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 :obj:`not_ ` for a strict opposite bound. - [`eq`](/en/haskell/latest/reference/libtmux-query-v-eq/) (function): Exact equality in the field's declared type. No Unicode normalization, case folding or byte-to-text conversion is implicit. - [`Expr`](/en/haskell/latest/reference/libtmux-query-t-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`](/en/haskell/latest/reference/libtmux-query-t-field/) (data type): Fields belong to physical rows or contextual links, never both implicitly. - [`ge`](/en/haskell/latest/reference/libtmux-query-v-ge/) (function): Compare a mathematical Integer field with an unbounded threshold: greater-or-equal, greater, less-or-equal or less, respectively. - [`gt`](/en/haskell/latest/reference/libtmux-query-v-gt/) (function): Compare a mathematical Integer field with an unbounded threshold: greater-or-equal, greater, less-or-equal or less, respectively. - [`le`](/en/haskell/latest/reference/libtmux-query-v-le/) (function): Compare a mathematical Integer field with an unbounded threshold: greater-or-equal, greater, less-or-equal or less, respectively. - [`lt`](/en/haskell/latest/reference/libtmux-query-v-lt/) (function): Compare a mathematical Integer field with an unbounded threshold: greater-or-equal, greater, less-or-equal or less, respectively. - [`not_`](/en/haskell/latest/reference/libtmux-query-v-not_/) (function): Logical negation, preserving the expression's validation requirements. - [`oneOf`](/en/haskell/latest/reference/libtmux-query-v-oneof/) (function): Membership using exact equality against a finite operand list. An empty list never matches, but its field requirement is still validated. - [`Order`](/en/haskell/latest/reference/libtmux-query-t-order/) (data type): One ascending or descending field ordering. Combine keys with :obj:`orderBy `. - [`paneIndexAtLeast`](/en/haskell/latest/reference/libtmux-query-v-paneindexatleast/) (function): Inclusive bounds on a pane index, without narrowing or constructing an index. - [`paneIndexAtMost`](/en/haskell/latest/reference/libtmux-query-v-paneindexatmost/) (function): Inclusive bounds on a pane index, without narrowing or constructing an index. - [`Query`](/en/haskell/latest/reference/libtmux-query-t-query/) (data type): A source, predicate, stable ordering and optional final limit. Building a query performs no IO and retains no Server handle. Use :obj:`LibTmux.Query ` to evaluate. - [`QueryError`](/en/haskell/latest/reference/libtmux-query-t-queryerror/) (data type): Pure validation or navigation failure. Operational acquisition failures remain exceptions at the Server boundary rather than becoming empty results. - [`QueryRequirements`](/en/haskell/latest/reference/libtmux-query-t-queryrequirements/) (data type): Inspectable dependencies, not a serialized query or an optimization plan. - [`related`](/en/haskell/latest/reference/libtmux-query-v-related/) (function): Test the required related observation in the supplied snapshot. A failed lookup returns :obj:`RelationshipLookupFailed `, never False or absence. - [`serverInfo`](/en/haskell/latest/reference/libtmux-query-v-serverinfo/) (function): The single captured daemon-metadata observation. - [`ToMany`](/en/haskell/latest/reference/libtmux-query-t-tomany/) (data type): A closed one-to-many relationship. Obtain tokens from the entity field modules and use :obj:`some `, :obj:`every ` or :obj:`none `. Constructors are private. - [`ToOne`](/en/haskell/latest/reference/libtmux-query-t-toone/) (data type): A required relationship in a validated graph, used with :obj:`related `. - [`ToOptional`](/en/haskell/latest/reference/libtmux-query-t-tooptional/) (data type): An observed optional relationship, used with :obj:`optionalRelated `. Known absence is separate from an unavailable relationship. - [`windowIndexAtLeast`](/en/haskell/latest/reference/libtmux-query-v-windowindexatleast/) (function): Inclusive bounds on a contextual window index, using Integer thresholds. - [`windowIndexAtMost`](/en/haskell/latest/reference/libtmux-query-v-windowindexatmost/) (function): Inclusive bounds on a contextual window index, using Integer thresholds. - [`windowLinks`](/en/haskell/latest/reference/libtmux-query-v-windowlinks/) (function): Contextual links in session-ID then window-index order, retaining multiplicity. ## Guides Pages that discuss `LibTmux.Query`. - [Implementation status](/en/haskell/latest/guides/status/)