IF Commons GitHub

width

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

Display width: how many columns of a terminal a text takes, and a text cut to a number of columns (commons 0006-signals FR-023). An escape sequence takes none and is never split; a grapheme (what a person sees as one character, found with Intl.Segmenter) is never split either; a wide character or an emoji takes two columns.

The width of a grapheme is an approximation of what terminals do (as wcwidth and the string-width package approximate it):

  • a control character, a combining mark, a format character (such as the zero-width joiner) or a variation selector alone: 0;
  • an emoji: 2 when it is shown as an emoji, which is when its first code point has the Emoji_Presentation property (✅ ❌ 👉), when it carries the emoji variation selector U+FE0F (⏭️ ⏹️ ⚠️, keycaps such as 1️⃣), or when it is a zero-width-joiner sequence (one glyph of two columns, however many code points it joins); the text variation selector U+FE0E makes it 1;
  • an East Asian Wide or Fullwidth character (CJK ideographs, kana, Hangul syllables, fullwidth forms): 2, by the ranges in WIDE, which follow Unicode's EastAsianWidth.txt in blocks rather than code point by code point (JavaScript has no property escape for it);
  • anything else: 1. Ambiguous-width characters (Greek, box drawing) count 1, as a terminal in a Western locale shows them.
import { cutToWidth, displayWidth } from "./width.ts";
displayWidth("✅ 测试"); // 7
cutToWidth("✅ 测试", 6); // "✅ 测"
cutToWidth("\u001b[31mfailed badly\u001b[0m", 7, "…"); // "\u001b[31mfailed…\u001b[0m"

Source: commons/terminal/src/width.ts

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

widthnamespace
namespace width
width.Tokentypeno test imports it
type Token = { readonly kind: "escape"; readonly text: string } | { readonly kind: "text"; readonly text: string };

A piece of a text: an escape sequence, or a run of text between them.

width.tokensfunctionno test imports it
function tokens(text: string): readonly Token[]

A text split into its escape sequences and the runs of text between them, in order; joined, the pieces are the text again.

width.graphemesfunctionno test imports it
function graphemes(text: string): readonly string[]

The graphemes of a text with no escape sequence, in order (extended grapheme clusters, by Intl.Segmenter).

width.graphemeWidthfunctionno test imports it
function graphemeWidth(grapheme: string): 0 | 1 | 2

The columns one grapheme takes: 0, 1 or 2 (see the module's rules).

width.displayWidthfunctionno test imports it
function displayWidth(text: string): number

The columns a text takes on a terminal: its graphemes' widths summed; escape sequences take none.

width.Splittypeno test imports it
type Split = {
  /** The longest beginning that takes at most the columns asked for, with every escape sequence before the cut. */
  readonly head: string;
  /** The rest: `head + tail` is the text. */
  readonly tail: string;
};

A text split in two at a number of columns.

width.splitAtWidthfunctionno test imports it
function splitAtWidth(text: string, width: number): Split

A text split where it reaches width columns, between two graphemes or escape sequences, never inside one: a wide character that would cross the edge goes to the tail. Escape sequences up to the first grapheme that does not fit stay in the head.

width.sgrParamsfunctionno test imports it
function sgrParams(escape: string): readonly number[] | undefined

The parameters of an SGR sequence (ESC [ ... m), or undefined for another sequence.

width.RESETconstno test imports it
const RESET: string

The SGR sequence that turns every style off.

width.cutToWidthfunctionno test imports it
function cutToWidth(text: string, width: number, ellipsis?: string): string

A text cut to at most width columns. A text that fits is returned as it is. Otherwise it is cut between graphemes so that it and the ellipsis (none by default; "…" is the usual one) fit; the escape sequences before the cut are kept, those after are dropped, and where a colour or another style was still on at the cut, the result ends with a reset so that the style does not run on. An ellipsis wider than width is left out.

Tokentypeno test imports it
type Token = { readonly kind: "escape"; readonly text: string } | { readonly kind: "text"; readonly text: string };

A piece of a text: an escape sequence, or a run of text between them.

tokensfunction
function tokens(text: string): readonly Token[]

A text split into its escape sequences and the runs of text between them, in order; joined, the pieces are the text again.

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

graphemesfunction
function graphemes(text: string): readonly string[]

The graphemes of a text with no escape sequence, in order (extended grapheme clusters, by Intl.Segmenter).

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

graphemeWidthfunction
function graphemeWidth(grapheme: string): 0 | 1 | 2

The columns one grapheme takes: 0, 1 or 2 (see the module's rules).

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

displayWidthfunction
function displayWidth(text: string): number

The columns a text takes on a terminal: its graphemes' widths summed; escape sequences take none.

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

Splittypeno test imports it
type Split = {
  /** The longest beginning that takes at most the columns asked for, with every escape sequence before the cut. */
  readonly head: string;
  /** The rest: `head + tail` is the text. */
  readonly tail: string;
};

A text split in two at a number of columns.

splitAtWidthfunction
function splitAtWidth(text: string, width: number): Split

A text split where it reaches width columns, between two graphemes or escape sequences, never inside one: a wide character that would cross the edge goes to the tail. Escape sequences up to the first grapheme that does not fit stay in the head.

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

sgrParamsfunction
function sgrParams(escape: string): readonly number[] | undefined

The parameters of an SGR sequence (ESC [ ... m), or undefined for another sequence.

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

RESETconst
const RESET: string

The SGR sequence that turns every style off.

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

cutToWidthfunction
function cutToWidth(text: string, width: number, ellipsis?: string): string

A text cut to at most width columns. A text that fits is returned as it is. Otherwise it is cut between graphemes so that it and the ellipsis (none by default; "…" is the usual one) fit; the escape sequences before the cut are kept, those after are dropped, and where a colour or another style was still on at the cut, the result ends with a reset so that the style does not run on. An ellipsis wider than width is left out.

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

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