tmux_model (libtmux for Erlang v0.0.1)

View Source

Validated native domain records. Constructors perform no tmux I/O.

Missing optional observations remain not_loaded; required identity fields must be supplied. Unavailable capabilities remain unavailable. Neither state means an empty relation or known absence. Rows created by new/2 and the entity constructors are detached. Entity constructors accept generated input-map types such as pane_input/0. Use new/2 to validate dynamic maps; Dialyzer checks known constructor shapes but does not replace runtime validation. Use tmux_server:bind/2 to register a fresh observed row for actions; use tmux_snapshot for captured graph relationships.

Observed rows carry a private observation/0 value. Actions compare it with the row's origin, snapshot identity and target fields, rejecting mismatched observations before I/O. Valid-shaped binding mismatches return observation_mismatch; detached and malformed rows keep their validation errors. Retarget through tmux_server:bind/2; it reads current values. This protects ordinary API use, not authority against trusted code in the Erlang VM.

Native model version 2 adds this association. Discard version-1 rows and snapshots on upgrade and freshly observe them. to_map/1 extracts domain fields for explicit schema validation; maps carry no actionable origin.

Summary

Types

Private captured target association, created by observation. Retain with its row; construction and field access are internal. It is not an authorization or serialization format.

A validated pane observation. Native records are experimental in OTP 29.

A canonical pane ID binary in the percent namespace; nominal checking is by Dialyzer.

Trusted constructor fields for pane/1. Required keys use :=; optional observations may be not_loaded or unavailable. Integral floats are normalized to integers. Runtime validation still checks ranges, IDs, UTF-8 and derived values. Use new/2 for dynamically validated maps.

One schema-defined native domain record, with separate origin and capture metadata.

A validated session observation. Native records are experimental in OTP 29.

A canonical session ID binary in the dollar namespace.

Trusted constructor fields for session/1. Required keys use :=; optional observations may be not_loaded or unavailable. Integral floats are normalized to integers. Runtime validation still checks ranges, IDs, UTF-8 and derived values. Use new/2 for dynamically validated maps.

A validated window observation. Native records are experimental in OTP 29.

A canonical physical-window ID binary in the at-sign namespace.

Trusted constructor fields for window/1. Required keys use :=; optional observations may be not_loaded or unavailable. Integral floats are normalized to integers. Runtime validation still checks ranges, IDs, UTF-8 and derived values. Use new/2 for dynamically validated maps.

A validated window_link observation. Native records are experimental in OTP 29.

Trusted constructor fields for window_link/1. Required keys use :=; optional observations may be not_loaded or unavailable. Integral floats are normalized to integers. Runtime validation still checks ranges, IDs, UTF-8 and derived values. Use new/2 for dynamically validated maps.

Functions

Return the built-in entity kind of a native row without I/O.

Read a permitted domain field without I/O. Unknown fields raise unknown_field; unloaded and unavailable values remain distinct.

Read the native model version. Unknown versions fail validation; record internals are not a persistence format.

Construct a detached row from validated observations.

Read the opaque origin token, or none for a detached row. This does not revalidate endpoint lifetime.

Construct a detached pane row, validating required fields and scalar bounds without tmux I/O.

Construct a detached session row, validating required fields and scalar bounds without tmux I/O.

Read the capture identity, or none when not associated with a snapshot. Performs no I/O.

Return domain field values without origin or capture metadata. This is not the portable filter wire representation. Performs no I/O.

Validate native row shape, model version and normalized observations. Exported records do not enforce these invariants at construction. Performs no I/O.

Construct a detached window row, validating required fields and scalar bounds without tmux I/O.

Construct a detached window_link row, validating required fields and scalar bounds without tmux I/O.

Types

observation()

-opaque observation()

Private captured target association, created by observation. Retain with its row; construction and field access are internal. It is not an authorization or serialization format.

pane()

-type pane() :: #pane{}.

A validated pane observation. Native records are experimental in OTP 29.

pane_id()

-nominal pane_id() :: binary().

A canonical pane ID binary in the percent namespace; nominal checking is by Dialyzer.

pane_input()

-type pane_input() ::
          #{id := pane_id(),
            window_id => window_id() | not_loaded | unavailable,
            index => non_neg_integer() | float() | not_loaded | unavailable,
            active => boolean() | not_loaded | unavailable,
            current_command => binary() | not_loaded | unavailable,
            current_path => binary() | not_loaded | unavailable,
            width => non_neg_integer() | float() | not_loaded | unavailable,
            height => non_neg_integer() | float() | not_loaded | unavailable,
            pid => pos_integer() | float() | none | not_loaded | unavailable,
            title => binary() | not_loaded | unavailable,
            dead => boolean() | not_loaded | unavailable,
            exit_status => integer() | float() | none | not_loaded | unavailable}.

Trusted constructor fields for pane/1. Required keys use :=; optional observations may be not_loaded or unavailable. Integral floats are normalized to integers. Runtime validation still checks ranges, IDs, UTF-8 and derived values. Use new/2 for dynamically validated maps.

row()

-type row() :: #session{} | #window{} | #window_link{} | #pane{}.

One schema-defined native domain record, with separate origin and capture metadata.

session()

-type session() :: #session{}.

A validated session observation. Native records are experimental in OTP 29.

session_id()

-nominal session_id() :: binary().

A canonical session ID binary in the dollar namespace.

session_input()

-type session_input() ::
          #{id := session_id(),
            name => binary() | not_loaded | unavailable,
            attached_count => non_neg_integer() | float() | not_loaded | unavailable,
            attached => boolean() | not_loaded | unavailable,
            created => non_neg_integer() | float() | not_loaded | unavailable}.

Trusted constructor fields for session/1. Required keys use :=; optional observations may be not_loaded or unavailable. Integral floats are normalized to integers. Runtime validation still checks ranges, IDs, UTF-8 and derived values. Use new/2 for dynamically validated maps.

window()

-type window() :: #window{}.

A validated window observation. Native records are experimental in OTP 29.

window_id()

-nominal window_id() :: binary().

A canonical physical-window ID binary in the at-sign namespace.

window_input()

-type window_input() ::
          #{id := window_id(),
            name => binary() | not_loaded | unavailable,
            width => non_neg_integer() | float() | not_loaded | unavailable,
            height => non_neg_integer() | float() | not_loaded | unavailable,
            pane_count => non_neg_integer() | float() | not_loaded | unavailable,
            layout => binary() | not_loaded | unavailable}.

Trusted constructor fields for window/1. Required keys use :=; optional observations may be not_loaded or unavailable. Integral floats are normalized to integers. Runtime validation still checks ranges, IDs, UTF-8 and derived values. Use new/2 for dynamically validated maps.

window_link()

-type window_link() :: #window_link{}.

A validated window_link observation. Native records are experimental in OTP 29.

Functions

entity/1

-spec entity(row()) -> tmux_schema:entity().

Return the built-in entity kind of a native row without I/O.

get/2

-spec get(atom(), row()) -> term().

Read a permitted domain field without I/O. Unknown fields raise unknown_field; unloaded and unavailable values remain distinct.

model_version/1

-spec model_version(row()) -> pos_integer().

Read the native model version. Unknown versions fail validation; record internals are not a persistence format.

new(Entity, Fields)

-spec new(atom(), map()) -> {ok, row()} | {error, tmux_schema:error_detail()}.

Construct a detached row from validated observations.

Accepts dynamic maps, including malformed input that returns a tagged tmux_schema:error_detail/0. For trusted typed code, prefer the entity constructors such as pane/1 and pane_input/0.

1> {ok, Pane} = tmux_model:new(pane, #{id => <<"%1">>, width => 120}), ok.
ok
2> tmux_model:get(width, Pane).
120

origin/1

-spec origin(row()) -> none | reference().

Read the opaque origin token, or none for a detached row. This does not revalidate endpoint lifetime.

pane(Fields)

-spec pane(pane_input()) -> {ok, pane()} | {error, tmux_schema:error_detail()}.

Construct a detached pane row, validating required fields and scalar bounds without tmux I/O.

session(Fields)

-spec session(session_input()) -> {ok, session()} | {error, tmux_schema:error_detail()}.

Construct a detached session row, validating required fields and scalar bounds without tmux I/O.

snapshot_id/1

-spec snapshot_id(row()) -> none | reference().

Read the capture identity, or none when not associated with a snapshot. Performs no I/O.

to_map/1

-spec to_map(row()) -> map().

Return domain field values without origin or capture metadata. This is not the portable filter wire representation. Performs no I/O.

validate(Row)

-spec validate(term()) -> {ok, row()} | {error, map()}.

Validate native row shape, model version and normalized observations. Exported records do not enforce these invariants at construction. Performs no I/O.

window(Fields)

-spec window(window_input()) -> {ok, window()} | {error, tmux_schema:error_detail()}.

Construct a detached window row, validating required fields and scalar bounds without tmux I/O.

window_link(Fields)

-spec window_link(window_link_input()) -> {ok, window_link()} | {error, tmux_schema:error_detail()}.

Construct a detached window_link row, validating required fields and scalar bounds without tmux I/O.