`term`

Terminal utilities and ANSI escape sequences - 16 foreground and background colours, text styles (bold, dim, italic, underline, blink, reverse, strikethrough), cursor movement (up/down/left/right/home/position/save/restore/show/hide), screen clearing, progress bars with percentage and elapsed time, frame-based spinners, interactive text menus with arrow-key navigation, and buffered output.

Load with: use term

What this module does

term is a comprehensive terminal UI toolkit. It exposes ANSI escape code tables as objects and provides high-level helpers for coloured text, progress bars, spinners, menus, and cursor control. All output goes through os.tepri. Terminal capability detection (colour support, Unicode support, TTY status) is available via utldt.

Quick example

use term

# Coloured text
prn(clrfg("error message", "red"))
prn(clrfg("success", "green"))

# Styled text
prn(bold("important"))
prn(undrl("underlined"))

# Progress bar
bar = prgcr(40, "█")
prn(prgrn(bar, 30, 100))  # "[████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░░] 30% (0s)"

# Spinner
sp = spncr(nil, nil)
prn(spnrn(sp, "loading..."))  # "| loading..."

# Screen / cursor
scrcl()       # clear screen
crhme()       # move cursor to home
crsve()       # save cursor position
crrst()       # restore cursor position
crshw()       # show cursor
crhde()       # hide cursor

Functions

Colour and style

clrfg(text, colour)

Wraps text in the ANSI foreground colour escape for colour (e.g. "red", "bright_blue"). Resets after.

clrbg(text, colour)

Wraps text in an ANSI background colour escape.

teclr(text, style)

Applies an ANSI text style ("bold", "dim", "underline", "blink", "reverse", "strikethrough").

bold(text), dim(text), undrl(text), blink(text), rvrse(text)

Convenience shortcuts for common text styles.

ansi()

Returns the full ANSI escape code table as an object with colors, backgrounds, styles, cursor, and screen sub-objects.

Cursor and screen

crhme()

Move cursor to home (top-left).

crpos(row, col)

Move cursor to absolute position.

crsve() / crrst()

Save and restore cursor position.

crshw() / crhde()

Show and hide the cursor.

scrcl()

Clear the entire screen.

scrln()

Clear from cursor to end of line.

Progress and spinners

prgcr(width, char)

Creates a progress bar config with given width and fill character. Default width 50, default char █.

prgrn(bar, current, total)

Renders the progress bar as a string with percentage and elapsed seconds.

spncr(frames, interval)

Creates a spinner with custom frames (defaults to |/-\) and interval in ms.

spnrn(spin, text)

Returns the next spinner frame + space + text. Call repeatedly to animate.

Menus

mnucr(title, options, multi)

Creates a menu state with a title, list of option strings, and optional multi-select flag.

mnadd(menu, option)

Adds an option string to the menu.

mnrnd(menu)

Renders the menu as a string with the selected option highlighted.

mnnxt(menu) / mnprv(menu)

Move selection down/up.

mnslc(menu)

Returns the currently selected option string.

Notes

Requires trl, txt, colr, os, and proc.