@intellectual-frontiers/terminal 0.0.0-stage → 0.1.1
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
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A command tree declared once as data (commons 0005-typescript-runtime FR-072): a command of groups and verbs to any depth, each with a
|
|
3
|
+
* name and a summary, and each verb with its options (`./args.ts`'s declaration) and its arguments. From that declaration alone it
|
|
4
|
+
* resolves an argument vector to the verb it names, to the help asked for, or to a typed error that names the word not known, where, the
|
|
5
|
+
* words known there and the nearest of them; and it renders the help of every level, so that help never runs a verb.
|
|
6
|
+
*
|
|
7
|
+
* @remarks
|
|
8
|
+
* A group named with no verb asks for its help, as `git remote` with no verb would list; `--help` or `-h` anywhere before `--` asks for
|
|
9
|
+
* the help of the deepest group or verb named before it. Unknown options of a verb are its own parser's business (`parseArgs`), which the
|
|
10
|
+
* verb runs on the arguments left to it.
|
|
11
|
+
*
|
|
12
|
+
* @example
|
|
13
|
+
* ```ts
|
|
14
|
+
* import { group, resolveCommand, verb } from "./commands.js";
|
|
15
|
+
* const tree = group({ name: "tool", summary: "A tool.", children: [group({ name: "work", summary: "Works.", children: [
|
|
16
|
+
* verb({ name: "build", summary: "Build.", options: {} }),
|
|
17
|
+
* ] })] });
|
|
18
|
+
* resolveCommand(tree, ["work", "build", "a"]); // ok: the verb build, with ["a"] left
|
|
19
|
+
* resolveCommand(tree, ["wrk"]); // err: wrk is not known at the top, did you mean work?
|
|
20
|
+
* ```
|
|
21
|
+
*
|
|
22
|
+
* @module
|
|
23
|
+
*/
|
|
24
|
+
import { type Result } from "@intellectual-frontiers/core";
|
|
25
|
+
import { type Operand, type Spec, type SpecCheck } from "./args.js";
|
|
26
|
+
/** An example of a verb: the words after the verb, and what it does. */
|
|
27
|
+
export type Example = {
|
|
28
|
+
readonly args: readonly string[];
|
|
29
|
+
readonly says: string;
|
|
30
|
+
};
|
|
31
|
+
/** A verb: a leaf of the tree, with the options and arguments it takes. */
|
|
32
|
+
export type Verb<S extends Spec = Spec> = {
|
|
33
|
+
readonly kind: "verb";
|
|
34
|
+
readonly name: string;
|
|
35
|
+
readonly summary: string;
|
|
36
|
+
readonly options: S;
|
|
37
|
+
readonly operands: readonly Operand[];
|
|
38
|
+
readonly examples: readonly Example[];
|
|
39
|
+
};
|
|
40
|
+
/** A group: a word that names more words, groups or verbs. */
|
|
41
|
+
export type Group = {
|
|
42
|
+
readonly kind: "group";
|
|
43
|
+
readonly name: string;
|
|
44
|
+
readonly summary: string;
|
|
45
|
+
readonly children: readonly CommandNode[];
|
|
46
|
+
};
|
|
47
|
+
/** One node of a command tree. */
|
|
48
|
+
export type CommandNode = Group | Verb;
|
|
49
|
+
/** A verb, declared with its options checked as `parseArgs` checks them. */
|
|
50
|
+
export declare function verb<S extends Spec>(v: {
|
|
51
|
+
readonly name: string;
|
|
52
|
+
readonly summary: string;
|
|
53
|
+
readonly options: S & SpecCheck<S>;
|
|
54
|
+
readonly operands?: readonly Operand[];
|
|
55
|
+
readonly examples?: readonly Example[];
|
|
56
|
+
}): Verb<S>;
|
|
57
|
+
/** A group of nodes. */
|
|
58
|
+
export declare function group(g: {
|
|
59
|
+
readonly name: string;
|
|
60
|
+
readonly summary: string;
|
|
61
|
+
readonly children: readonly CommandNode[];
|
|
62
|
+
}): Group;
|
|
63
|
+
/** Whether a name is one a command may have: lower case letters, digits and dashes, beginning with a letter. */
|
|
64
|
+
export declare function validCommandName(name: string): boolean;
|
|
65
|
+
/** What is wrong with a declared tree: a name that may not be one, or two children of a group with the same name. */
|
|
66
|
+
export type TreeProblem = {
|
|
67
|
+
readonly kind: "bad-name";
|
|
68
|
+
readonly path: readonly string[];
|
|
69
|
+
readonly name: string;
|
|
70
|
+
} | {
|
|
71
|
+
readonly kind: "duplicate";
|
|
72
|
+
readonly path: readonly string[];
|
|
73
|
+
readonly name: string;
|
|
74
|
+
};
|
|
75
|
+
/** Every problem of a tree, in the order of its nodes; none where it is well formed. */
|
|
76
|
+
export declare function treeProblems(root: CommandNode, path?: readonly string[]): readonly TreeProblem[];
|
|
77
|
+
/** What an argument vector names: a verb with the arguments left for it, or the help of a node. */
|
|
78
|
+
export type Resolved = {
|
|
79
|
+
readonly kind: "verb";
|
|
80
|
+
readonly path: readonly string[];
|
|
81
|
+
readonly verb: Verb;
|
|
82
|
+
readonly args: readonly string[];
|
|
83
|
+
} | {
|
|
84
|
+
readonly kind: "help";
|
|
85
|
+
readonly path: readonly string[];
|
|
86
|
+
readonly node: CommandNode;
|
|
87
|
+
};
|
|
88
|
+
/** Why an argument vector names nothing: a word not known below `path`, the words known there, and the nearest. */
|
|
89
|
+
export type CommandError = {
|
|
90
|
+
readonly kind: "unknown-command";
|
|
91
|
+
readonly path: readonly string[];
|
|
92
|
+
readonly word: string;
|
|
93
|
+
readonly known: readonly string[];
|
|
94
|
+
readonly suggestion: string | undefined;
|
|
95
|
+
};
|
|
96
|
+
/** Whether a word asks for help. */
|
|
97
|
+
export declare function asksForHelp(word: string): boolean;
|
|
98
|
+
/** Resolves an argument vector (the words after the program's name) against a tree whose root is the program. */
|
|
99
|
+
export declare function resolveCommand(root: Group, argv: readonly string[]): Result<Resolved, CommandError>;
|
|
100
|
+
/** A command error as one sentence, with the help to run next. */
|
|
101
|
+
export declare function formatCommandError(e: CommandError): string;
|
|
102
|
+
/** The help of a node at `path` (the words that name it, the program's first), from its declaration alone. */
|
|
103
|
+
export declare function commandHelp(path: readonly string[], node: CommandNode): string;
|
package/dist/commands.js
ADDED
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
// Spec: 0001-terminal FR-002
|
|
2
|
+
/**
|
|
3
|
+
* A command tree declared once as data (commons 0005-typescript-runtime FR-072): a command of groups and verbs to any depth, each with a
|
|
4
|
+
* name and a summary, and each verb with its options (`./args.ts`'s declaration) and its arguments. From that declaration alone it
|
|
5
|
+
* resolves an argument vector to the verb it names, to the help asked for, or to a typed error that names the word not known, where, the
|
|
6
|
+
* words known there and the nearest of them; and it renders the help of every level, so that help never runs a verb.
|
|
7
|
+
*
|
|
8
|
+
* @remarks
|
|
9
|
+
* A group named with no verb asks for its help, as `git remote` with no verb would list; `--help` or `-h` anywhere before `--` asks for
|
|
10
|
+
* the help of the deepest group or verb named before it. Unknown options of a verb are its own parser's business (`parseArgs`), which the
|
|
11
|
+
* verb runs on the arguments left to it.
|
|
12
|
+
*
|
|
13
|
+
* @example
|
|
14
|
+
* ```ts
|
|
15
|
+
* import { group, resolveCommand, verb } from "./commands.ts";
|
|
16
|
+
* const tree = group({ name: "tool", summary: "A tool.", children: [group({ name: "work", summary: "Works.", children: [
|
|
17
|
+
* verb({ name: "build", summary: "Build.", options: {} }),
|
|
18
|
+
* ] })] });
|
|
19
|
+
* resolveCommand(tree, ["work", "build", "a"]); // ok: the verb build, with ["a"] left
|
|
20
|
+
* resolveCommand(tree, ["wrk"]); // err: wrk is not known at the top, did you mean work?
|
|
21
|
+
* ```
|
|
22
|
+
*
|
|
23
|
+
* @module
|
|
24
|
+
*/
|
|
25
|
+
import { absurd, err, ok } from "@intellectual-frontiers/core";
|
|
26
|
+
import { helpOf, suggest } from "./args.js";
|
|
27
|
+
/** A verb, declared with its options checked as `parseArgs` checks them. */
|
|
28
|
+
export function verb(v) {
|
|
29
|
+
return { kind: "verb", name: v.name, summary: v.summary, options: v.options, operands: v.operands ?? [], examples: v.examples ?? [] };
|
|
30
|
+
}
|
|
31
|
+
/** A group of nodes. */
|
|
32
|
+
export function group(g) {
|
|
33
|
+
return { kind: "group", name: g.name, summary: g.summary, children: g.children };
|
|
34
|
+
}
|
|
35
|
+
/** Whether a name is one a command may have: lower case letters, digits and dashes, beginning with a letter. */
|
|
36
|
+
export function validCommandName(name) {
|
|
37
|
+
return /^[a-z][a-z0-9-]*$/.test(name);
|
|
38
|
+
}
|
|
39
|
+
/** Every problem of a tree, in the order of its nodes; none where it is well formed. */
|
|
40
|
+
export function treeProblems(root, path = []) {
|
|
41
|
+
const here = [...path, root.name];
|
|
42
|
+
const own = validCommandName(root.name) ? [] : [{ kind: "bad-name", path, name: root.name }];
|
|
43
|
+
switch (root.kind) {
|
|
44
|
+
case "verb":
|
|
45
|
+
return own;
|
|
46
|
+
case "group": {
|
|
47
|
+
const seen = new Set();
|
|
48
|
+
const dups = [];
|
|
49
|
+
for (const c of root.children) {
|
|
50
|
+
if (seen.has(c.name))
|
|
51
|
+
dups.push({ kind: "duplicate", path: here, name: c.name });
|
|
52
|
+
seen.add(c.name);
|
|
53
|
+
}
|
|
54
|
+
return [...own, ...dups, ...root.children.flatMap((c) => treeProblems(c, here))];
|
|
55
|
+
}
|
|
56
|
+
default:
|
|
57
|
+
return absurd(root);
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
/** Whether a word asks for help. */
|
|
61
|
+
export function asksForHelp(word) {
|
|
62
|
+
return word === "--help" || word === "-h";
|
|
63
|
+
}
|
|
64
|
+
/** Resolves an argument vector (the words after the program's name) against a tree whose root is the program. */
|
|
65
|
+
export function resolveCommand(root, argv) {
|
|
66
|
+
let node = root;
|
|
67
|
+
const path = [root.name];
|
|
68
|
+
let i = 0;
|
|
69
|
+
while (node.kind === "group") {
|
|
70
|
+
const word = argv[i];
|
|
71
|
+
if (word === undefined || asksForHelp(word))
|
|
72
|
+
return ok({ kind: "help", path, node });
|
|
73
|
+
const known = node.children.map((c) => c.name);
|
|
74
|
+
const next = node.children.find((c) => c.name === word);
|
|
75
|
+
if (next === undefined) {
|
|
76
|
+
const candidates = word.startsWith("-") ? ["--help"] : known;
|
|
77
|
+
return err({ kind: "unknown-command", path: [...path], word, known, suggestion: suggest(word, candidates) });
|
|
78
|
+
}
|
|
79
|
+
node = next;
|
|
80
|
+
path.push(next.name);
|
|
81
|
+
i += 1;
|
|
82
|
+
}
|
|
83
|
+
const args = argv.slice(i);
|
|
84
|
+
const end = args.indexOf("--");
|
|
85
|
+
const before = end < 0 ? args : args.slice(0, end);
|
|
86
|
+
if (before.some(asksForHelp))
|
|
87
|
+
return ok({ kind: "help", path, node });
|
|
88
|
+
return ok({ kind: "verb", path, verb: node, args });
|
|
89
|
+
}
|
|
90
|
+
/** A command error as one sentence, with the help to run next. */
|
|
91
|
+
export function formatCommandError(e) {
|
|
92
|
+
const at = e.path.join(" ");
|
|
93
|
+
const what = e.word.startsWith("-") ? "an option" : "a command";
|
|
94
|
+
const near = e.suggestion === undefined ? "" : `; did you mean ${e.suggestion}?`;
|
|
95
|
+
return `${e.word} is not ${what} of ${at}${near} Run ${at} --help to see what it takes.`;
|
|
96
|
+
}
|
|
97
|
+
/** Lines of two columns, the second aligned two spaces after the widest first. */
|
|
98
|
+
function columns(rows) {
|
|
99
|
+
const width = Math.max(0, ...rows.map(([l]) => l.length));
|
|
100
|
+
return rows.map(([l, r]) => ` ${l.padEnd(width)} ${r}`.trimEnd());
|
|
101
|
+
}
|
|
102
|
+
/** The help of a node at `path` (the words that name it, the program's first), from its declaration alone. */
|
|
103
|
+
export function commandHelp(path, node) {
|
|
104
|
+
const at = path.join(" ");
|
|
105
|
+
switch (node.kind) {
|
|
106
|
+
case "group": {
|
|
107
|
+
const rows = node.children.map((c) => [c.name, c.summary]);
|
|
108
|
+
return [
|
|
109
|
+
`${at}: ${node.summary}`,
|
|
110
|
+
"",
|
|
111
|
+
`Usage: ${at} COMMAND [OPTIONS] [ARGUMENTS]`,
|
|
112
|
+
"",
|
|
113
|
+
"Commands:",
|
|
114
|
+
...columns(rows),
|
|
115
|
+
"",
|
|
116
|
+
`Run ${at} COMMAND --help for a command's help.`,
|
|
117
|
+
].join("\n");
|
|
118
|
+
}
|
|
119
|
+
case "verb": {
|
|
120
|
+
const body = helpOf(at, node.summary, node.options, node.operands);
|
|
121
|
+
const examples = node.examples.map((x) => [[at, ...x.args].join(" "), x.says]);
|
|
122
|
+
return examples.length === 0 ? body : [body, "", "Examples:", ...columns(examples)].join("\n");
|
|
123
|
+
}
|
|
124
|
+
default:
|
|
125
|
+
return absurd(node);
|
|
126
|
+
}
|
|
127
|
+
}
|
package/dist/mod.d.ts
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The terminal, as pure code (commons terminal 0001-terminal): a typed command-line parser (`args`) and command trees (`commands`), the one palette of colour roles and marks (`palette`), display width
|
|
3
|
+
* and the cutting of a text by columns (`width`), and a small terminal emulator for snapshot tests (`vt`). Each is a namespace of this entry and an entry of its own (`@intellectual-frontiers/terminal/args`,
|
|
4
|
+
* and so on), so that a program imports what it uses; nothing here touches the host.
|
|
5
|
+
*
|
|
6
|
+
* @example
|
|
7
|
+
* ```ts
|
|
8
|
+
* import { args } from "@intellectual-frontiers/terminal";
|
|
9
|
+
* const options = { verbose: args.flag({ help: "Say more." }) };
|
|
10
|
+
* args.parseArgs(["--verbose"], { options, operands: [] }); // an Args value with options.verbose true
|
|
11
|
+
* ```
|
|
12
|
+
*
|
|
13
|
+
* @module
|
|
14
|
+
*/
|
|
15
|
+
export * as args from "./args.js";
|
|
16
|
+
export * as commands from "./commands.js";
|
|
17
|
+
export * as palette from "./palette.js";
|
|
18
|
+
export * as vt from "./vt.js";
|
|
19
|
+
export * as width from "./width.js";
|
package/dist/mod.js
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
// Spec: 0001-terminal FR-006
|
|
2
|
+
/**
|
|
3
|
+
* The terminal, as pure code (commons terminal 0001-terminal): a typed command-line parser (`args`) and command trees (`commands`), the one palette of colour roles and marks (`palette`), display width
|
|
4
|
+
* and the cutting of a text by columns (`width`), and a small terminal emulator for snapshot tests (`vt`). Each is a namespace of this entry and an entry of its own (`@intellectual-frontiers/terminal/args`,
|
|
5
|
+
* and so on), so that a program imports what it uses; nothing here touches the host.
|
|
6
|
+
*
|
|
7
|
+
* @example
|
|
8
|
+
* ```ts
|
|
9
|
+
* import { args } from "@intellectual-frontiers/terminal";
|
|
10
|
+
* const options = { verbose: args.flag({ help: "Say more." }) };
|
|
11
|
+
* args.parseArgs(["--verbose"], { options, operands: [] }); // an Args value with options.verbose true
|
|
12
|
+
* ```
|
|
13
|
+
*
|
|
14
|
+
* @module
|
|
15
|
+
*/
|
|
16
|
+
export * as args from "./args.js";
|
|
17
|
+
export * as commands from "./commands.js";
|
|
18
|
+
export * as palette from "./palette.js";
|
|
19
|
+
export * as vt from "./vt.js";
|
|
20
|
+
export * as width from "./width.js";
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/** What the terminal written to can show: colour, emoji, and its width in columns (the fields of the runtime's `Look`). */
|
|
2
|
+
export type Capabilities = {
|
|
3
|
+
readonly colour: boolean;
|
|
4
|
+
readonly emoji: boolean;
|
|
5
|
+
readonly columns: number;
|
|
6
|
+
};
|
|
7
|
+
/** What a piece of output means, and so its colour. */
|
|
8
|
+
export type Role = "success" | "failure" | "skipped" | "cancelled" | "hint" | "warning" | "dim" | "accent" | "plain";
|
|
9
|
+
/** Every role, in a fixed order. */
|
|
10
|
+
export declare const ROLES: readonly Role[];
|
|
11
|
+
/** A mark at the start of a line: how something ended, or what a line is. */
|
|
12
|
+
export type MarkKind = "done" | "failed" | "skipped" | "cancelled" | "hint" | "warning" | "pending" | "action";
|
|
13
|
+
/** Every mark, in a fixed order. */
|
|
14
|
+
export declare const MARK_KINDS: readonly MarkKind[];
|
|
15
|
+
/** A mark as an emoji, its ASCII fallback, and the role it is painted in. */
|
|
16
|
+
export type MarkStyle = {
|
|
17
|
+
readonly emoji: string;
|
|
18
|
+
readonly ascii: string;
|
|
19
|
+
readonly role: Role;
|
|
20
|
+
};
|
|
21
|
+
/**
|
|
22
|
+
* The marks: ✅ ❌ ⏭️ ⏹️ 👉 ⚠️ ⏳ ⚡, and `[ok]` `[x]` `[skip]` `[stop]` `->` `[!]` `[todo]` `[you]` where there are no emoji. ❌ and ⚠️ are
|
|
23
|
+
* problems; ⏳ (pending) is something not set up yet, expected until someone does it; ⚡ (action) is a step that is the person's to take
|
|
24
|
+
* (send a change, back up, approve): nothing is wrong, so it is neither a warning nor an error (FR-027).
|
|
25
|
+
*/
|
|
26
|
+
export declare const MARKS: Readonly<Record<MarkKind, MarkStyle>>;
|
|
27
|
+
/** A mark: its emoji where the terminal shows emoji, else its ASCII fallback. */
|
|
28
|
+
export declare function mark(kind: MarkKind, caps: {
|
|
29
|
+
readonly emoji: boolean;
|
|
30
|
+
}): string;
|
|
31
|
+
/** The SGR parameters of a role; empty for `plain`. */
|
|
32
|
+
export declare function sgrOf(role: Role): string;
|
|
33
|
+
/**
|
|
34
|
+
* A text in a role's colour, followed by a reset, where colour is allowed; the text as it is where it is not, for the role `plain`, and for
|
|
35
|
+
* an empty text. Painted texts are put side by side, not inside one another: the inner reset would end the outer colour.
|
|
36
|
+
*/
|
|
37
|
+
export declare function paint(role: Role, text: string, caps: {
|
|
38
|
+
readonly colour: boolean;
|
|
39
|
+
}): string;
|
|
40
|
+
/** A line's beginning: the mark painted in its role, a space, and the text. */
|
|
41
|
+
export declare function label(kind: MarkKind, text: string, caps: {
|
|
42
|
+
readonly colour: boolean;
|
|
43
|
+
readonly emoji: boolean;
|
|
44
|
+
}): string;
|
package/dist/palette.js
ADDED
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
// Spec: 0001-terminal FR-003
|
|
2
|
+
/**
|
|
3
|
+
* The console's one palette (commons 0006-signals FR-022): the colour roles as a union type, and the marks a person reads at a glance,
|
|
4
|
+
* each with an ASCII fallback for a terminal with no emoji. Whether colour and emoji may be used is the terminal's (commons
|
|
5
|
+
* 0005-typescript-runtime FR-023, `runtime/tty.ts`'s `lookOf`); this module only obeys it: `paint` writes SGR sequences only where colour is
|
|
6
|
+
* allowed, and `mark` an emoji only where emoji are.
|
|
7
|
+
*
|
|
8
|
+
* `Capabilities` has the fields of the runtime's `Look` that output depends on (`colour`, `emoji`, `columns`, the same names), so a `Look`
|
|
9
|
+
* is a `Capabilities` as it is.
|
|
10
|
+
*
|
|
11
|
+
* @example
|
|
12
|
+
* ```ts
|
|
13
|
+
* import { label, mark, paint } from "./palette.ts";
|
|
14
|
+
* mark("done", { emoji: true }); // "✅"
|
|
15
|
+
* mark("done", { emoji: false }); // "[ok]"
|
|
16
|
+
* paint("failure", "3 failed", { colour: true }); // "\u001b[31m3 failed\u001b[0m"
|
|
17
|
+
* label("warning", "slow", { colour: false, emoji: false }); // "[!] slow"
|
|
18
|
+
* ```
|
|
19
|
+
*
|
|
20
|
+
* @module
|
|
21
|
+
*/
|
|
22
|
+
import { absurd } from "@intellectual-frontiers/core";
|
|
23
|
+
/** Every role, in a fixed order. */
|
|
24
|
+
export const ROLES = ["success", "failure", "skipped", "cancelled", "hint", "warning", "dim", "accent", "plain"];
|
|
25
|
+
/** Every mark, in a fixed order. */
|
|
26
|
+
export const MARK_KINDS = ["done", "failed", "skipped", "cancelled", "hint", "warning", "pending", "action"];
|
|
27
|
+
/**
|
|
28
|
+
* The marks: ✅ ❌ ⏭️ ⏹️ 👉 ⚠️ ⏳ ⚡, and `[ok]` `[x]` `[skip]` `[stop]` `->` `[!]` `[todo]` `[you]` where there are no emoji. ❌ and ⚠️ are
|
|
29
|
+
* problems; ⏳ (pending) is something not set up yet, expected until someone does it; ⚡ (action) is a step that is the person's to take
|
|
30
|
+
* (send a change, back up, approve): nothing is wrong, so it is neither a warning nor an error (FR-027).
|
|
31
|
+
*/
|
|
32
|
+
export const MARKS = {
|
|
33
|
+
done: { emoji: "✅", ascii: "[ok]", role: "success" },
|
|
34
|
+
failed: { emoji: "❌", ascii: "[x]", role: "failure" },
|
|
35
|
+
skipped: { emoji: "\u{23ed}\u{fe0f}", ascii: "[skip]", role: "skipped" },
|
|
36
|
+
cancelled: { emoji: "\u{23f9}\u{fe0f}", ascii: "[stop]", role: "cancelled" },
|
|
37
|
+
hint: { emoji: "👉", ascii: "->", role: "hint" },
|
|
38
|
+
warning: { emoji: "\u{26a0}\u{fe0f}", ascii: "[!]", role: "warning" },
|
|
39
|
+
pending: { emoji: "\u{23f3}", ascii: "[todo]", role: "dim" },
|
|
40
|
+
action: { emoji: "\u{26a1}", ascii: "[you]", role: "accent" },
|
|
41
|
+
};
|
|
42
|
+
/** A mark: its emoji where the terminal shows emoji, else its ASCII fallback. */
|
|
43
|
+
export function mark(kind, caps) {
|
|
44
|
+
const m = MARKS[kind];
|
|
45
|
+
return caps.emoji ? m.emoji : m.ascii;
|
|
46
|
+
}
|
|
47
|
+
/** The SGR parameters of a role; empty for `plain`. */
|
|
48
|
+
export function sgrOf(role) {
|
|
49
|
+
switch (role) {
|
|
50
|
+
case "success":
|
|
51
|
+
return "32";
|
|
52
|
+
case "failure":
|
|
53
|
+
return "31";
|
|
54
|
+
case "skipped":
|
|
55
|
+
return "33";
|
|
56
|
+
case "cancelled":
|
|
57
|
+
return "35";
|
|
58
|
+
case "hint":
|
|
59
|
+
return "36";
|
|
60
|
+
case "warning":
|
|
61
|
+
return "33;1";
|
|
62
|
+
case "dim":
|
|
63
|
+
return "2";
|
|
64
|
+
case "accent":
|
|
65
|
+
return "1";
|
|
66
|
+
case "plain":
|
|
67
|
+
return "";
|
|
68
|
+
default:
|
|
69
|
+
return absurd(role);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
const ESC = String.fromCharCode(0x1b);
|
|
73
|
+
/**
|
|
74
|
+
* A text in a role's colour, followed by a reset, where colour is allowed; the text as it is where it is not, for the role `plain`, and for
|
|
75
|
+
* an empty text. Painted texts are put side by side, not inside one another: the inner reset would end the outer colour.
|
|
76
|
+
*/
|
|
77
|
+
export function paint(role, text, caps) {
|
|
78
|
+
const sgr = sgrOf(role);
|
|
79
|
+
return caps.colour && sgr !== "" && text !== "" ? `${ESC}[${sgr}m${text}${ESC}[0m` : text;
|
|
80
|
+
}
|
|
81
|
+
/** A line's beginning: the mark painted in its role, a space, and the text. */
|
|
82
|
+
export function label(kind, text, caps) {
|
|
83
|
+
return `${paint(MARKS[kind].role, mark(kind, caps), caps)} ${text}`;
|
|
84
|
+
}
|
package/dist/vt.d.ts
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
/** 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. */
|
|
2
|
+
export type Colour = {
|
|
3
|
+
readonly kind: "default";
|
|
4
|
+
} | {
|
|
5
|
+
readonly kind: "indexed";
|
|
6
|
+
readonly index: number;
|
|
7
|
+
} | {
|
|
8
|
+
readonly kind: "rgb";
|
|
9
|
+
readonly r: number;
|
|
10
|
+
readonly g: number;
|
|
11
|
+
readonly b: number;
|
|
12
|
+
};
|
|
13
|
+
/** How a cell's text is drawn, as SGR left it. */
|
|
14
|
+
export type Style = {
|
|
15
|
+
readonly bold: boolean;
|
|
16
|
+
readonly dim: boolean;
|
|
17
|
+
readonly italic: boolean;
|
|
18
|
+
readonly underline: boolean;
|
|
19
|
+
readonly blink: boolean;
|
|
20
|
+
readonly inverse: boolean;
|
|
21
|
+
readonly hidden: boolean;
|
|
22
|
+
readonly strike: boolean;
|
|
23
|
+
readonly fg: Colour;
|
|
24
|
+
readonly bg: Colour;
|
|
25
|
+
};
|
|
26
|
+
/** The style of a cell nothing styled: every attribute off, default colours. */
|
|
27
|
+
export declare const PLAIN: Style;
|
|
28
|
+
/** A style in words, for a snapshot: the attributes on, then `fg=` and `bg=` where not the default; "" for `PLAIN`. */
|
|
29
|
+
export declare function describeStyle(style: Style): string;
|
|
30
|
+
/** Whether two styles draw the same. */
|
|
31
|
+
export declare function sameStyle(a: Style, b: Style): boolean;
|
|
32
|
+
/** 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. */
|
|
33
|
+
export type Cell = {
|
|
34
|
+
readonly text: string;
|
|
35
|
+
readonly width: 0 | 1 | 2;
|
|
36
|
+
readonly style: Style;
|
|
37
|
+
};
|
|
38
|
+
/** A run of cells of one style on a line, their text joined. */
|
|
39
|
+
export type Run = {
|
|
40
|
+
readonly text: string;
|
|
41
|
+
readonly style: Style;
|
|
42
|
+
};
|
|
43
|
+
/** Where the cursor is (row and column from 0) and whether it is shown. */
|
|
44
|
+
export type Cursor = {
|
|
45
|
+
readonly row: number;
|
|
46
|
+
readonly col: number;
|
|
47
|
+
readonly visible: boolean;
|
|
48
|
+
};
|
|
49
|
+
/** The size of a screen and how it reads a line feed. */
|
|
50
|
+
export type ScreenOptions = {
|
|
51
|
+
/** Columns; at least 1. */
|
|
52
|
+
readonly width: number;
|
|
53
|
+
/** Rows: the screen scrolls when a line feed is written on the last; without it, the screen grows. */
|
|
54
|
+
readonly height?: number;
|
|
55
|
+
/** "crlf" (the default): a line feed also returns the carriage, as a terminal's line discipline does; "lf": it only moves down. */
|
|
56
|
+
readonly newline?: "crlf" | "lf";
|
|
57
|
+
};
|
|
58
|
+
/** A screen being written to. */
|
|
59
|
+
export type Screen = {
|
|
60
|
+
/** Its width in columns. */
|
|
61
|
+
readonly width: number;
|
|
62
|
+
/** Its height in rows, or undefined where it grows. */
|
|
63
|
+
readonly height: number | undefined;
|
|
64
|
+
/** Feeds it what a program writes: text, or bytes decoded as UTF-8 (a character may be split across writes). */
|
|
65
|
+
write(data: string | Uint8Array): void;
|
|
66
|
+
/** Its lines as text: trailing spaces of each line and trailing empty lines left out. */
|
|
67
|
+
lines(): readonly string[];
|
|
68
|
+
/** Its lines joined by "\n". */
|
|
69
|
+
text(): string;
|
|
70
|
+
/** Its lines as runs of one style, trailing unstyled spaces and trailing empty lines left out. */
|
|
71
|
+
styled(): readonly (readonly Run[])[];
|
|
72
|
+
/** The cell at a row and column; undefined outside the screen. */
|
|
73
|
+
cell(row: number, col: number): Cell | undefined;
|
|
74
|
+
/** The cursor. */
|
|
75
|
+
cursor(): Cursor;
|
|
76
|
+
};
|
|
77
|
+
/** A new, empty screen with the cursor at the top left, shown. */
|
|
78
|
+
export declare function createScreen(options: ScreenOptions): Screen;
|