arizona_terminal_driver behaviour (arizona v0.4.0)

Behaviour for a terminal UI driver -- the policy that turns a ?terminal live view into a concrete terminal experience.

arizona_terminal_session is generic: it mounts the view, dispatches events, and re-renders, but holds no opinion about how the terminal looks or which keys mean what. A driver supplies that policy:

keys/2 maps raw input bytes to view events (or a stop request) -- the key map.
paint/3 turns a freshly rendered ANSI frame plus the view's effects into the bytes to write, and decides whether to keep going or stop -- the paint model.
setup/1 / teardown/1 emit one-shot bytes at start and on quit (e.g. hide / show the cursor, enter / leave the alternate screen).
init/1 creates the driver state threaded through the calls above.

Every callback is optional: arizona_terminal_default_driver ships a sensible default for each, and the session uses a driver's callback when it exports one, else that default. So a driver implements only the callbacks it changes, and passing arizona_terminal_default_driver itself uses all the defaults.

Summary

Types

command()

An action a key read produces: dispatch a view event, or stop the session.

Callbacks

init(Arg)

Create the driver's initial state. Arg is transport-supplied context.

keys(Bytes, State)

Map a raw input read (a byte binary) to commands and the next state. [] ignores the input. May keep state to buffer escape sequences across reads.

paint(Frame, Effects, State)

Turn the freshly rendered ANSI Frame and the view's Effects into the bytes to write, whether to continue or stop, and the next state.

setup(State)

One-shot output emitted before the first paint (e.g. hide the cursor).

teardown(State)

One-shot output emitted on quit, before stopping (e.g. show the cursor).

Types

command()

-nominal command() :: {event, Name :: binary(), Payload :: map()} | stop.

An action a key read produces: dispatch a view event, or stop the session.

Callbacks

init(Arg)

(optional)

-callback init(Arg :: term()) -> State :: term().

Create the driver's initial state. Arg is transport-supplied context.

keys(Bytes, State)

(optional)

-callback keys(Bytes :: binary(), State :: term()) -> {[command()], NewState :: term()}.

Map a raw input read (a byte binary) to commands and the next state. [] ignores the input. May keep state to buffer escape sequences across reads.

paint(Frame, Effects, State)

(optional)

-callback paint(Frame :: binary(), Effects :: [arizona_effect:cmd()], State :: term()) ->
                   {iodata(), continue | stop, NewState :: term()}.

Turn the freshly rendered ANSI Frame and the view's Effects into the bytes to write, whether to continue or stop, and the next state.

setup(State)

(optional)

-callback setup(State :: term()) -> {iodata(), NewState :: term()}.

One-shot output emitted before the first paint (e.g. hide the cursor).

teardown(State)

(optional)

-callback teardown(State :: term()) -> iodata().

One-shot output emitted on quit, before stopping (e.g. show the cursor).