term/tui
Build terminal applications with a Model interface, asynchronous commands, keyboard events, and terminal rendering.
Model, messages, and commands#
Import term/tui. Applications implement the Model interface with Init, Update, and View methods. Init returns the first command; Update handles a message and returns the next model and command; View returns the display. All three run serially on the thread calling Run. Value models return updated copies; pointer models mutate state and return their pointer. Interface dispatch invokes the concrete implementation.
Msg is an alias for any, so application-defined values can be messages. Cmd is an alias for func() Msg. Commands execute on native workers and return messages to the application loop. Keep model mutation in Update; capture immutable inputs for commands. Return tui.NoCmd or a zero Cmd when no effect is needed.
interface Model {
Init() Cmd;
Update(message Msg) (Model, Cmd);
View() string;
}
type Msg = any;
type Cmd = func() Msg;
A counter with asynchronous ticks#
Each tick command waits on a worker and returns a message; Update schedules the next tick. The application thread remains available for keyboard and resize events. Ctrl+C is a key message in raw mode, so handle it explicitly.
package main;
import "term/tui";
import "io";
import "time";
struct counter { count int; }
struct tickMsg {}
func (model counter) Init() tui.Cmd { return tui.Tick(time.Second, tickMsg{}); }
func (model counter) Update(message tui.Msg) (tui.Model, tui.Cmd) {
switch (event := message.(type)) {
case tui.KeyMsg:
if (event.Key == "ctrl+c" || event.Text == "q") return model, tui.Quit;
if (event.Key == "up" || event.Text == "+") model.count++;
if (event.Key == "down" || event.Text == "-") model.count--;
case tickMsg:
model.count++;
return model, tui.Tick(time.Second, tickMsg{});
case tui.EOFMsg: return model, tui.Quit;
}
return model, tui.NoCmd;
}
func (model counter) View() string {
return "Count: " + io.Sprint(model.count) + "\n↑/↓ or +/- to change · q to quit";
}
func main() {
program := tui.NewProgram(counter{}, tui.Options{AltScreen: true});
program.Run().unwrap();
}
Program lifecycle#
NewProgram accepts zero or one Options value. Options{} uses stdin/stdout, raw input, and redraws from the current line. AltScreen: true uses the alternate screen. Headless: true overrides terminal options, disables input, size events, View calls, and rendering. It supports command-only applications and tests without a terminal.
Keep Program at a stable address and never copy it after first use: it contains a mutex. Run is single-use. Send and Quit are safe from other threads; keep Program alive until those callers finish. The queue is unbounded. FIFO order is enqueue order; concurrent commands may complete in any order, and pending messages can be discarded when Quit is processed.
| API | Behavior |
|---|---|
NewProgram(model Model, options ...Options) Program | Construct a single-use application. |
(*Program).Run() Result<Model> | Return the final model, or a terminal/I/O/command-panic error. |
(*Program).Send(message Msg) bool | Queue before or during Run; false after shutdown. |
(*Program).Quit() bool | Enqueue QuitMsg. |
Effects, composition, and I/O#
Return command function values from Init or Update; the runner invokes them on workers. Batch runs children concurrently and delivers results as they finish. Sequence executes commands in order and waits for nested batches to finish; it enqueues results without waiting for Update to process them. Empty composites are valid.
Tick is a one-shot approximate timer in nanoseconds (for example, time.Second); negative durations panic. Schedule another tick from Update to repeat. The event loop polls approximately every 5ms; Tick uses time.Sleep. Each effect uses a native thread; bound the amount of concurrent work.
Read and Write operate on preopened independent streams. Do not use them on the terminal’s stdin/stdout. Open streams before Run, close them afterward, and use one reader/writer per stream. The existing os file registry is not internally synchronized: concurrent opening/closing/registering files while the terminal loop accesses that registry is unsupported. Custom commands may return application-specific I/O messages. Errors from Read/Write become ErrorMsg, rather than automatically stopping Run.
| API | Behavior |
|---|---|
NoCmd / zero(tui.Cmd) | No effect. |
Quit | Command returning QuitMsg. |
Batch(commands ...Cmd) Cmd | Concurrent effects. |
Sequence(commands ...Cmd) Cmd | Ordered effects, including nested batches. |
Tick(nanoseconds int, message Msg) Cmd | One-shot timer. |
Read(file os.File, count int) Cmd | Read up to count bytes; count must be positive. Returns ReadMsg or ErrorMsg. |
Write(file os.File, text string) Cmd | Write all text. Returns WriteMsg or ErrorMsg. |
Messages and keyboard input#
KeyMsg.Text contains one printable UTF-8 scalar; Key is rune, or space for ASCII space. Other key names include enter, tab, backspace, esc, up, down, left, right, home, end, insert, delete, pgup, pgdown, shift+tab, f1–f12, and ctrl+a–ctrl+z, with enter/tab/backspace taking precedence. NUL is ctrl+space; remaining control bytes use numeric names such as ctrl+28. Alt prefixes set Alt.
Split UTF-8 and common CSI/SS3 sequences are buffered. A lone Escape waits about 30ms. Invalid UTF-8 produces replacement characters; unrecognized escape sequences produce unknown keys. Ctrl+C is delivered to Update. Window dimensions are initially queued before Init results and polled approximately every 100ms. EOFMsg stops input polling; Update decides whether to quit.
| API | Behavior |
|---|---|
KeyMsg | Key string, Text string, Alt bool. |
WindowSizeMsg | Width int, Height int in terminal cells. |
ReadMsg | Bytes i8[], End bool. Empty successful reads report End; short nonempty reads do not imply EOF. |
WriteMsg | Bytes int successfully written. |
ErrorMsg | Error string from an I/O command. |
EOFMsg | Terminal input ended. |
QuitMsg | Stops Run; not delivered to Update. |
NoneMsg | Ignored; not delivered to Update. |
Cancellation and terminal restoration#
Run restores raw settings, shows the cursor, leaves the alternate screen, and restores Windows output mode on normal return, returned errors, and ordinary model-panic unwinding. Model panics propagate; command panics are recovered and become Run errors. OS signal termination, os.Exit, native crashes, and SIGKILL bypass deferred cleanup. Only one program may own the terminal at a time; do not read stdin or write stdout elsewhere during Run.
Shutdown requests cooperative cancellation and joins outstanding commands, including nested batch children. Command defers run. Arbitrary blocking native I/O cannot be forcibly interrupted and may delay Run returning until the call finishes. Terminal restoration occurs before worker joins. Use bounded I/O or application-specific cancellation. External threads and resources remain the caller’s responsibility; do not Return/Kill the Run thread. Pointers in messages still borrow their pointees.
Rendering and platforms#
Views redraw when changed or resized, clear stale content, translate newlines to CRLF, and accept SGR styles/colors. Other control characters are filtered. Excess lines/columns are clipped; the last column is reserved to avoid autowrap. Common combining/East Asian widths are estimated. Full grapheme/emoji layout, mouse input, bracketed paste, focus events, and extended keyboard protocols are not implemented.
The library uses term and native threads on Linux x86-64/AArch64/RISC-V64, macOS x86-64/AArch64, and Windows x86-64/AArch64 with a VT-capable console. Windows VT output mode is enabled and restored. WebAssembly compilation fails because native threading is required. Linux PTY behavior is tested; real Windows/macOS execution still needs host validation. Use a compiler with interface method dispatch and native thread support.