LEVIATHAN v962456e · 962456eee1

Standard Library

namespace term

Control of the terminal the program runs in: raw input mode and the window size.

since 0.1.0-alpha.1linux

Overview

In raw mode keys reach the program one at a time as they are pressed, without waiting for Enter and without being echoed, which is what full-screen terminal programs need. The runtime puts the terminal back to normal when the program ends, even if it fails halfway, so a crash does not leave the shell unusable. These functions act on standard input and standard output.

Description

term is a namespace of functions for programs that talk to a terminal directly: text editors, menus and full-screen interfaces.

Size. term::size() returns a term::WinSize with rows and cols. It asks the operating system first. If the answer is unavailable (the output is not a terminal) and the terminal is in raw mode, it falls back to asking the terminal itself with an escape sequence. If neither works, it returns the safe default of 24 rows by 80 columns. The function never throws.

Raw mode. Normally the terminal collects a whole line before your program sees it and echoes what you type. In raw mode your program receives each key as it is pressed and the terminal does not echo or interpret anything.

  • term::enableRaw() switches standard input into raw mode and returns true if it worked, or false if standard input is not a terminal.
  • term::restore() switches it back.
  • term::isRaw() tells you which mode is active.

The runtime restores the terminal on every way the program can end, even if restore() is never reached, so a program that crashes in the middle of drawing does not leave the user's shell in raw mode. While raw mode is on, Ctrl-C is delivered to your program as a plain byte instead of as the interrupt signal.

WinSize is a small class, constructed as term::WinSize(rows, cols), and its no-argument form is the 24 by 80 default. Mind the axis order when converting: the rows come first and are the height, the columns are the width.

WinSize values

term::WinSize fallback = term::WinSize();
console.writeln("default: ${fallback.rows} rows x ${fallback.cols} cols");
term::WinSize big = term::WinSize(50, 132);
console.writeln("custom: ${big.rows} rows x ${big.cols} cols");
console.writeln(term::isRaw());
Run it ▶
default: 24 rows x 80 cols
custom: 50 rows x 132 cols
false

Rules

  • size() never throws and never returns zero: it ends in the 24 by 80 default.
  • enableRaw() returns false when standard input is not a terminal; check the result before relying on single-key input.
  • Raw mode is restored automatically when the program exits, whether it ends normally, through env::exit, or through an uncaught exception.
  • None of the term functions can run in comptime code.
  • Watch for resizes with signal::on(signal::WINCH); see std.signal.

Examples

A full-screen program reads the size, enters raw mode for the time it needs, and restores the terminal:

term::WinSize size = term::size();
console.writeln("terminal is ${size.cols} columns wide");

if (term::enableRaw()) {
    // ... read keys and draw the screen here ...
    term::restore();
}
console.writeln("raw mode is on: ${term::isRaw()}");
not run — needs a terminal

Notes

Raw mode applies to standard input only (descriptor 0).

Examples

console.writeln(term::isRaw());
term::WinSize size = term::size();
console.writeln(size.rows > 0 && size.cols > 0);
term::WinSize fixed = term::WinSize(30, 100);
console.writeln("${fixed.cols} columns by ${fixed.rows} rows");
Run it ▶
false
true
100 columns by 30 rows

Types

  • WinSize — The size of a terminal window in character cells.

Functions

enableRaw

enableRaw() -> bool

Switch the terminal to raw input mode.

The call returns false and changes nothing when standard input is not a terminal, for example when input is piped from a file. Pair every successful call with restore.

Returns

true when raw mode is now on, false when standard input is not a terminal.

Examples

bool raw = term::enableRaw();
term::restore();
console.writeln(term::isRaw());
Run it ▶
false

Reading keys in raw mode

if (term::enableRaw()) {
    console.writeln("raw mode is on");
    term::restore();
} else {
    console.writeln("not running in a terminal");
}
not run — depends on standard input being an interactive terminal

See also: restore

isRaw

isRaw() -> bool

Report whether the terminal is currently in raw input mode.

Returns

true after a successful enableRaw and before restore, otherwise false.

Examples

console.writeln(term::isRaw());
term::enableRaw();
term::restore();
console.writeln(term::isRaw());
Run it ▶
false
false

See also: enableRaw

restore

restore() -> void

Return the terminal to its normal input mode.

Calling it when raw mode is not on does nothing.

Examples

term::restore();
console.writeln(term::isRaw());
Run it ▶
false

See also: enableRaw

size

size() -> WinSize

Ask for the size of the terminal window.

The size comes from the terminal attached to standard output. When it cannot be determined, for example because output goes to a file, the result is the default of 24 rows by 80 columns, so the call never fails.

Returns

The window size in rows and columns.

Examples

term::WinSize size = term::size();
console.writeln(size.rows > 0);
console.writeln(size.cols > 0);
Run it ▶
true
true

Reading the size of the real terminal

term::WinSize size = term::size();
console.writeln("window: ${size.cols} columns by ${size.rows} rows");
not run — the size depends on the terminal the program runs in

See also: WinSize

See also

  • WinSize — The size of a terminal window in character cells.
  • signal — Operating-system signals delivered to the program as streams.
  • Pty — Runs another program on a pseudo-terminal, so the child believes it is talking to a real terminal.
  • Console — The program's standard output as an object.