IF Commons GitHub

vt

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-terminal FR-005

A 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:

  • printable text by grapheme and display width (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;
  • CR, LF (also VT and FF), BS and TAB (stops every eight columns); LF also returns the carriage by default (newline: "crlf", as a terminal's line discipline turns a program's "\n" into CR LF), or only moves down (newline: "lf");
  • CSI cursor up, down, forward and back (A, B, C, D), next and previous line (E, F), column (G), row (d), position (H, f), save and restore (s, u, and ESC 7, ESC 8), erase in line (K 0, 1, 2) and in display (J 0, 1, 2, 3), and SGR (m: bold, dim, italic, underline, blink, inverse, hidden, strike, their resets, the 8, 16, 256 and 24-bit colours of text and background);
  • cursor shown and hidden (CSI ? 25 h and l), kept in cursor().visible;
  • every other control sequence, other private mode, OSC, DCS, APC, PM and SOS string, other escape and other control character: read and ignored. A sequence may be split across writes; bytes are decoded as UTF-8 across writes too.

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 }

Source: commons/terminal/src/vt.ts

3 of 22 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

vtnamespace
namespace vt
vt.Colourtypeno test imports it
type 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 it
type 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 it
const PLAIN: Style

The style of a cell nothing styled: every attribute off, default colours.

vt.describeStylefunctionno test imports it
function describeStyle(style: Style): string

A style in words, for a snapshot: the attributes on, then fg= and bg= where not the default; "" for PLAIN.

vt.sameStylefunctionno test imports it
function sameStyle(a: Style, b: Style): boolean

Whether two styles draw the same.

vt.Celltypeno test imports it
type 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 it
type Run = { readonly text: string; readonly style: Style };

A run of cells of one style on a line, their text joined.

vt.Cursortypeno test imports it
type 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 it
type 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 it
type 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 it
function createScreen(options: ScreenOptions): Screen

A new, empty screen with the cursor at the top left, shown.

Colourtypeno test imports it
type 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 it
type 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 it
const PLAIN: Style

The style of a cell nothing styled: every attribute off, default colours.

describeStylefunction
function describeStyle(style: Style): string

A style in words, for a snapshot: the attributes on, then fg= and bg= where not the default; "" for PLAIN.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

sameStylefunctionno test imports it
function sameStyle(a: Style, b: Style): boolean

Whether two styles draw the same.

Celltypeno test imports it
type 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 it
type Run = { readonly text: string; readonly style: Style };

A run of cells of one style on a line, their text joined.

Cursortypeno test imports it
type 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 it
type 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.

Screentype
type 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.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

createScreenfunction
function createScreen(options: ScreenOptions): Screen

A new, empty screen with the cursor at the top left, shown.

Imported by 12 tests of the run (12 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.