tmux_query (libtmux for Erlang v0.0.1)

View Source

Build and execute explicit queries over the tmux graph.

Use fetch/1 to execute a query. Constructors, where/2, limit/2, pushdown/2 and explain/1 perform no tmux I/O. Criteria are validated when added, and repeated conditions conjoin. Fetching returns an ordered tmux_select selection backed by a complete tmux_snapshot graph. By default the full captured view is filtered locally. Enable native candidate exclusion with pushdown/2: it can add a scan without reducing complete-graph hydration. The candidate is a necessary condition; the full filter still runs before the limit.

Captures span commands and are not atomic. Candidate IDs excluded at one observation cannot be recovered by later local filtering. Disabling pushdown/2 evaluates the complete captured view without an earlier candidate exclusion. Numeric candidate fields come from the restricted scalar codec and must agree with the capture's scalar observations. Text and relationships remain local.

Captures emit bounded OTP Logger reports with their snapshot ID and endpoint generation. See runtime diagnostics for observation cost, rejection reports and configuration.

1> Q0 = tmux_query:panes(unopened), ok.
ok
2> Q = tmux_query:where(#{width => #{gte => 120}}, Q0), ok.
ok
3> maps:get(format, maps:get(candidate, tmux_query:explain(Q))).
<<"1">>
4> Pushed = tmux_query:pushdown(true, Q), ok.
ok
5> maps:get(format, maps:get(candidate, tmux_query:explain(Pushed))).
<<"#{e|>=|:#{pane_width},120}">>

Summary

Types

Native necessary condition. format is a rendered tmux expression; exact means the translation covers the whole predicate for one observed state. A true fallback can admit every row. numeric_range describes qualified integer conversion, and is omitted for disabled/oversized fallback plans.

Capture phases: initial identity/scalar scans, optional candidate scans, complete text/byte hydration and final identity/scalar scans. hydration gives the default batched templates; isolated_hydration describes the explicit isolated option and unqualified-field fallback. An empty server skips window/pane scans. Execution still validates capture bounds and can fail.

Capture bounds plus an explicitly requested single inconsistent-capture retry; default retry is zero.

Why part of a predicate stays local. field and relation contain stable schema IDs, not Erlang names or tmux formats. An unsupported leaf may broaden the native condition; it never removes the full local predicate.

Pure explanation of a query. pushdown reports whether candidate exclusion is enabled (disabled by default). residual is the full portable predicate, required lists coverage requirements, and limit applies after residual evaluation. ordering and deduplication name the identity policy, not arbitrary map order. capabilities describes the planner baseline without probing a live endpoint.

Diagnostic command template, not executable argv. Scan templates carry args; text/byte hydration escapes each field once before column framing. Unqualified schema fields use isolated target = observed_id templates, resolved only while capturing. codec states how returned data is framed, including the version-specific print layer. This value grants no atomicity or persistent-connection guarantee.

t()

An immutable description of future tmux reads. Only fetch executes it.

Functions

Inspect command templates, necessary candidate conditions, full residual, hydration, required fields, ordering and temporal assumptions. Performs no I/O and does not contact the endpoint to claim dynamic capabilities.

Execute with default capture bounds and no retry. Returns an ordered selection whose complete graph remains locally readable. See fetch/2 for resource limits, requested retries and operational errors.

Execute the planned observation, full local predicate and final limit.

Set a final result limit from 0 through 65536, applied after residual filtering and identity handling. It is not a candidate-fetch limit. Performs no I/O; invalid counts raise bad_query_limit.

Describe a future server-wide physical pane query. Performs no I/O; fetch/1 is the execution boundary.

Enable or disable native candidate exclusion, returning a new query. The default is disabled: evaluate the complete captured view locally. Enabling it can add a candidate scan without reducing hydration; neither mode promises an atomic graph. Performs no I/O.

Describe a future server-wide session query without executing tmux.

Validate trusted criteria for this entity and conjoin them with prior conditions. Successive calls share the same normalized resource limits as one flat conjunction. Each relationship quantifier retains its own scope. Returns a new immutable query; malformed criteria raise bad_filter. Performs no I/O.

Describe a future query over session-relative window memberships. Repeated physical windows retain distinct membership identity. Performs no I/O.

Describe a future query over unique physical windows. Performs no I/O.

Types

candidate()

-type candidate() ::
          #{format := binary(),
            exact := boolean(),
            local_only := [local_reason()],
            numeric_range => {0, 9007199254740991}}.

Native necessary condition. format is a rendered tmux expression; exact means the translation covers the whole predicate for one observed state. A true fallback can admit every row. numeric_range describes qualified integer conversion, and is omitted for disabled/oversized fallback plans.

command_plan()

-type command_plan() ::
          #{initial_spine := [source_command()],
            candidate := [source_command()],
            hydration := [source_command()],
            isolated_hydration := [source_command()],
            final_spine := [source_command()],
            empty_server := skip_window_and_pane_scans}.

Capture phases: initial identity/scalar scans, optional candidate scans, complete text/byte hydration and final identity/scalar scans. hydration gives the default batched templates; isolated_hydration describes the explicit isolated option and unqualified-field fallback. An empty server skips window/pane scans. Execution still validates capture bounds and can fail.

fetch_options()

-type fetch_options() ::
          #{deadline_ms => 1..600000,
            max_rows => 1..65536,
            max_bytes => 1..67108864,
            hydration => tmux_server:hydration(),
            consistency => observed | atomic,
            retry => 0 | 1}.

Capture bounds plus an explicitly requested single inconsistent-capture retry; default retry is zero.

local_reason()

-type local_reason() ::
          #{reason :=
                disabled | format_limit | inexact_negation | unqualified_scalar_codec |
                complete_relationship_required,
            field => binary(),
            relation => binary(),
            operator => tmux_schema:operator()}.

Why part of a predicate stays local. field and relation contain stable schema IDs, not Erlang names or tmux formats. An unsupported leaf may broaden the native condition; it never removes the full local predicate.

plan()

-type plan() ::
          #{entity := tmux_schema:entity(),
            pushdown := boolean(),
            candidate := candidate(),
            residual := tmux_filter:wire_document(),
            required := [tmux_snapshot:requirement()],
            limit := infinity | 0..65536,
            commands := command_plan(),
            hydration := complete_graph,
            ordering := session_index_window | numeric_id,
            deduplication := membership | physical_id,
            capabilities := #{minimum_tmux := binary(), transport := one_shot},
            consistency := observed,
            atomic := false,
            candidate_scalars := same_row_checked_against_spine,
            text_and_relations := later_observations,
            temporal_limit := excluded_rows_cannot_be_recovered}.

Pure explanation of a query. pushdown reports whether candidate exclusion is enabled (disabled by default). residual is the full portable predicate, required lists coverage requirements, and limit applies after residual evaluation. ordering and deduplication name the identity policy, not arbitrary map order. capabilities describes the planner baseline without probing a live endpoint.

Capture spans commands. Candidate scalar values are checked against the first scan; text and relationships are later observations. Excluded rows cannot be recovered after state changes. Even an exact candidate is not an atomic query.

source_command()

-type source_command() ::
          #{entity := tmux_schema:entity(),
            command := binary(),
            format := binary(),
            transport := one_shot,
            codec := scalar_spine,
            kind := tmux_schema:entity(),
            args := [binary()],
            filter => binary()} |
          #{entity := tmux_schema:entity(),
            fields := [atom()],
            command := binary(),
            format := binary(),
            transport := one_shot,
            codec := escaped_columns_v1,
            args := [binary()]} |
          #{entity := tmux_schema:entity(),
            field := atom(),
            command := binary(),
            format := binary(),
            transport := one_shot,
            codec := id_prefixed_quoted_field,
            target := observed_id}.

Diagnostic command template, not executable argv. Scan templates carry args; text/byte hydration escapes each field once before column framing. Unqualified schema fields use isolated target = observed_id templates, resolved only while capturing. codec states how returned data is framed, including the version-specific print layer. This value grants no atomicity or persistent-connection guarantee.

t()

-opaque t()

An immutable description of future tmux reads. Only fetch executes it.

Functions

explain/1

-spec explain(t()) -> plan().

Inspect command templates, necessary candidate conditions, full residual, hydration, required fields, ordering and temporal assumptions. Performs no I/O and does not contact the endpoint to claim dynamic capabilities.

fetch(Query)

-spec fetch(t()) -> {ok, tmux_select:t()} | {error, map()}.

Execute with default capture bounds and no retry. Returns an ordered selection whose complete graph remains locally readable. See fetch/2 for resource limits, requested retries and operational errors.

fetch/2

-spec fetch(t(), fetch_options()) -> {ok, tmux_select:t()} | {error, map()}.

Execute the planned observation, full local predicate and final limit.

Capture options are those of tmux_server:snapshot/2. retry is 0 (default) or 1 and retries only inconsistent_capture, within the original capture deadline. The retry is a new read-only capture. No mutations are retried. Invalid capture requests return tagged errors, including unsupported consistency.

1> tmux_query:fetch(tmux_query:panes(unopened), #{retry => 2}).
{error,#{code => invalid_query_options}}

limit/2

-spec limit(0..65536, t()) -> t().

Set a final result limit from 0 through 65536, applied after residual filtering and identity handling. It is not a candidate-fetch limit. Performs no I/O; invalid counts raise bad_query_limit.

panes(Server)

-spec panes(tmux_server:t()) -> t().

Describe a future server-wide physical pane query. Performs no I/O; fetch/1 is the execution boundary.

pushdown(Enabled, Query)

-spec pushdown(boolean(), t()) -> t().

Enable or disable native candidate exclusion, returning a new query. The default is disabled: evaluate the complete captured view locally. Enabling it can add a candidate scan without reducing hydration; neither mode promises an atomic graph. Performs no I/O.

sessions(Server)

-spec sessions(tmux_server:t()) -> t().

Describe a future server-wide session query without executing tmux.

where/2

-spec where(map() | tmux_filter:t(), t()) -> t().

Validate trusted criteria for this entity and conjoin them with prior conditions. Successive calls share the same normalized resource limits as one flat conjunction. Each relationship quantifier retains its own scope. Returns a new immutable query; malformed criteria raise bad_filter. Performs no I/O.

window_links(Server)

-spec window_links(tmux_server:t()) -> t().

Describe a future query over session-relative window memberships. Repeated physical windows retain distinct membership identity. Performs no I/O.

windows(Server)

-spec windows(tmux_server:t()) -> t().

Describe a future query over unique physical windows. Performs no I/O.