vtnamespacenamespace vtA small terminal emulator for snapshot tests (commons 0006-signals FR-025): a screen a given number of columns wide, either growing as it is written to (no height) or a given number of rows high and scrolling, that is fed what a program writes and shows what a person would see after it: the text, each cell's style kept apart from it, and the cursor.
What it understands, as xterm does:
width.ts): a wide character or emoji takes two cells (the second a continuation), a combining mark or another zero-width grapheme joins the cell before; a character that does not fit in the last column wraps to the next line (autowrap with the wrap deferred until the next character, so a line exactly as wide as the screen does not add an empty one), and a wide character that would cross the right edge wraps whole, leaving the last cell empty;newline: "crlf", as a terminal's line discipline turns a program's "\n" into CR LF), or only moves down (newline: "lf");cursor().visible;Erased cells take no style. A grapheme split across two writes is seen as two (the second joins the first cell, without changing its width).
import { createScreen } from "./vt.ts";
const s = createScreen({ width: 20 });
s.write("building\n\u001b[32m✅\u001b[0m done");
s.write("\u001b[1A\r\u001b[2Kbuilt");
s.text(); // "built\n✅ done"
s.cell(1, 0)?.style.fg; // { kind: "indexed", index: 2 }vtnamespacenamespace vtvt.Colourtypeno test imports ittype Colour =
| { readonly kind: "default" }
| { readonly kind: "indexed"; readonly index: number }
| { readonly kind: "rgb"; readonly r: number; readonly g: number; readonly b: number };A colour of text or background: the terminal's default, one of 256 indexed colours (0 to 15 the basic and bright ones), or 24-bit.
vt.Styletypeno test imports ittype Style = {
readonly bold: boolean;
readonly dim: boolean;
readonly italic: boolean;
readonly underline: boolean;
readonly blink: boolean;
readonly inverse: boolean;
readonly hidden: boolean;
readonly strike: boolean;
readonly fg: Colour;
readonly bg: Colour;
};How a cell's text is drawn, as SGR left it.
vt.PLAINconstno test imports itconst PLAIN: StyleThe style of a cell nothing styled: every attribute off, default colours.
vt.describeStylefunctionno test imports itfunction describeStyle(style: Style): stringA style in words, for a snapshot: the attributes on, then fg= and bg= where not the default; "" for PLAIN.
vt.sameStylefunctionno test imports itfunction sameStyle(a: Style, b: Style): booleanWhether two styles draw the same.
vt.Celltypeno test imports ittype Cell = { readonly text: string; readonly width: 0 | 1 | 2; readonly style: Style };One cell of the screen: a grapheme and its style; a wide grapheme's second cell is a continuation, of width 0 and empty text.
vt.Runtypeno test imports ittype Run = { readonly text: string; readonly style: Style };A run of cells of one style on a line, their text joined.
vt.Cursortypeno test imports ittype Cursor = { readonly row: number; readonly col: number; readonly visible: boolean };Where the cursor is (row and column from 0) and whether it is shown.
vt.ScreenOptionstypeno test imports ittype ScreenOptions = {
/** Columns; at least 1. */
readonly width: number;
/** Rows: the screen scrolls when a line feed is written on the last; without it, the screen grows. */
readonly height?: number;
/** "crlf" (the default): a line feed also returns the carriage, as a terminal's line discipline does; "lf": it only moves down. */
readonly newline?: "crlf" | "lf";
};The size of a screen and how it reads a line feed.
vt.Screentypeno test imports ittype Screen = {
/** Its width in columns. */
readonly width: number;
/** Its height in rows, or undefined where it… (808 characters)type Screen = {
/** Its width in columns. */
readonly width: number;
/** Its height in rows, or undefined where it grows. */
readonly height: number | undefined;
/** Feeds it what a program writes: text, or bytes decoded as UTF-8 (a character may be split across writes). */
write(data: string | Uint8Array): void;
/** Its lines as text: trailing spaces of each line and trailing empty lines left out. */
lines(): readonly string[];
/** Its lines joined by "\n". */
text(): string;
/** Its lines as runs of one style, trailing unstyled spaces and trailing empty lines left out. */
styled(): readonly (readonly Run[])[];
/** The cell at a row and column; undefined outside the screen. */
cell(row: number, col: number): Cell | undefined;
/** The cursor. */
cursor(): Cursor;
};A screen being written to.
vt.createScreenfunctionno test imports itfunction createScreen(options: ScreenOptions): ScreenA new, empty screen with the cursor at the top left, shown.
Colourtypeno test imports ittype Colour =
| { readonly kind: "default" }
| { readonly kind: "indexed"; readonly index: number }
| { readonly kind: "rgb"; readonly r: number; readonly g: number; readonly b: number };A colour of text or background: the terminal's default, one of 256 indexed colours (0 to 15 the basic and bright ones), or 24-bit.
Styletypeno test imports ittype Style = {
readonly bold: boolean;
readonly dim: boolean;
readonly italic: boolean;
readonly underline: boolean;
readonly blink: boolean;
readonly inverse: boolean;
readonly hidden: boolean;
readonly strike: boolean;
readonly fg: Colour;
readonly bg: Colour;
};How a cell's text is drawn, as SGR left it.
PLAINconstno test imports itconst PLAIN: StyleThe style of a cell nothing styled: every attribute off, default colours.
describeStylefunctionfunction describeStyle(style: Style): stringA style in words, for a snapshot: the attributes on, then fg= and bg= where not the default; "" for PLAIN.
sameStylefunctionno test imports itfunction sameStyle(a: Style, b: Style): booleanWhether two styles draw the same.
Celltypeno test imports ittype Cell = { readonly text: string; readonly width: 0 | 1 | 2; readonly style: Style };One cell of the screen: a grapheme and its style; a wide grapheme's second cell is a continuation, of width 0 and empty text.
Runtypeno test imports ittype Run = { readonly text: string; readonly style: Style };A run of cells of one style on a line, their text joined.
Cursortypeno test imports ittype Cursor = { readonly row: number; readonly col: number; readonly visible: boolean };Where the cursor is (row and column from 0) and whether it is shown.
ScreenOptionstypeno test imports ittype ScreenOptions = {
/** Columns; at least 1. */
readonly width: number;
/** Rows: the screen scrolls when a line feed is written on the last; without it, the screen grows. */
readonly height?: number;
/** "crlf" (the default): a line feed also returns the carriage, as a terminal's line discipline does; "lf": it only moves down. */
readonly newline?: "crlf" | "lf";
};The size of a screen and how it reads a line feed.
Screentypetype Screen = {
/** Its width in columns. */
readonly width: number;
/** Its height in rows, or undefined where it… (808 characters)type Screen = {
/** Its width in columns. */
readonly width: number;
/** Its height in rows, or undefined where it grows. */
readonly height: number | undefined;
/** Feeds it what a program writes: text, or bytes decoded as UTF-8 (a character may be split across writes). */
write(data: string | Uint8Array): void;
/** Its lines as text: trailing spaces of each line and trailing empty lines left out. */
lines(): readonly string[];
/** Its lines joined by "\n". */
text(): string;
/** Its lines as runs of one style, trailing unstyled spaces and trailing empty lines left out. */
styled(): readonly (readonly Run[])[];
/** The cell at a row and column; undefined outside the screen. */
cell(row: number, col: number): Cell | undefined;
/** The cursor. */
cursor(): Cursor;
};A screen being written to.
createScreenfunctionfunction createScreen(options: ScreenOptions): ScreenA new, empty screen with the cursor at the top left, shown.