nish:term
Terminal input for a full-screen program: read a key the moment it is pressed, wait for one with a timeout that doubles as a frame clock, and ask the terminal whether it is one, how big it is, and to stop echoing.
import {
isTerminal,
readStdin,
setRawMode,
setTerminalRestore,
terminalSize,
waitStdin,
} from "nish:term";
import { readStdin, setRawMode, waitStdin } from "nish:term";
export const main = (): number => {
setRawMode(true);
const keys: u8[] = new Array<u8>(16);
let running = true;
while (running) {
if (waitStdin(16)) {
const n = readStdin(keys, 0, keys.length);
if (n === 0 || (n < 0 && n !== -11)) {
running = false; // stdin ended, or reading it failed
}
for (let i = 0; i < n && i < keys.length; i++) {
if (keys[i] === 113) {
running = false; // q
}
}
}
// advance and draw one frame
}
setRawMode(false);
return 0;
};
isTerminal
Whether a descriptor is a terminal, isatty; under Node tty.isatty.
readStdin
Up to len bytes of stdin into buf, without waiting: it asks select with a zero timeout before it reads.
setRawMode
Put stdin's terminal in raw mode, or back as it was.
setTerminalRestore
Keep a copy of bytes for the runtime to write to the terminal on stdout as the program ends, before termios is restored: the escapes that leave an alternate screen, show the cursor or turn mouse reporting off.
terminalSize
The size of the terminal on stdout, or on stderr when stdout is not one, read fresh on each call: read it again each frame to follow a resize.
waitStdin
Wait until stdin is readable or the time passes.
Each export is the global of the same name, renamed. The six carry the
tty capability, not net, and are C in runtime/runtime-term.c, which
section GC leaves out of a program that calls none of them. Errors are
numbers in nish:net's shape: >= 0 is success and a negative number the
errno, negated; -11 (nothing is waiting) and -25 (not a terminal) are
the same on every platform. stdin is never made non-blocking, because
O_NONBLOCK would be shared with the shell.
Linux and Darwin only, and WASI with differences: there readStdin waits
for its bytes (call waitStdin first), a waitStdin waits at least 10 ms,
and there is no terminal. A freestanding --target wasm32 build refuses all
six. Under Node readStdin, waitStdin, setRawMode and
setTerminalRestore throw, each naming itself; in a browser so do they, and
there isTerminal answers false and terminalSize [-25, 0].
Raw mode
It is cfmakeraw's input side without its output side: echo,
line editing, CR-to-NL, flow control and parity stripping are off, and a key
arrives as its bytes (an arrow as ESC [ A). ISIG stays on, so Ctrl-C is
still SIGINT; OPOST stays on, so "\n" needs no "\r".
The terminal is always put back
on setRawMode(false), when main
returns or process.exit is called, on every panic, and on every signal
whose default action ends the program, SIGKILL aside. Ctrl-Z restores it
while the program is stopped and enters raw mode again on fg.
Rules: https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#nishterm-terminal-input
Functions
isTerminal
Whether a descriptor is a terminal, isatty; under Node tty.isatty.
const isTerminal: (fd: i32) => boolean
fdi32requiredThe descriptor, 0 for stdin, 1 stdout, 2 stderr.
returnsboolean
true for a terminal; false for a pipe, a file, and always
under WASI.
readStdin
Up to len bytes of stdin into buf, without waiting: it asks select
with a zero timeout before it reads. Under --profile wasi it waits for
its bytes instead.
const readStdin: (buf: u8[], off: i32, len: i32) => i32
bufu8[]requiredA writable u8[].
offi32required
Where the first byte goes. The range [off, off + len) is
checked as netRead's is.
leni32required
The most bytes to read. A len of 0 answers 0, so ask for
at least one.
returnsi32
The count, 0 at the end of the stream, -11 when nothing is
waiting, or another negative errno.
setRawMode
Put stdin's terminal in raw mode, or back as it was. Each switch into raw
mode saves the termios that was there; asking for the mode it is already
in changes nothing, so setRawMode(false) is always safe. The terminal is
restored at exit, on a panic and on every signal that ends the program,
SIGKILL aside. A program started in the background is stopped by SIGTTOU
here until fg.
const setRawMode: (on: boolean) => i32
onbooleanrequiredtrue for raw mode, false for the mode it had.
returnsi32
0, -25 when stdin is not a terminal (and 0 for false
there), or the host's -errno when the terminal refuses.
setTerminalRestore
Keep a copy of bytes for the runtime to write to the terminal on stdout
as the program ends, before termios is restored: the escapes that leave an
alternate screen, show the cursor or turn mouse reporting off. They go out
once, with write alone, when main returns or process.exit is called,
on every panic and on every signal whose default ends the program, raw
mode or not; Ctrl-Z and setRawMode(false) write nothing. Set them again
with each change, last the set that undoes them all.
const setTerminalRestore: (bytes: string) => i32
bytesstringrequired
The bytes to keep, replacing what was kept before; ""
keeps nothing.
returnsi32
0; -25 when stdout is not a terminal and -7 (E2BIG) past
NISH_TERM_RESTORE_MAX, 4096 bytes, both keeping what was there.
terminalSize
The size of the terminal on stdout, or on stderr when stdout is not one,
read fresh on each call: read it again each frame to follow a resize.
Under Node, its columns and rows.
const terminalSize: () => i32[]
returnsi32[]
A new [columns, rows]; [-errno, 0] when neither stream is a
terminal, [-25, 0] for "not a terminal", and [0, 0] for a terminal no
one set a size for.
waitStdin
Wait until stdin is readable or the time passes. Readable includes its end
and an error, so the read after it answers at once, with 0 or a negative
errno that is not -11, which a loop treats as the end. A Ctrl-Z and
fg after setRawMode(true) does not end the wait early: it goes on for
what is left of the timeout. Before raw mode Linux goes on and Darwin ends
the wait. Not willreturn.
const waitStdin: (timeoutMs: i32) => boolean
timeoutMsi32requiredThe most milliseconds to wait; negative waits for ever. Under WASI a wait is at least 10 ms.
returnsboolean
true when stdin is readable, false when the time ran out
first or a signal ended the wait.

