Tern

term

The term module is for programs that talk to a person at a terminal: whether output goes to one, its size, colors that turn themselves off when they shouldn't show, aligned tables, a progress line, and reading a password without echoing it.

import term

fn main():
    term.set_color(false)                  # (the docs' output isn't a terminal anyway)
    print(term.green("ok"), term.bold("3 files"))
    print(term.table([["NAME", "SIZE"], ["a.txt", "12"], ["notes.md", "3401"]]))
    print(term.display_width("héllo"), term.strip_ansi("\x1b[31mred\x1b[0m"))
Output
ok 3 files
NAME      SIZE
a.txt     12
notes.md  3401

5 red

Functions

fn is_tty() bool              stdout is a terminal
fn stderr_is_tty() bool       fn stdin_is_tty() bool
fn width() int                the terminal's columns ($COLUMNS, else 80, when there's none)
fn height() int               its rows ($LINES, else 24)
fn color() bool               whether the color functions add color
fn set_color(on: bool)        decide that yourself (a --color flag)
fn red(s: str) str            also green, yellow, blue, magenta, cyan, gray,
                              bold, dim, italic, underline
fn strip_ansi(s: str) str     s without escape sequences (colors, cursor moves, links)
fn display_width(s: str) int  the columns s takes: escapes none, each character one
fn pad(s: str, width: int) str      s and spaces up to width columns
fn table(rows: [[str]]) str   columns lined up two spaces apart, a line per row
fn progress(done: int, total: int, label: str)   a progress line on stderr
fn clear_line() str           "\r\x1b[2K": the start of the line, cleared
fn secret(prompt: str) str    prompt on stderr, then a line read without echo
fn read_line(prompt: str) str prompt on stderr, then a line the person can edit, with history

Colors

The color functions wrap text in ANSI escapes only when they would show: stdout is a terminal, NO_COLOR is unset, and TERM isn't dumb. FORCE_COLOR=1 turns them on regardless (CI logs that render color), and term.set_color(on) overrides both. The decision is made once, on the first use. Styles nest: term.bold(term.red("x")).

Progress and passwords

term.progress(done, total, label) draws label [######--------] 42% 21/50 on stderr, over the previous one, and ends the line when done == total. It draws nothing when stderr isn't a terminal, so a program can call it unconditionally and still have clean logs when piped.

term.secret(prompt) turns echo off while the person types (when stdin is a terminal) and returns the line without its line end, for a password or a token. On WebAssembly, which has no terminal control, it reads a plain line.

Reading a line

term.read_line(prompt) is os.read_line with a prompt and line editing: when stdin and stderr are terminals, the arrow keys, Home/End, Backspace/Delete and Ctrl-A/E/K/U/W edit the line, and Up/Down bring back the lines it returned before, as in a shell. It returns the line with its "\n", "" at the end of input (Ctrl-D on an empty line), and "\x03" for Ctrl-C. Piped input is read as a plain line. tern repl reads with it.

Compiles (not run here)
import term

fn main():
    while true:
        line = term.read_line("> ")
        if line == "" or line == "\x03":
            break
        print(line.trim().upper())
Source: docs/std/term.md. Every example on this page is compiled and run by tern x test docs.