Drafter.Session.Context (drafter v0.3.2)

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.

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.

keys()

The process-dictionary keys a session context occupies.

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.

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.

keys()

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

The process-dictionary keys a session context occupies.

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.