charm.program — de.timokramer/charm.clj 0.2.123

The Elm Architecture event loop for TUI applications.

A program consists of:

• init: Initial state and optional startup command
• update: (state, msg) -> [new-state, cmd]
• view: state -> string

Commands are functions that produce messages asynchronously.

batch clj

(batch & cmds)

Combine multiple commands into one.

cmd clj

(cmd f)

Create a command from a function that returns a message. The function will be called asynchronously.

quit-cmd clj

Command that sends a quit message.

run clj

(run {:keys [init update view running?] :as opts})

Run a TUI program.

Options: :init - (fn [] [initial-state cmd]) or initial state value :update - (fn [state msg] [new-state cmd]) :view - (fn [state] string) :alt-screen - Use alternate screen buffer (default: false) :mouse - Mouse mode: nil, :normal, :cell, or :all (default: nil) :focus-reporting - Report focus in/out (default: false) :fps - Frames per second (default: 60) :hide-cursor - Hide cursor (default: true) :sanitize - Drop every escape sequence but SGR styling from the view before it reaches the terminal (default: true). Turn this off only for a view that authors its own control sequences, and then sanitize untrusted parts of it with charm.ansi.sanitize/sanitize. :bracketed-paste - Ask the terminal to bracket pasted text (default: false). When on, a paste arrives as a single :paste message carrying the whole text instead of one key press per character, so an application can tell a paste from fast typing. Off by default, because a program that only handles key presses would stop seeing pastes at all. :overflow - Which end to drop lines from when the view is taller than the terminal: :top (default) keeps the last lines, which suits an inline program; :bottom keeps the first ones, which is usually what a full-screen program wants, since otherwise a view one line too tall loses its title. :ctrl-c - What Ctrl+C does: :quit (default) stops the program before update sees it, so a program that does not handle it can still be killed from the keyboard; :message delivers it to update as an ordinary "ctrl+c" key press and leaves quitting to the application. With :message, an application that never acts on it cannot be interrupted from the keyboard. :running? - Atom to control the event loop externally (default: internal atom) :color-profile - :ascii, :ansi, :ansi256 or :true-color, overriding detection (default: nil, detect from $TERM/$COLORTERM) :dark-background? - Override the terminal background query (default: nil, query the terminal)

The init function should return [initial-state cmd] or just initial-state. The update function receives (state msg) and returns [new-state cmd]. Commands are optional and can be nil.

At startup an :environment message with the :color-profile and :dark-background? in effect is sent, and both are bound for the duration of the program so colors resolve against the actual terminal. Pinning either option skips its detection; pinning :dark-background? also skips the terminal background query, and with it the probe timeout that terminals which never answer would otherwise cost at every startup.

run-async clj

(run-async opts)

Run a TUI program in the background. Returns a handle: :quit! - (fn [] ...) stop the program :result - promise, deref to get the final state

Accepts the same options as run.

sequence-cmds clj

(sequence-cmds & cmds)

Run commands in sequence (each waits for previous to complete).

window-size-msg clj

(window-size-msg width height)

Create a window size message.