class

ArrTop::Terminal

Low-level terminal control for the TUI: the alternate screen buffer, cursor visibility, and raw/no-echo input — plus a guaranteed restore of the terminal to its normal state on every exit path.

The restore contract is the whole point of this class. A TUI that leaves the terminal in raw mode with a hidden cursor is a hard bug, so #restore is wired to run on: normal quit (the ensure in TUI#run), SIGINT/SIGTERM, an uncaught exception (also the ensure), and process exit (at_exit). It is idempotent — guarded by @active under a lock — so being called from several of those paths at once is safe.

Constants

ENTER_ALT = "\e[?1049h"

Enter the alternate screen buffer (so the user's scrollback is preserved).

FALLBACK = {rows: 24, cols: 80}

Fallback size when the ioctl fails (no tty, redirected, or an error).

HIDE_CURSOR = "\e[?25l"

Hide the cursor while the TUI paints.

LEAVE_ALT = "\e[?1049l"

Leave the alternate screen buffer, restoring the prior screen contents.

SHOW_CURSOR = "\e[?25h"

Show the cursor again.

Constructors

new(input : IO::FileDescriptor = STDIN, output : IO::FileDescriptor = STDOUT)

Source

Class methods

size(fd : Int32 = STDOUT.fd) : NamedTuple(rows: Int32, cols: Int32)

The terminal size as {rows, cols}, read fresh via TIOCGWINSZ so a resize is picked up on the next redraw without needing SIGWINCH. Any failure (not a tty, ioctl error, zero dimensions) yields {24, 80}.

Source

Instance methods

read_byte

Reads a single byte from input (blocking), or nil at EOF. Under raw mode each keypress returns immediately.

Source

restore

Restores the terminal to its normal state: cooked input, cursor shown, alternate screen left. Idempotent — safe to call from the run loop's ensure, a signal trap, and at_exit all in one run.

Source

size

Current terminal size (instance shortcut over the class method).

Source

start

Enters the TUI display state: alternate screen, hidden cursor, and raw + no-echo input so a single keypress (q) is delivered immediately. Installs the SIGINT/SIGTERM traps and the at_exit backstop so #restore runs no matter how the process ends. Raw mode is best-effort: if STDIN is not a tty it is skipped (the caller only starts a TUI when STDOUT is a tty).

Source

stop

Alias so callers can read #stop as the paired verb to #start.

Source

write(frame : String) : Nil

Writes frame to the output in one go and flushes, minimizing flicker.

Source