@intellectual-frontiers/terminal 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +8 -2
- package/dist/args.d.ts +240 -0
- package/dist/args.js +328 -0
- package/dist/commands.d.ts +103 -0
- package/dist/commands.js +127 -0
- package/dist/mod.d.ts +19 -0
- package/dist/mod.js +20 -0
- package/dist/palette.d.ts +44 -0
- package/dist/palette.js +84 -0
- package/dist/vt.d.ts +78 -0
- package/dist/vt.js +486 -0
- package/dist/width.d.ts +63 -0
- package/dist/width.js +170 -0
- package/package.json +63 -4
- package/src/args.ts +547 -0
- package/src/commands.ts +182 -0
- package/src/mod.ts +20 -0
- package/src/palette.ts +104 -0
- package/src/vt.ts +497 -0
- package/src/width.ts +181 -0
package/dist/width.js
ADDED
|
@@ -0,0 +1,170 @@
|
|
|
1
|
+
// Spec: 0001-terminal FR-004
|
|
2
|
+
/**
|
|
3
|
+
* 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
|
|
4
|
+
* escape sequence takes none and is never split; a grapheme (what a person sees as one character, found with `Intl.Segmenter`) is never
|
|
5
|
+
* split either; a wide character or an emoji takes two columns.
|
|
6
|
+
*
|
|
7
|
+
* The width of a grapheme is an approximation of what terminals do (as `wcwidth` and the `string-width` package approximate it):
|
|
8
|
+
* - a control character, a combining mark, a format character (such as the zero-width joiner) or a variation selector alone: 0;
|
|
9
|
+
* - an emoji: 2 when it is shown as an emoji, which is when its first code point has the `Emoji_Presentation` property (✅ ❌ 👉), when
|
|
10
|
+
* it carries the emoji variation selector U+FE0F (⏭️ ⏹️ ⚠️, keycaps such as 1️⃣), or when it is a zero-width-joiner sequence (one glyph
|
|
11
|
+
* of two columns, however many code points it joins); the text variation selector U+FE0E makes it 1;
|
|
12
|
+
* - an East Asian Wide or Fullwidth character (CJK ideographs, kana, Hangul syllables, fullwidth forms): 2, by the ranges in `WIDE`,
|
|
13
|
+
* which follow Unicode's `EastAsianWidth.txt` in blocks rather than code point by code point (JavaScript has no property escape for it);
|
|
14
|
+
* - anything else: 1. Ambiguous-width characters (Greek, box drawing) count 1, as a terminal in a Western locale shows them.
|
|
15
|
+
*
|
|
16
|
+
* @example
|
|
17
|
+
* ```ts
|
|
18
|
+
* import { cutToWidth, displayWidth } from "./width.ts";
|
|
19
|
+
* displayWidth("✅ 测试"); // 7
|
|
20
|
+
* cutToWidth("✅ 测试", 6); // "✅ 测"
|
|
21
|
+
* cutToWidth("\u001b[31mfailed badly\u001b[0m", 7, "…"); // "\u001b[31mfailed…\u001b[0m"
|
|
22
|
+
* ```
|
|
23
|
+
*
|
|
24
|
+
* @module
|
|
25
|
+
*/
|
|
26
|
+
const ESC = String.fromCharCode(0x1b);
|
|
27
|
+
const BEL = String.fromCharCode(0x07);
|
|
28
|
+
/**
|
|
29
|
+
* An escape sequence: a control sequence (CSI, even one cut off at the end of the text), a string sequence (OSC, DCS, SOS, PM, APC) up
|
|
30
|
+
* to its terminator (BEL or ESC \) or the end, another escape (`ESC 7`, `ESC ( B`), or a lone ESC.
|
|
31
|
+
*/
|
|
32
|
+
const ESCAPE = new RegExp(`${ESC}(?:\\[[0-?]*[ -/]*[@-~]?|[\\]PX^_][^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)?|[ -/]*[0-~]|)`, "g");
|
|
33
|
+
/** A text split into its escape sequences and the runs of text between them, in order; joined, the pieces are the text again. */
|
|
34
|
+
export function tokens(text) {
|
|
35
|
+
const out = [];
|
|
36
|
+
let last = 0;
|
|
37
|
+
for (const m of text.matchAll(ESCAPE)) {
|
|
38
|
+
if (m.index > last)
|
|
39
|
+
out.push({ kind: "text", text: text.slice(last, m.index) });
|
|
40
|
+
out.push({ kind: "escape", text: m[0] });
|
|
41
|
+
last = m.index + m[0].length;
|
|
42
|
+
}
|
|
43
|
+
if (last < text.length)
|
|
44
|
+
out.push({ kind: "text", text: text.slice(last) });
|
|
45
|
+
return out;
|
|
46
|
+
}
|
|
47
|
+
const segmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
|
|
48
|
+
/** The graphemes of a text with no escape sequence, in order (extended grapheme clusters, by `Intl.Segmenter`). */
|
|
49
|
+
export function graphemes(text) {
|
|
50
|
+
return Array.from(segmenter.segment(text), (s) => s.segment);
|
|
51
|
+
}
|
|
52
|
+
/** East Asian Wide and Fullwidth ranges (inclusive), by block; emoji are told apart by their own properties. */
|
|
53
|
+
const WIDE = [
|
|
54
|
+
[0x1100, 0x115f], // Hangul Jamo, leading consonants
|
|
55
|
+
[0x2329, 0x232a], // angle brackets
|
|
56
|
+
[0x2e80, 0x303e], // CJK radicals, Kangxi radicals, ideographic description, CJK symbols and punctuation
|
|
57
|
+
[0x3041, 0x33ff], // Hiragana, Katakana, Bopomofo, Hangul compatibility Jamo, Kanbun, CJK strokes, enclosed CJK, CJK compatibility
|
|
58
|
+
[0x3400, 0x4dbf], // CJK extension A
|
|
59
|
+
[0x4e00, 0x9fff], // CJK unified ideographs
|
|
60
|
+
[0xa000, 0xa4cf], // Yi
|
|
61
|
+
[0xa960, 0xa97f], // Hangul Jamo extended A
|
|
62
|
+
[0xac00, 0xd7a3], // Hangul syllables
|
|
63
|
+
[0xf900, 0xfaff], // CJK compatibility ideographs
|
|
64
|
+
[0xfe10, 0xfe19], // vertical forms
|
|
65
|
+
[0xfe30, 0xfe6f], // CJK compatibility forms, small form variants
|
|
66
|
+
[0xff00, 0xff60], // fullwidth forms
|
|
67
|
+
[0xffe0, 0xffe6], // fullwidth signs
|
|
68
|
+
[0x16fe0, 0x16fe4], // ideographic symbols
|
|
69
|
+
[0x17000, 0x18cff], // Tangut, Khitan
|
|
70
|
+
[0x1b000, 0x1b2ff], // kana supplement and extensions, Nushu
|
|
71
|
+
[0x1f200, 0x1f2ff], // enclosed ideographic supplement
|
|
72
|
+
[0x20000, 0x2fffd], // CJK extensions B to F, compatibility supplement
|
|
73
|
+
[0x30000, 0x3fffd], // CJK extensions G and H
|
|
74
|
+
];
|
|
75
|
+
const isWide = (cp) => WIDE.some(([lo, hi]) => cp >= lo && cp <= hi);
|
|
76
|
+
const isControl = (cp) => cp < 0x20 || (cp >= 0x7f && cp < 0xa0);
|
|
77
|
+
const ZERO = /^[\p{Mn}\p{Me}\p{Cf}\u{fe00}-\u{fe0f}]+$/u;
|
|
78
|
+
const PRESENTATION = /^\p{Emoji_Presentation}/u;
|
|
79
|
+
const PICTOGRAPHIC = /\p{Extended_Pictographic}/u;
|
|
80
|
+
const EMOJI = /\p{Emoji}/u;
|
|
81
|
+
/** The columns one grapheme takes: 0, 1 or 2 (see the module's rules). */
|
|
82
|
+
export function graphemeWidth(grapheme) {
|
|
83
|
+
const cp = grapheme.codePointAt(0);
|
|
84
|
+
if (cp === undefined || isControl(cp) || ZERO.test(grapheme))
|
|
85
|
+
return 0;
|
|
86
|
+
if (grapheme.includes("\u{fe0e}"))
|
|
87
|
+
return 1;
|
|
88
|
+
if (PRESENTATION.test(grapheme))
|
|
89
|
+
return 2;
|
|
90
|
+
if (grapheme.includes("\u{fe0f}") && EMOJI.test(grapheme))
|
|
91
|
+
return 2;
|
|
92
|
+
if (grapheme.includes("\u{200d}") && PICTOGRAPHIC.test(grapheme))
|
|
93
|
+
return 2;
|
|
94
|
+
return isWide(cp) ? 2 : 1;
|
|
95
|
+
}
|
|
96
|
+
/** The columns a text takes on a terminal: its graphemes' widths summed; escape sequences take none. */
|
|
97
|
+
export function displayWidth(text) {
|
|
98
|
+
let w = 0;
|
|
99
|
+
for (const t of tokens(text))
|
|
100
|
+
if (t.kind === "text")
|
|
101
|
+
for (const g of graphemes(t.text))
|
|
102
|
+
w += graphemeWidth(g);
|
|
103
|
+
return w;
|
|
104
|
+
}
|
|
105
|
+
/**
|
|
106
|
+
* A text split where it reaches `width` columns, between two graphemes or escape sequences, never inside one: a wide character that would
|
|
107
|
+
* cross the edge goes to the tail. Escape sequences up to the first grapheme that does not fit stay in the head.
|
|
108
|
+
*/
|
|
109
|
+
export function splitAtWidth(text, width) {
|
|
110
|
+
let used = 0;
|
|
111
|
+
let at = 0;
|
|
112
|
+
for (const t of tokens(text)) {
|
|
113
|
+
if (t.kind === "escape") {
|
|
114
|
+
at += t.text.length;
|
|
115
|
+
continue;
|
|
116
|
+
}
|
|
117
|
+
for (const g of graphemes(t.text)) {
|
|
118
|
+
const w = graphemeWidth(g);
|
|
119
|
+
if (used + w > width)
|
|
120
|
+
return { head: text.slice(0, at), tail: text.slice(at) };
|
|
121
|
+
used += w;
|
|
122
|
+
at += g.length;
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
return { head: text, tail: "" };
|
|
126
|
+
}
|
|
127
|
+
const SGR = new RegExp(`^${ESC}\\[([0-9;:]*)m$`);
|
|
128
|
+
/** The parameters of an SGR sequence (`ESC [ ... m`), or undefined for another sequence. */
|
|
129
|
+
export function sgrParams(escape) {
|
|
130
|
+
const m = SGR.exec(escape);
|
|
131
|
+
if (m === null)
|
|
132
|
+
return undefined;
|
|
133
|
+
return (m[1] ?? "").split(/[;:]/).map((p) => (p === "" ? 0 : Number(p)));
|
|
134
|
+
}
|
|
135
|
+
/** Whether, after these escape sequences, a style set by SGR is still on: something other than a reset came after the last reset. */
|
|
136
|
+
function styleOpen(escapes) {
|
|
137
|
+
let open = false;
|
|
138
|
+
for (const e of escapes) {
|
|
139
|
+
const params = sgrParams(e) ?? [];
|
|
140
|
+
for (let i = 0; i < params.length; i++) {
|
|
141
|
+
const p = params[i];
|
|
142
|
+
if (p === 0)
|
|
143
|
+
open = false;
|
|
144
|
+
else {
|
|
145
|
+
open = true;
|
|
146
|
+
// 38, 48 and 58 take a colour: 5;n or 2;r;g;b.
|
|
147
|
+
if (p === 38 || p === 48 || p === 58)
|
|
148
|
+
i += params[i + 1] === 5 ? 2 : params[i + 1] === 2 ? 4 : 0;
|
|
149
|
+
}
|
|
150
|
+
}
|
|
151
|
+
}
|
|
152
|
+
return open;
|
|
153
|
+
}
|
|
154
|
+
/** The SGR sequence that turns every style off. */
|
|
155
|
+
export const RESET = `${ESC}[0m`;
|
|
156
|
+
/**
|
|
157
|
+
* 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
|
|
158
|
+
* `ellipsis` (none by default; "…" is the usual one) fit; the escape sequences before the cut are kept, those after are dropped, and where a
|
|
159
|
+
* 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
|
|
160
|
+
* `width` is left out.
|
|
161
|
+
*/
|
|
162
|
+
export function cutToWidth(text, width, ellipsis = "") {
|
|
163
|
+
if (displayWidth(text) <= width)
|
|
164
|
+
return text;
|
|
165
|
+
const room = width - displayWidth(ellipsis);
|
|
166
|
+
const mark = room >= 0 ? ellipsis : "";
|
|
167
|
+
const { head } = splitAtWidth(text, room >= 0 ? room : width);
|
|
168
|
+
const escapes = tokens(head).flatMap((t) => (t.kind === "escape" ? [t.text] : []));
|
|
169
|
+
return head + mark + (styleOpen(escapes) ? RESET : "");
|
|
170
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,65 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@intellectual-frontiers/terminal",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "The terminal as pure code: a typed command-line parser and command trees, the one palette of colour roles and marks, display width and cutting by columns, and a small terminal emulator for snapshot tests; no host, the same code on Bun, Node 26 and in a browser.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"engines": {
|
|
8
|
+
"node": ">=26"
|
|
9
|
+
},
|
|
10
|
+
"sideEffects": false,
|
|
11
|
+
"types": "./dist/mod.d.ts",
|
|
12
|
+
"exports": {
|
|
13
|
+
".": {
|
|
14
|
+
"types": "./dist/mod.d.ts",
|
|
15
|
+
"bun": "./src/mod.ts",
|
|
16
|
+
"default": "./dist/mod.js"
|
|
17
|
+
},
|
|
18
|
+
"./args": {
|
|
19
|
+
"types": "./dist/args.d.ts",
|
|
20
|
+
"bun": "./src/args.ts",
|
|
21
|
+
"default": "./dist/args.js"
|
|
22
|
+
},
|
|
23
|
+
"./commands": {
|
|
24
|
+
"types": "./dist/commands.d.ts",
|
|
25
|
+
"bun": "./src/commands.ts",
|
|
26
|
+
"default": "./dist/commands.js"
|
|
27
|
+
},
|
|
28
|
+
"./palette": {
|
|
29
|
+
"types": "./dist/palette.d.ts",
|
|
30
|
+
"bun": "./src/palette.ts",
|
|
31
|
+
"default": "./dist/palette.js"
|
|
32
|
+
},
|
|
33
|
+
"./vt": {
|
|
34
|
+
"types": "./dist/vt.d.ts",
|
|
35
|
+
"bun": "./src/vt.ts",
|
|
36
|
+
"default": "./dist/vt.js"
|
|
37
|
+
},
|
|
38
|
+
"./width": {
|
|
39
|
+
"types": "./dist/width.d.ts",
|
|
40
|
+
"bun": "./src/width.ts",
|
|
41
|
+
"default": "./dist/width.js"
|
|
42
|
+
}
|
|
43
|
+
},
|
|
44
|
+
"dependencies": {
|
|
45
|
+
"@intellectual-frontiers/core": "0.1.0"
|
|
46
|
+
},
|
|
47
|
+
"files": [
|
|
48
|
+
"dist",
|
|
49
|
+
"src",
|
|
50
|
+
"README.md",
|
|
51
|
+
"LICENSE"
|
|
52
|
+
],
|
|
53
|
+
"repository": {
|
|
54
|
+
"type": "git",
|
|
55
|
+
"url": "git+https://github.com/intellectual-frontiers/.github.git",
|
|
56
|
+
"directory": "commons/terminal"
|
|
57
|
+
},
|
|
58
|
+
"homepage": "https://github.com/intellectual-frontiers/.github/tree/main/commons/terminal",
|
|
59
|
+
"bugs": {
|
|
60
|
+
"url": "https://github.com/intellectual-frontiers/.github/issues"
|
|
61
|
+
},
|
|
62
|
+
"publishConfig": {
|
|
63
|
+
"access": "public"
|
|
64
|
+
}
|
|
65
|
+
}
|