tmux_select (libtmux for Erlang v0.0.1)

View Source

Filter ordered captured rows without tmux I/O.

Use panes/1, windows/1, window_links/1 or sessions/1 with a tmux_snapshot to retain graph coverage. from_list/2 preserves supplied order, duplicates and row origins; it establishes only fields present in every row and loads no relationships. Filtering and take/2 retain the original coverage even if no rows remain.

where/2 accepts map criteria or a tmux_filter:t/0 portable filter. filter/2 accepts a unary Boolean function, whose exceptions propagate. Cardinality criteria validate the whole expression and its coverage before stopping at sufficient evidence. Selections are opaque values; use to_list/1 for functions in lists.

A snapshot-backed selection retains the complete captured graph, including rows removed by filtering. After relationship evaluation, store the result of to_list/1 and release other snapshot and selection references to allow that context to be collected. Row extraction preserves the supplied field binaries; caller-created subbinaries can still retain their backing allocation.

Summary

Types

Compact local inspection. size counts current materialized rows; coverage still describes the original captured context after filtering or take. snapshot_id is none for a list-backed selection. Capture bounds and query diagnostics are included only when that source metadata exists.

t()

A selection over schema-defined native domain records.

Ordered captured rows with observation and coverage context, not an extensible list protocol. The parameter describes the intended row type. OTP 29 Dialyzer can widen generic return variables to their declared bounds; it does not prove every entity relationship through one/1 or to_list/1. Runtime schema, coverage and action checks remain necessary.

Functions

Return the current materialized row count without I/O.

Return the exact local match count after full criteria and coverage validation. Performs no I/O.

Return whether this materialized selection is nonempty, without I/O.

Validate all criteria/coverage first, then stop at the first local match. Performs no I/O; an empty selection does not bypass validation.

Apply an ordinary unary Boolean function locally, preserving row order and context. Non-Booleans and callback failures propagate; they are not false matches. This is executable application code, not portable filter data.

Return the first current row or none. Additional matches are allowed. Performs no I/O.

Validate criteria and coverage, then stop at the first local match. Returns none when no row matches; performs no I/O.

Fold over current rows in order without I/O, using the function, accumulator, selection argument order. Arbitrary results are ordinary Erlang values.

Validate an ordinary list without rebinding, reordering or deduplicating it.

Prepare a trusted behaviour once, then apply its Boolean predicate.

Return the sole current row or a no_match/multiple_matches error. Ambiguity reports at_least = 2 rather than computing a needless exact count.

Validate criteria and coverage, then stop after enough local matches to establish cardinality. Returns a tagged cardinality result; performs no I/O.

Return the sole row directly, raising on zero or multiple matches. Use one/1 for tagged cardinality errors.

Filter locally with complete validation, then return the sole row directly. Raises on zero or multiple matches; performs no I/O.

Return the sole current row, {ok, none} on absence, or a multiple-match error. Performs no I/O.

Validate local criteria and return one row or known absence. A second match is an explicit ambiguity error; performs no I/O.

Select captured physical panes while retaining snapshot graph and coverage. Performs no I/O and preserves the snapshot's deterministic order.

Select captured sessions with their relationship and coverage context. Performs no I/O.

Return the cached number of materialized rows in this selection without traversing tmux or re-evaluating criteria.

Return a compact Erlang diagnostic map with entity, size, capture identity, interval and coverage. Fetched queries include candidate/attempt information. Opaque snapshot references make this a diagnostic value, not a wire format.

Keep the first N rows and retain the original observation and coverage. Performs no I/O; taking a subset cannot establish missing field coverage.

Return the current ordered rows as an ordinary Erlang list without I/O. Use list functions or comprehensions for transformations to other value types. Returns the stored rows without copying their binary fields. Keeping only the list allows the selection's snapshot context to be collected; other references can still keep that context alive.

Apply the same local criteria and coverage checks as where/2, returning tagged validation or evaluation errors. It does not catch arbitrary application callback exceptions and never performs tmux I/O.

Validate portable criteria and coverage, then preserve matching rows in order. Performs no I/O. Malformed trusted criteria raise bad_filter; missing coverage and runtime evaluation failures remain distinct exceptions. Use try_where/2 for tagged library errors.

Select all captured session memberships, retaining repeated physical windows and session-relative indexes. Performs no I/O.

Select unique captured physical windows with their complete graph context. Performs no I/O; session memberships remain separate window-link rows.

Types

cardinality_error()

-type cardinality_error() :: {error, no_match | {multiple_matches, #{at_least := 2}}}.

criteria()

-type criteria() :: map() | tmux_filter:t().

summary()

-type summary() ::
          #{entity := tmux_schema:entity(),
            size := non_neg_integer(),
            snapshot_id := reference() | none,
            coverage := tmux_snapshot:entity_coverage(),
            capture_started => integer(),
            capture_finished => integer(),
            time_unit => microsecond,
            query => tmux_snapshot:query_metadata()}.

Compact local inspection. size counts current materialized rows; coverage still describes the original captured context after filtering or take. snapshot_id is none for a list-backed selection. Capture bounds and query diagnostics are included only when that source metadata exists.

t()

-type t() :: t(tmux_model:row()).

A selection over schema-defined native domain records.

t(Row)

-opaque t(Row)

Ordered captured rows with observation and coverage context, not an extensible list protocol. The parameter describes the intended row type. OTP 29 Dialyzer can widen generic return variables to their declared bounds; it does not prove every entity relationship through one/1 or to_list/1. Runtime schema, coverage and action checks remain necessary.

Functions

count(Selection)

-spec count(t()) -> non_neg_integer().

Return the current materialized row count without I/O.

count/2

-spec count(criteria(), t()) -> non_neg_integer().

Return the exact local match count after full criteria and coverage validation. Performs no I/O.

exists/1

-spec exists(t()) -> boolean().

Return whether this materialized selection is nonempty, without I/O.

exists(Criteria, Selection)

-spec exists(criteria(), t()) -> boolean().

Validate all criteria/coverage first, then stop at the first local match. Performs no I/O; an empty selection does not bypass validation.

filter/2

-spec filter(fun((Row) -> boolean()), t(Row)) -> t(Row) when Row :: tmux_model:row().

Apply an ordinary unary Boolean function locally, preserving row order and context. Non-Booleans and callback failures propagate; they are not false matches. This is executable application code, not portable filter data.

first/1

-spec first(t(Row)) -> {ok, Row} | none when Row :: tmux_model:row().

Return the first current row or none. Additional matches are allowed. Performs no I/O.

first(Criteria, Selection)

-spec first(criteria(), t(Row)) -> {ok, Row} | none when Row :: tmux_model:row().

Validate criteria and coverage, then stop at the first local match. Returns none when no row matches; performs no I/O.

fold/3

-spec fold(fun((Row, Acc) -> Acc), Acc, t(Row)) -> Acc when Row :: tmux_model:row().

Fold over current rows in order without I/O, using the function, accumulator, selection argument order. Arbitrary results are ordinary Erlang values.

from_list(Entity, Rows)

-spec from_list(tmux_schema:entity(), [Row]) -> t(Row) when Row :: tmux_model:row().

Validate an ordinary list without rebinding, reordering or deduplicating it.

1> {ok, P} = tmux_model:pane(#{id => <<"%1">>, width => 120}), ok.
ok
2> S = tmux_select:from_list(pane, [P, P]), ok.
ok
3> tmux_select:size(tmux_select:where(#{width => #{gte => 120}}, S)).
2
4> tmux_select:one(S).
{error,{multiple_matches,#{at_least => 2}}}

matching/2

-spec matching({module(), term()}, t(Row)) -> {ok, t(Row)} | {error, term()}
                  when Row :: tmux_model:row().

Prepare a trusted behaviour once, then apply its Boolean predicate.

Uses tmux_matcher:prepare/2; preparation failure returns {error, Detail}. Exceptions in either callback propagate. A matcher requires a captured snapshot; a from_list/2 selection returns matcher_requires_snapshot. The application chooses Module.

one/1

-spec one(t(Row)) -> {ok, Row} | cardinality_error() when Row :: tmux_model:row().

Return the sole current row or a no_match/multiple_matches error. Ambiguity reports at_least = 2 rather than computing a needless exact count.

one(Criteria, Selection)

-spec one(criteria(), t(Row)) -> {ok, Row} | cardinality_error() when Row :: tmux_model:row().

Validate criteria and coverage, then stop after enough local matches to establish cardinality. Returns a tagged cardinality result; performs no I/O.

one_or_error(Selection)

-spec one_or_error(t(Row)) -> Row when Row :: tmux_model:row().

Return the sole row directly, raising on zero or multiple matches. Use one/1 for tagged cardinality errors.

one_or_error(Criteria, Selection)

-spec one_or_error(criteria(), t(Row)) -> Row when Row :: tmux_model:row().

Filter locally with complete validation, then return the sole row directly. Raises on zero or multiple matches; performs no I/O.

one_or_none(Selection)

-spec one_or_none(t(Row)) -> {ok, Row | none} | cardinality_error() when Row :: tmux_model:row().

Return the sole current row, {ok, none} on absence, or a multiple-match error. Performs no I/O.

one_or_none(Criteria, Selection)

-spec one_or_none(criteria(), t(Row)) -> {ok, Row | none} | cardinality_error()
                     when Row :: tmux_model:row().

Validate local criteria and return one row or known absence. A second match is an explicit ambiguity error; performs no I/O.

panes(Snapshot)

-spec panes(tmux_snapshot:t()) -> t(tmux_model:pane()).

Select captured physical panes while retaining snapshot graph and coverage. Performs no I/O and preserves the snapshot's deterministic order.

sessions(Snapshot)

-spec sessions(tmux_snapshot:t()) -> t(tmux_model:session()).

Select captured sessions with their relationship and coverage context. Performs no I/O.

size/1

-spec size(t()) -> non_neg_integer().

Return the cached number of materialized rows in this selection without traversing tmux or re-evaluating criteria.

summary/1

-spec summary(t()) -> summary().

Return a compact Erlang diagnostic map with entity, size, capture identity, interval and coverage. Fetched queries include candidate/attempt information. Opaque snapshot references make this a diagnostic value, not a wire format.

take/2

-spec take(non_neg_integer(), t(Row)) -> t(Row) when Row :: tmux_model:row().

Keep the first N rows and retain the original observation and coverage. Performs no I/O; taking a subset cannot establish missing field coverage.

to_list/1

-spec to_list(t(Row)) -> [Row] when Row :: tmux_model:row().

Return the current ordered rows as an ordinary Erlang list without I/O. Use list functions or comprehensions for transformations to other value types. Returns the stored rows without copying their binary fields. Keeping only the list allows the selection's snapshot context to be collected; other references can still keep that context alive.

try_where/2

-spec try_where(criteria(), t(Row)) -> {ok, t(Row)} | {error, map()} when Row :: tmux_model:row().

Apply the same local criteria and coverage checks as where/2, returning tagged validation or evaluation errors. It does not catch arbitrary application callback exceptions and never performs tmux I/O.

where(Criteria, Selection)

-spec where(criteria(), t(Row)) -> t(Row) when Row :: tmux_model:row().

Validate portable criteria and coverage, then preserve matching rows in order. Performs no I/O. Malformed trusted criteria raise bad_filter; missing coverage and runtime evaluation failures remain distinct exceptions. Use try_where/2 for tagged library errors.

window_links(Snapshot)

-spec window_links(tmux_snapshot:t()) -> t(tmux_model:window_link()).

Select all captured session memberships, retaining repeated physical windows and session-relative indexes. Performs no I/O.

windows(Snapshot)

-spec windows(tmux_snapshot:t()) -> t(tmux_model:window()).

Select unique captured physical windows with their complete graph context. Performs no I/O; session memberships remain separate window-link rows.