Drafter.Session.Context (drafter v0.5.0)

Resolves the per-session services a process is operating on behalf of.

A Drafter session owns a compositor, an event manager, a screen manager and so on. The association between a process and its session's instances is held in the process dictionary, so it must be copied explicitly whenever work moves to another process: use capture/0 in the originating process and adopt/1 in the new one.

Resolution falls back to a globally registered process of the same name, so a widget can be rendered outside any session.

A session also carries the environment of the terminal it is attached to, read with terminal_env/0. For a session served over ssh or telnet that is the connecting client's environment, which is not the environment of the host the program runs on; terminal_env/0 falls back to the host's when no session set one.

Summary

Types

role()

Functions

adopt(context)

Adopt a context captured by capture/0.

capture()

Snapshot the calling process's context, for handing to another process.

cell_size()

The terminal's cell size as {width, height} in pixels, or nil when it has not answered — because the app did not ask with cell_size: true, or the terminal does not report it.

fetch!(role)

Like get/1, but raises with the role named rather than returning nil.

get(role)

The process serving role for the calling session.

key_release?()

Whether this session's terminal reports key releases.

keys()

The process-dictionary keys a session context occupies.

pixel_mouse?()

Whether this session's mouse events carry px, the pixel under the pointer.

put_cell_size(arg)

Record the terminal's cell size in pixels, from its {:cell_size, size} report.

put_key_release(supported?)

Record whether the terminal will report key releases.

put_pixel_mouse(on?)

Record whether the terminal sends mouse reports in pixels.

put_terminal_env(env)

Record the environment of the terminal this session is attached to.

put_terminal_protocol(protocol)

Record the graphics protocol the terminal answered a probe with.

roles()

Every role a session context carries.

terminal_env()

The environment of the terminal this session is attached to.

terminal_protocol()

The probed graphics protocol, or :unprobed when the terminal was never asked.

Types

role()

@type role() ::
  :event_manager
  | :compositor
  | :theme_manager
  | :screen_manager
  | :event_handler
  | :skin_manager

Functions

adopt(context)

@spec adopt(%{required(atom()) => pid()} | keyword()) :: :ok

Adopt a context captured by capture/0.

capture()

@spec capture() :: %{required(atom()) => pid()}

Snapshot the calling process's context, for handing to another process.

cell_size()

@spec cell_size() :: {pos_integer(), pos_integer()} | nil

The terminal's cell size as {width, height} in pixels, or nil when it has not answered — because the app did not ask with cell_size: true, or the terminal does not report it.

fetch!(role)

@spec fetch!(role()) :: pid() | atom()

Like get/1, but raises with the role named rather than returning nil.

get(role)

@spec get(role()) :: pid() | atom() | nil

The process serving role for the calling session.

Prefers the session's own instance, then a globally registered process of the same name, and finally nil.

key_release?()

@spec key_release?() :: boolean()

Whether this session's terminal reports key releases.

true only after the terminal has answered the query a key_release: true app sends at startup; false before that, for an app that did not opt in, and for a terminal that never answers.

keys()

@spec keys() :: [atom()]

The process-dictionary keys a session context occupies.

pixel_mouse?()

@spec pixel_mouse?() :: boolean()

Whether this session's mouse events carry px, the pixel under the pointer.

true only after the terminal has confirmed pixel reports to an app that asked with pixel_mouse: true; false before that, for an app that did not ask, and for a terminal that ignores the mode.

put_cell_size(arg)

@spec put_cell_size({pos_integer(), pos_integer()}) :: :ok

Record the terminal's cell size in pixels, from its {:cell_size, size} report.

put_key_release(supported?)

@spec put_key_release(boolean()) :: :ok

Record whether the terminal will report key releases.

The app loop calls this when {:key_release_support, supported?} arrives, before handing the event to the app.

put_pixel_mouse(on?)

@spec put_pixel_mouse(boolean()) :: :ok

Record whether the terminal sends mouse reports in pixels.

The app loop calls this when {:pixel_mouse, on?} arrives, before handing the event to the app.

put_terminal_env(env)

@spec put_terminal_env(%{required(String.t()) => String.t()}) :: :ok

Record the environment of the terminal this session is attached to.

env is a map of environment variable name to string value, as System.get_env/0 returns. Carried to other processes by capture/0 and adopt/1 like any other part of the context.

put_terminal_protocol(protocol)

@spec put_terminal_protocol(atom() | nil) :: :ok

Record the graphics protocol the terminal answered a probe with.

protocol is :kitty, :iterm2 or :sixel, or nil for a terminal that named none. Recording nil is not the same as recording nothing: a terminal that was asked and answered with no graphics is settled, and terminal_protocol/0 reports {:ok, nil} for it, where a terminal that was never asked reports :unprobed.

roles()

@spec roles() :: [role()]

Every role a session context carries.

terminal_env()

@spec terminal_env() :: %{required(String.t()) => String.t()}

The environment of the terminal this session is attached to.

The session's own environment when one was recorded with put_terminal_env/1, and the host process's environment otherwise. A session that recorded an empty map gets that empty map, not the host's environment.

terminal_protocol()

@spec terminal_protocol() :: {:ok, atom() | nil} | :unprobed

The probed graphics protocol, or :unprobed when the terminal was never asked.

A caller that gets :unprobed should fall back to detecting from terminal_env/0.