@amritk/nish-aarch64-darwin 0.35.0 → 0.36.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/INSTALL.md +6 -1
- package/bin/nish +0 -0
- package/docs/AI.md +9 -2
- package/package.json +1 -1
- package/runtime/nish.d.ts +4612 -430
- package/runtime/vite.d.ts +30 -0
- package/runtime/vite.mjs +150 -0
- package/scripts/build.sh +108 -13
- package/std/base64.ts +34 -5
- package/std/bytes.ts +256 -40
- package/std/cli-args.ts +296 -70
- package/std/cli-flags.ts +184 -19
- package/std/cli.ts +475 -54
- package/std/collections.ts +121 -23
- package/std/compress/checksum.ts +44 -14
- package/std/compress/deflate.ts +224 -111
- package/std/compress/gzip.ts +217 -53
- package/std/compress/zlib.ts +63 -7
- package/std/crypto/aes.ts +80 -9
- package/std/crypto/base64url.ts +22 -0
- package/std/crypto/bcrypt-batch.ts +88 -21
- package/std/crypto/bcrypt.ts +60 -0
- package/std/crypto/chacha20poly1305.ts +53 -0
- package/std/crypto/ct.ts +32 -13
- package/std/crypto/ed25519.ts +47 -0
- package/std/crypto/hkdf.ts +198 -13
- package/std/crypto/hmac.ts +235 -31
- package/std/crypto/jwt.ts +192 -63
- package/std/crypto/p256.ts +159 -16
- package/std/crypto/p384.ts +28 -3
- package/std/crypto/pki-roots.ts +32 -2
- package/std/crypto/pki.ts +81 -15
- package/std/crypto/rsa.ts +33 -3
- package/std/crypto/sha1.ts +3 -0
- package/std/crypto/sha256.ts +24 -1
- package/std/crypto/sha512.ts +99 -14
- package/std/crypto/x25519.ts +152 -14
- package/std/crypto/x509-random.ts +10 -0
- package/std/crypto/x509.ts +67 -7
- package/std/json-equal.ts +19 -0
- package/std/json-format.ts +112 -13
- package/std/json-number.ts +64 -14
- package/std/json-pointer.ts +23 -1
- package/std/json-tokenizer.ts +100 -29
- package/std/json-typed.ts +713 -66
- package/std/json-value.ts +400 -124
- package/std/json.ts +138 -10
- package/std/map.ts +25 -7
- package/std/math.ts +36 -4
- package/std/net/buffer-pool.ts +42 -11
- package/std/net/dns-config.ts +109 -23
- package/std/net/dns-message.ts +62 -7
- package/std/net/dns-resolver.ts +247 -53
- package/std/net/dns.ts +203 -35
- package/std/net/fetch.ts +151 -61
- package/std/net/handler.ts +278 -80
- package/std/net/hpack.ts +262 -52
- package/std/net/http-compress.ts +125 -15
- package/std/net/http-fields.ts +85 -9
- package/std/net/http1-client-codec.ts +100 -19
- package/std/net/http1-codec.ts +235 -27
- package/std/net/http1-server.ts +343 -85
- package/std/net/http2-frame.ts +272 -35
- package/std/net/http2-tls.ts +135 -34
- package/std/net/http2.ts +247 -106
- package/std/net/http3-frame.ts +154 -17
- package/std/net/http3-server.ts +246 -96
- package/std/net/http3.ts +307 -115
- package/std/net/outbound.ts +37 -3
- package/std/net/postgres-carrier.ts +144 -8
- package/std/net/postgres.ts +723 -103
- package/std/net/prefork.ts +164 -31
- package/std/net/qpack.ts +105 -18
- package/std/net/quic-conn-ack.ts +59 -12
- package/std/net/quic-conn-cid.ts +124 -27
- package/std/net/quic-conn-params.ts +70 -10
- package/std/net/quic-datagram.ts +43 -3
- package/std/net/quic-frame.ts +286 -12
- package/std/net/quic-listener.ts +101 -32
- package/std/net/quic-packet.ts +302 -21
- package/std/net/quic-recovery.ts +228 -44
- package/std/net/quic-stream.ts +353 -91
- package/std/net/quic.ts +489 -171
- package/std/net/router.ts +87 -40
- package/std/net/tls/client.ts +166 -51
- package/std/net/tls/codec.ts +413 -56
- package/std/net/tls/record-client.ts +110 -55
- package/std/net/tls/record-server.ts +159 -59
- package/std/net/tls/record.ts +109 -12
- package/std/net/tls/schedule.ts +235 -26
- package/std/net/tls/ticket.ts +159 -40
- package/std/net/tls/verify.ts +49 -3
- package/std/net/tls-tcp.ts +250 -45
- package/std/net/tls.ts +221 -59
- package/std/net/upstream.ts +81 -45
- package/std/net/url.ts +97 -13
- package/std/net/websocket.ts +122 -12
- package/std/net/webtransport.ts +220 -89
- package/std/pair.ts +10 -2
- package/std/random.ts +34 -9
- package/std/regex.ts +352 -198
- package/std/region.ts +70 -15
- package/std/secret.ts +52 -11
- package/std/sort.ts +17 -2
- package/std/sqlite.ts +256 -35
- package/std/sync/ring.ts +205 -35
- package/std/sync/shm.ts +194 -16
- package/std/term-io.ts +137 -64
- package/std/term-pixels.ts +144 -19
- package/std/term-probe.ts +66 -25
- package/std/term-rate.ts +128 -57
- package/std/term.ts +332 -121
- package/std/testing.ts +130 -32
- package/std/text.ts +73 -7
- package/std/threads.ts +229 -41
- package/std/yaml-json.ts +94 -82
- package/std/yaml-lines.ts +47 -15
- package/std/yaml-write.ts +24 -16
- package/std/yaml.ts +764 -384
package/std/cli.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* `
|
|
2
|
+
* `nish/cli` — a command-line tool's help menu: whether a stream gets colour,
|
|
3
3
|
* the escapes that paint it, and the rows a `--help` is made of.
|
|
4
4
|
*
|
|
5
5
|
* import { HelpMenu, agentDriven, styleFor } from "nish/cli";
|
|
@@ -64,43 +64,81 @@ const PALETTE_MONO: i32 = 2
|
|
|
64
64
|
* spelling the numbers. The first sixteen are the colours a theme redefines:
|
|
65
65
|
* the eight basic ones and their bright twins.
|
|
66
66
|
*/
|
|
67
|
+
/** The SGR parameter for the theme's black as the text colour. */
|
|
67
68
|
export const SGR_BLACK: string = "30"
|
|
69
|
+
/** The SGR parameter for the theme's red as the text colour. */
|
|
68
70
|
export const SGR_RED: string = "31"
|
|
71
|
+
/** The SGR parameter for the theme's green as the text colour. */
|
|
69
72
|
export const SGR_GREEN: string = "32"
|
|
73
|
+
/** The SGR parameter for the theme's yellow as the text colour. */
|
|
70
74
|
export const SGR_YELLOW: string = "33"
|
|
75
|
+
/** The SGR parameter for the theme's blue as the text colour. */
|
|
71
76
|
export const SGR_BLUE: string = "34"
|
|
77
|
+
/** The SGR parameter for the theme's magenta as the text colour. */
|
|
72
78
|
export const SGR_MAGENTA: string = "35"
|
|
79
|
+
/** The SGR parameter for the theme's cyan as the text colour. */
|
|
73
80
|
export const SGR_CYAN: string = "36"
|
|
81
|
+
/** The SGR parameter for the theme's white as the text colour. */
|
|
74
82
|
export const SGR_WHITE: string = "37"
|
|
83
|
+
/** The SGR parameter for the theme's bright black (gray) as the text colour. */
|
|
75
84
|
export const SGR_BRIGHT_BLACK: string = "90"
|
|
85
|
+
/** The SGR parameter for the theme's bright red as the text colour. */
|
|
76
86
|
export const SGR_BRIGHT_RED: string = "91"
|
|
87
|
+
/** The SGR parameter for the theme's bright green as the text colour. */
|
|
77
88
|
export const SGR_BRIGHT_GREEN: string = "92"
|
|
89
|
+
/** The SGR parameter for the theme's bright yellow as the text colour. */
|
|
78
90
|
export const SGR_BRIGHT_YELLOW: string = "93"
|
|
91
|
+
/** The SGR parameter for the theme's bright blue as the text colour. */
|
|
79
92
|
export const SGR_BRIGHT_BLUE: string = "94"
|
|
93
|
+
/** The SGR parameter for the theme's bright magenta as the text colour. */
|
|
80
94
|
export const SGR_BRIGHT_MAGENTA: string = "95"
|
|
95
|
+
/** The SGR parameter for the theme's bright cyan as the text colour. */
|
|
81
96
|
export const SGR_BRIGHT_CYAN: string = "96"
|
|
97
|
+
/** The SGR parameter for the theme's bright white as the text colour. */
|
|
82
98
|
export const SGR_BRIGHT_WHITE: string = "97"
|
|
99
|
+
/** The SGR parameter for the theme's black as the background. */
|
|
83
100
|
export const SGR_BG_BLACK: string = "40"
|
|
101
|
+
/** The SGR parameter for the theme's red as the background. */
|
|
84
102
|
export const SGR_BG_RED: string = "41"
|
|
103
|
+
/** The SGR parameter for the theme's green as the background. */
|
|
85
104
|
export const SGR_BG_GREEN: string = "42"
|
|
105
|
+
/** The SGR parameter for the theme's yellow as the background. */
|
|
86
106
|
export const SGR_BG_YELLOW: string = "43"
|
|
107
|
+
/** The SGR parameter for the theme's blue as the background. */
|
|
87
108
|
export const SGR_BG_BLUE: string = "44"
|
|
109
|
+
/** The SGR parameter for the theme's magenta as the background. */
|
|
88
110
|
export const SGR_BG_MAGENTA: string = "45"
|
|
111
|
+
/** The SGR parameter for the theme's cyan as the background. */
|
|
89
112
|
export const SGR_BG_CYAN: string = "46"
|
|
113
|
+
/** The SGR parameter for the theme's white as the background. */
|
|
90
114
|
export const SGR_BG_WHITE: string = "47"
|
|
115
|
+
/** The SGR parameter for the theme's bright black as the background. */
|
|
91
116
|
export const SGR_BG_BRIGHT_BLACK: string = "100"
|
|
117
|
+
/** The SGR parameter for the theme's bright red as the background. */
|
|
92
118
|
export const SGR_BG_BRIGHT_RED: string = "101"
|
|
119
|
+
/** The SGR parameter for the theme's bright green as the background. */
|
|
93
120
|
export const SGR_BG_BRIGHT_GREEN: string = "102"
|
|
121
|
+
/** The SGR parameter for the theme's bright yellow as the background. */
|
|
94
122
|
export const SGR_BG_BRIGHT_YELLOW: string = "103"
|
|
123
|
+
/** The SGR parameter for the theme's bright blue as the background. */
|
|
95
124
|
export const SGR_BG_BRIGHT_BLUE: string = "104"
|
|
125
|
+
/** The SGR parameter for the theme's bright magenta as the background. */
|
|
96
126
|
export const SGR_BG_BRIGHT_MAGENTA: string = "105"
|
|
127
|
+
/** The SGR parameter for the theme's bright cyan as the background. */
|
|
97
128
|
export const SGR_BG_BRIGHT_CYAN: string = "106"
|
|
129
|
+
/** The SGR parameter for the theme's bright white as the background. */
|
|
98
130
|
export const SGR_BG_BRIGHT_WHITE: string = "107"
|
|
131
|
+
/** The SGR parameter for bold, or increased intensity. */
|
|
99
132
|
export const SGR_BOLD: string = "1"
|
|
133
|
+
/** The SGR parameter for faint, or decreased intensity. */
|
|
100
134
|
export const SGR_FAINT: string = "2"
|
|
135
|
+
/** The SGR parameter for italic, which some terminals do not show. */
|
|
101
136
|
export const SGR_ITALIC: string = "3"
|
|
137
|
+
/** The SGR parameter for underline. */
|
|
102
138
|
export const SGR_UNDERLINE: string = "4"
|
|
139
|
+
/** The SGR parameter for inverse: foreground and background swapped. */
|
|
103
140
|
export const SGR_INVERSE: string = "7"
|
|
141
|
+
/** The SGR parameter for struck through. */
|
|
104
142
|
export const SGR_STRIKETHROUGH: string = "9"
|
|
105
143
|
|
|
106
144
|
/**
|
|
@@ -115,19 +153,70 @@ export const SGR_STRIKETHROUGH: string = "9"
|
|
|
115
153
|
* plain.
|
|
116
154
|
*/
|
|
117
155
|
export class Style {
|
|
118
|
-
on: boolean
|
|
119
|
-
colour: boolean
|
|
156
|
+
private on: boolean
|
|
157
|
+
private colour: boolean
|
|
158
|
+
/**
|
|
159
|
+
* The SGR list `heading` paints a section heading with when the terminal
|
|
160
|
+
* has colours: bold magenta (`"1;35"`) unless the program sets another.
|
|
161
|
+
*/
|
|
120
162
|
headingThemed: string
|
|
163
|
+
/**
|
|
164
|
+
* The SGR list `heading` paints a section heading with on the failsafe,
|
|
165
|
+
* where the terminal has no colours: bold (`SGR_BOLD`) unless set.
|
|
166
|
+
*/
|
|
121
167
|
headingMono: string
|
|
168
|
+
/**
|
|
169
|
+
* The SGR list `name` paints the tool's own name with when the terminal has
|
|
170
|
+
* colours: bold magenta (`"1;35"`) unless the program sets another.
|
|
171
|
+
*/
|
|
122
172
|
nameThemed: string
|
|
173
|
+
/**
|
|
174
|
+
* The SGR list `name` paints the tool's own name with on the failsafe,
|
|
175
|
+
* where the terminal has no colours: bold (`SGR_BOLD`) unless set.
|
|
176
|
+
*/
|
|
123
177
|
nameMono: string
|
|
178
|
+
/**
|
|
179
|
+
* The SGR list `flag` paints a flag or command with when the terminal has
|
|
180
|
+
* colours: cyan (`SGR_CYAN`) unless the program sets another.
|
|
181
|
+
*/
|
|
124
182
|
flagThemed: string
|
|
183
|
+
/**
|
|
184
|
+
* The SGR list `flag` paints a flag or command with on the failsafe, where
|
|
185
|
+
* the terminal has no colours: bold (`SGR_BOLD`) unless set.
|
|
186
|
+
*/
|
|
125
187
|
flagMono: string
|
|
188
|
+
/**
|
|
189
|
+
* The SGR list `meta` paints a placeholder with when the terminal has
|
|
190
|
+
* colours: yellow (`SGR_YELLOW`) unless the program sets another.
|
|
191
|
+
*/
|
|
126
192
|
metaThemed: string
|
|
193
|
+
/**
|
|
194
|
+
* The SGR list `meta` paints a placeholder with on the failsafe, where the
|
|
195
|
+
* terminal has no colours: underline (`SGR_UNDERLINE`) unless set.
|
|
196
|
+
*/
|
|
127
197
|
metaMono: string
|
|
198
|
+
/**
|
|
199
|
+
* The SGR list `dim` paints descriptions and notes with when the terminal
|
|
200
|
+
* has colours: faint (`SGR_FAINT`) unless the program sets another.
|
|
201
|
+
*/
|
|
128
202
|
dimThemed: string
|
|
203
|
+
/**
|
|
204
|
+
* The SGR list `dim` paints descriptions and notes with on the failsafe,
|
|
205
|
+
* where the terminal has no colours: empty, so plain, unless set.
|
|
206
|
+
*/
|
|
129
207
|
dimMono: string
|
|
130
208
|
|
|
209
|
+
/**
|
|
210
|
+
* A style with every role at its default pair. `styleFor` builds the right
|
|
211
|
+
* one for a stream; a program calls this to decide for itself.
|
|
212
|
+
*
|
|
213
|
+
* @param on whether to mark the text up at all; `false` makes every painter
|
|
214
|
+
* give its text back unchanged, whatever `colour` says.
|
|
215
|
+
* @param colour whether the terminal has colours: `true` paints the roles'
|
|
216
|
+
* `…Themed` lists and lets the colour painters and `sgr` paint; `false`
|
|
217
|
+
* is the failsafe, which paints the `…Mono` lists and the attributes and
|
|
218
|
+
* leaves the colour painters and `sgr` plain.
|
|
219
|
+
*/
|
|
131
220
|
constructor(on: boolean, colour: boolean) {
|
|
132
221
|
this.on = on
|
|
133
222
|
this.colour = colour
|
|
@@ -152,7 +241,7 @@ export class Style {
|
|
|
152
241
|
* `text` unchanged when marking up is off or the chosen list is empty, so a
|
|
153
242
|
* caller never has to ask.
|
|
154
243
|
*/
|
|
155
|
-
paint(text: string, themed: string, mono: string): string {
|
|
244
|
+
private paint(text: string, themed: string, mono: string): string {
|
|
156
245
|
const code = this.colour ? themed : mono
|
|
157
246
|
if (!this.on || text.length === 0 || code.length === 0) {
|
|
158
247
|
return text
|
|
@@ -160,7 +249,14 @@ export class Style {
|
|
|
160
249
|
return `${CSI}${code}m${text}${CSI}0m`
|
|
161
250
|
}
|
|
162
251
|
|
|
163
|
-
/**
|
|
252
|
+
/**
|
|
253
|
+
* A section heading, in `headingThemed` or `headingMono`.
|
|
254
|
+
*
|
|
255
|
+
* @param text the words to paint, as they appear in the menu.
|
|
256
|
+
* @returns `text` wrapped in the heading role's escape and a reset, or `text`
|
|
257
|
+
* unchanged when marking up is off, `text` is empty, or the list this
|
|
258
|
+
* style uses for the role is empty.
|
|
259
|
+
*/
|
|
164
260
|
heading(text: string): string {
|
|
165
261
|
return this.paint(text, this.headingThemed, this.headingMono)
|
|
166
262
|
}
|
|
@@ -168,6 +264,11 @@ export class Style {
|
|
|
168
264
|
/**
|
|
169
265
|
* The tool's own name where it opens a line, in `nameThemed` or
|
|
170
266
|
* `nameMono`.
|
|
267
|
+
*
|
|
268
|
+
* @param text the words to paint, as they appear in the menu.
|
|
269
|
+
* @returns `text` wrapped in the name role's escape and a reset, or `text`
|
|
270
|
+
* unchanged when marking up is off, `text` is empty, or the list this
|
|
271
|
+
* style uses for the role is empty.
|
|
171
272
|
*/
|
|
172
273
|
name(text: string): string {
|
|
173
274
|
return this.paint(text, this.nameThemed, this.nameMono)
|
|
@@ -176,6 +277,11 @@ export class Style {
|
|
|
176
277
|
/**
|
|
177
278
|
* A flag, or a command a person would type, in `flagThemed` or
|
|
178
279
|
* `flagMono`.
|
|
280
|
+
*
|
|
281
|
+
* @param text the words to paint, as they appear in the menu.
|
|
282
|
+
* @returns `text` wrapped in the flag role's escape and a reset, or `text`
|
|
283
|
+
* unchanged when marking up is off, `text` is empty, or the list this
|
|
284
|
+
* style uses for the role is empty.
|
|
179
285
|
*/
|
|
180
286
|
flag(text: string): string {
|
|
181
287
|
return this.paint(text, this.flagThemed, this.flagMono)
|
|
@@ -184,6 +290,11 @@ export class Style {
|
|
|
184
290
|
/**
|
|
185
291
|
* A placeholder the person fills in, such as `<file.ts>` or `speed|size`, in
|
|
186
292
|
* `metaThemed` or `metaMono`.
|
|
293
|
+
*
|
|
294
|
+
* @param text the words to paint, as they appear in the menu.
|
|
295
|
+
* @returns `text` wrapped in the meta role's escape and a reset, or `text`
|
|
296
|
+
* unchanged when marking up is off, `text` is empty, or the list this
|
|
297
|
+
* style uses for the role is empty.
|
|
187
298
|
*/
|
|
188
299
|
meta(text: string): string {
|
|
189
300
|
return this.paint(text, this.metaThemed, this.metaMono)
|
|
@@ -192,6 +303,11 @@ export class Style {
|
|
|
192
303
|
/**
|
|
193
304
|
* Text that explains rather than names, such as descriptions and notes, in
|
|
194
305
|
* `dimThemed` or `dimMono`.
|
|
306
|
+
*
|
|
307
|
+
* @param text the words to paint, as they appear in the menu.
|
|
308
|
+
* @returns `text` wrapped in the dim role's escape and a reset, or `text`
|
|
309
|
+
* unchanged when marking up is off, `text` is empty, or the list this
|
|
310
|
+
* style uses for the role is empty.
|
|
195
311
|
*/
|
|
196
312
|
dim(text: string): string {
|
|
197
313
|
return this.paint(text, this.dimThemed, this.dimMono)
|
|
@@ -203,6 +319,13 @@ export class Style {
|
|
|
203
319
|
* 256-colour and truecolor, which ignore the reader's theme, so they stay
|
|
204
320
|
* the caller's explicit choice. The failsafe paints nothing, since the list
|
|
205
321
|
* may name a colour a monochrome terminal cannot show.
|
|
322
|
+
*
|
|
323
|
+
* @param text the words to paint.
|
|
324
|
+
* @param codes the SGR parameters, separated by `;`, without the CSI before
|
|
325
|
+
* them or the `m` after; an empty list leaves `text` plain.
|
|
326
|
+
* @returns `text` wrapped in the escape for `codes` and a reset, or `text`
|
|
327
|
+
* unchanged when colour is off (the failsafe included), `text` is empty,
|
|
328
|
+
* or `codes` is.
|
|
206
329
|
*/
|
|
207
330
|
sgr(text: string, codes: string): string {
|
|
208
331
|
return this.paint(text, codes, "")
|
|
@@ -212,192 +335,422 @@ export class Style {
|
|
|
212
335
|
// colours to show, paints none of them; the attribute painters paint under
|
|
213
336
|
// both.
|
|
214
337
|
|
|
215
|
-
/**
|
|
338
|
+
/**
|
|
339
|
+
* `text` in the theme's black (`SGR_BLACK`).
|
|
340
|
+
*
|
|
341
|
+
* @param text the words to colour.
|
|
342
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
343
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
344
|
+
*/
|
|
216
345
|
black(text: string): string {
|
|
217
346
|
return this.sgr(text, SGR_BLACK)
|
|
218
347
|
}
|
|
219
348
|
|
|
220
|
-
/**
|
|
349
|
+
/**
|
|
350
|
+
* `text` in the theme's red (`SGR_RED`).
|
|
351
|
+
*
|
|
352
|
+
* @param text the words to colour.
|
|
353
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
354
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
355
|
+
*/
|
|
221
356
|
red(text: string): string {
|
|
222
357
|
return this.sgr(text, SGR_RED)
|
|
223
358
|
}
|
|
224
359
|
|
|
225
|
-
/**
|
|
360
|
+
/**
|
|
361
|
+
* `text` in the theme's green (`SGR_GREEN`).
|
|
362
|
+
*
|
|
363
|
+
* @param text the words to colour.
|
|
364
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
365
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
366
|
+
*/
|
|
226
367
|
green(text: string): string {
|
|
227
368
|
return this.sgr(text, SGR_GREEN)
|
|
228
369
|
}
|
|
229
370
|
|
|
230
|
-
/**
|
|
371
|
+
/**
|
|
372
|
+
* `text` in the theme's yellow (`SGR_YELLOW`).
|
|
373
|
+
*
|
|
374
|
+
* @param text the words to colour.
|
|
375
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
376
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
377
|
+
*/
|
|
231
378
|
yellow(text: string): string {
|
|
232
379
|
return this.sgr(text, SGR_YELLOW)
|
|
233
380
|
}
|
|
234
381
|
|
|
235
|
-
/**
|
|
382
|
+
/**
|
|
383
|
+
* `text` in the theme's blue (`SGR_BLUE`).
|
|
384
|
+
*
|
|
385
|
+
* @param text the words to colour.
|
|
386
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
387
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
388
|
+
*/
|
|
236
389
|
blue(text: string): string {
|
|
237
390
|
return this.sgr(text, SGR_BLUE)
|
|
238
391
|
}
|
|
239
392
|
|
|
240
|
-
/**
|
|
393
|
+
/**
|
|
394
|
+
* `text` in the theme's magenta (`SGR_MAGENTA`).
|
|
395
|
+
*
|
|
396
|
+
* @param text the words to colour.
|
|
397
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
398
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
399
|
+
*/
|
|
241
400
|
magenta(text: string): string {
|
|
242
401
|
return this.sgr(text, SGR_MAGENTA)
|
|
243
402
|
}
|
|
244
403
|
|
|
245
|
-
/**
|
|
404
|
+
/**
|
|
405
|
+
* `text` in the theme's cyan (`SGR_CYAN`).
|
|
406
|
+
*
|
|
407
|
+
* @param text the words to colour.
|
|
408
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
409
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
410
|
+
*/
|
|
246
411
|
cyan(text: string): string {
|
|
247
412
|
return this.sgr(text, SGR_CYAN)
|
|
248
413
|
}
|
|
249
414
|
|
|
250
|
-
/**
|
|
415
|
+
/**
|
|
416
|
+
* `text` in the theme's white (`SGR_WHITE`).
|
|
417
|
+
*
|
|
418
|
+
* @param text the words to colour.
|
|
419
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
420
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
421
|
+
*/
|
|
251
422
|
white(text: string): string {
|
|
252
423
|
return this.sgr(text, SGR_WHITE)
|
|
253
424
|
}
|
|
254
425
|
|
|
255
|
-
/**
|
|
426
|
+
/**
|
|
427
|
+
* `text` in the theme's bright black, a gray (`SGR_BRIGHT_BLACK`).
|
|
428
|
+
*
|
|
429
|
+
* @param text the words to colour.
|
|
430
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
431
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
432
|
+
*/
|
|
256
433
|
brightBlack(text: string): string {
|
|
257
434
|
return this.sgr(text, SGR_BRIGHT_BLACK)
|
|
258
435
|
}
|
|
259
436
|
|
|
260
|
-
/**
|
|
437
|
+
/**
|
|
438
|
+
* `text` in the theme's bright red (`SGR_BRIGHT_RED`).
|
|
439
|
+
*
|
|
440
|
+
* @param text the words to colour.
|
|
441
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
442
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
443
|
+
*/
|
|
261
444
|
brightRed(text: string): string {
|
|
262
445
|
return this.sgr(text, SGR_BRIGHT_RED)
|
|
263
446
|
}
|
|
264
447
|
|
|
265
|
-
/**
|
|
448
|
+
/**
|
|
449
|
+
* `text` in the theme's bright green (`SGR_BRIGHT_GREEN`).
|
|
450
|
+
*
|
|
451
|
+
* @param text the words to colour.
|
|
452
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
453
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
454
|
+
*/
|
|
266
455
|
brightGreen(text: string): string {
|
|
267
456
|
return this.sgr(text, SGR_BRIGHT_GREEN)
|
|
268
457
|
}
|
|
269
458
|
|
|
270
|
-
/**
|
|
459
|
+
/**
|
|
460
|
+
* `text` in the theme's bright yellow (`SGR_BRIGHT_YELLOW`).
|
|
461
|
+
*
|
|
462
|
+
* @param text the words to colour.
|
|
463
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
464
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
465
|
+
*/
|
|
271
466
|
brightYellow(text: string): string {
|
|
272
467
|
return this.sgr(text, SGR_BRIGHT_YELLOW)
|
|
273
468
|
}
|
|
274
469
|
|
|
275
|
-
/**
|
|
470
|
+
/**
|
|
471
|
+
* `text` in the theme's bright blue (`SGR_BRIGHT_BLUE`).
|
|
472
|
+
*
|
|
473
|
+
* @param text the words to colour.
|
|
474
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
475
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
476
|
+
*/
|
|
276
477
|
brightBlue(text: string): string {
|
|
277
478
|
return this.sgr(text, SGR_BRIGHT_BLUE)
|
|
278
479
|
}
|
|
279
480
|
|
|
280
|
-
/**
|
|
481
|
+
/**
|
|
482
|
+
* `text` in the theme's bright magenta (`SGR_BRIGHT_MAGENTA`).
|
|
483
|
+
*
|
|
484
|
+
* @param text the words to colour.
|
|
485
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
486
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
487
|
+
*/
|
|
281
488
|
brightMagenta(text: string): string {
|
|
282
489
|
return this.sgr(text, SGR_BRIGHT_MAGENTA)
|
|
283
490
|
}
|
|
284
491
|
|
|
285
|
-
/**
|
|
492
|
+
/**
|
|
493
|
+
* `text` in the theme's bright cyan (`SGR_BRIGHT_CYAN`).
|
|
494
|
+
*
|
|
495
|
+
* @param text the words to colour.
|
|
496
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
497
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
498
|
+
*/
|
|
286
499
|
brightCyan(text: string): string {
|
|
287
500
|
return this.sgr(text, SGR_BRIGHT_CYAN)
|
|
288
501
|
}
|
|
289
502
|
|
|
290
|
-
/**
|
|
503
|
+
/**
|
|
504
|
+
* `text` in the theme's bright white (`SGR_BRIGHT_WHITE`).
|
|
505
|
+
*
|
|
506
|
+
* @param text the words to colour.
|
|
507
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
508
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
509
|
+
*/
|
|
291
510
|
brightWhite(text: string): string {
|
|
292
511
|
return this.sgr(text, SGR_BRIGHT_WHITE)
|
|
293
512
|
}
|
|
294
513
|
|
|
295
|
-
/**
|
|
514
|
+
/**
|
|
515
|
+
* `text` on the theme's black (`SGR_BG_BLACK`).
|
|
516
|
+
*
|
|
517
|
+
* @param text the words to colour.
|
|
518
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
519
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
520
|
+
*/
|
|
296
521
|
bgBlack(text: string): string {
|
|
297
522
|
return this.sgr(text, SGR_BG_BLACK)
|
|
298
523
|
}
|
|
299
524
|
|
|
300
|
-
/**
|
|
525
|
+
/**
|
|
526
|
+
* `text` on the theme's red (`SGR_BG_RED`).
|
|
527
|
+
*
|
|
528
|
+
* @param text the words to colour.
|
|
529
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
530
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
531
|
+
*/
|
|
301
532
|
bgRed(text: string): string {
|
|
302
533
|
return this.sgr(text, SGR_BG_RED)
|
|
303
534
|
}
|
|
304
535
|
|
|
305
|
-
/**
|
|
536
|
+
/**
|
|
537
|
+
* `text` on the theme's green (`SGR_BG_GREEN`).
|
|
538
|
+
*
|
|
539
|
+
* @param text the words to colour.
|
|
540
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
541
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
542
|
+
*/
|
|
306
543
|
bgGreen(text: string): string {
|
|
307
544
|
return this.sgr(text, SGR_BG_GREEN)
|
|
308
545
|
}
|
|
309
546
|
|
|
310
|
-
/**
|
|
547
|
+
/**
|
|
548
|
+
* `text` on the theme's yellow (`SGR_BG_YELLOW`).
|
|
549
|
+
*
|
|
550
|
+
* @param text the words to colour.
|
|
551
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
552
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
553
|
+
*/
|
|
311
554
|
bgYellow(text: string): string {
|
|
312
555
|
return this.sgr(text, SGR_BG_YELLOW)
|
|
313
556
|
}
|
|
314
557
|
|
|
315
|
-
/**
|
|
558
|
+
/**
|
|
559
|
+
* `text` on the theme's blue (`SGR_BG_BLUE`).
|
|
560
|
+
*
|
|
561
|
+
* @param text the words to colour.
|
|
562
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
563
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
564
|
+
*/
|
|
316
565
|
bgBlue(text: string): string {
|
|
317
566
|
return this.sgr(text, SGR_BG_BLUE)
|
|
318
567
|
}
|
|
319
568
|
|
|
320
|
-
/**
|
|
569
|
+
/**
|
|
570
|
+
* `text` on the theme's magenta (`SGR_BG_MAGENTA`).
|
|
571
|
+
*
|
|
572
|
+
* @param text the words to colour.
|
|
573
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
574
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
575
|
+
*/
|
|
321
576
|
bgMagenta(text: string): string {
|
|
322
577
|
return this.sgr(text, SGR_BG_MAGENTA)
|
|
323
578
|
}
|
|
324
579
|
|
|
325
|
-
/**
|
|
580
|
+
/**
|
|
581
|
+
* `text` on the theme's cyan (`SGR_BG_CYAN`).
|
|
582
|
+
*
|
|
583
|
+
* @param text the words to colour.
|
|
584
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
585
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
586
|
+
*/
|
|
326
587
|
bgCyan(text: string): string {
|
|
327
588
|
return this.sgr(text, SGR_BG_CYAN)
|
|
328
589
|
}
|
|
329
590
|
|
|
330
|
-
/**
|
|
591
|
+
/**
|
|
592
|
+
* `text` on the theme's white (`SGR_BG_WHITE`).
|
|
593
|
+
*
|
|
594
|
+
* @param text the words to colour.
|
|
595
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
596
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
597
|
+
*/
|
|
331
598
|
bgWhite(text: string): string {
|
|
332
599
|
return this.sgr(text, SGR_BG_WHITE)
|
|
333
600
|
}
|
|
334
601
|
|
|
335
|
-
/**
|
|
602
|
+
/**
|
|
603
|
+
* `text` on the theme's bright black (`SGR_BG_BRIGHT_BLACK`).
|
|
604
|
+
*
|
|
605
|
+
* @param text the words to colour.
|
|
606
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
607
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
608
|
+
*/
|
|
336
609
|
bgBrightBlack(text: string): string {
|
|
337
610
|
return this.sgr(text, SGR_BG_BRIGHT_BLACK)
|
|
338
611
|
}
|
|
339
612
|
|
|
340
|
-
/**
|
|
613
|
+
/**
|
|
614
|
+
* `text` on the theme's bright red (`SGR_BG_BRIGHT_RED`).
|
|
615
|
+
*
|
|
616
|
+
* @param text the words to colour.
|
|
617
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
618
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
619
|
+
*/
|
|
341
620
|
bgBrightRed(text: string): string {
|
|
342
621
|
return this.sgr(text, SGR_BG_BRIGHT_RED)
|
|
343
622
|
}
|
|
344
623
|
|
|
345
|
-
/**
|
|
624
|
+
/**
|
|
625
|
+
* `text` on the theme's bright green (`SGR_BG_BRIGHT_GREEN`).
|
|
626
|
+
*
|
|
627
|
+
* @param text the words to colour.
|
|
628
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
629
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
630
|
+
*/
|
|
346
631
|
bgBrightGreen(text: string): string {
|
|
347
632
|
return this.sgr(text, SGR_BG_BRIGHT_GREEN)
|
|
348
633
|
}
|
|
349
634
|
|
|
350
|
-
/**
|
|
635
|
+
/**
|
|
636
|
+
* `text` on the theme's bright yellow (`SGR_BG_BRIGHT_YELLOW`).
|
|
637
|
+
*
|
|
638
|
+
* @param text the words to colour.
|
|
639
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
640
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
641
|
+
*/
|
|
351
642
|
bgBrightYellow(text: string): string {
|
|
352
643
|
return this.sgr(text, SGR_BG_BRIGHT_YELLOW)
|
|
353
644
|
}
|
|
354
645
|
|
|
355
|
-
/**
|
|
646
|
+
/**
|
|
647
|
+
* `text` on the theme's bright blue (`SGR_BG_BRIGHT_BLUE`).
|
|
648
|
+
*
|
|
649
|
+
* @param text the words to colour.
|
|
650
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
651
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
652
|
+
*/
|
|
356
653
|
bgBrightBlue(text: string): string {
|
|
357
654
|
return this.sgr(text, SGR_BG_BRIGHT_BLUE)
|
|
358
655
|
}
|
|
359
656
|
|
|
360
|
-
/**
|
|
657
|
+
/**
|
|
658
|
+
* `text` on the theme's bright magenta (`SGR_BG_BRIGHT_MAGENTA`).
|
|
659
|
+
*
|
|
660
|
+
* @param text the words to colour.
|
|
661
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
662
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
663
|
+
*/
|
|
361
664
|
bgBrightMagenta(text: string): string {
|
|
362
665
|
return this.sgr(text, SGR_BG_BRIGHT_MAGENTA)
|
|
363
666
|
}
|
|
364
667
|
|
|
365
|
-
/**
|
|
668
|
+
/**
|
|
669
|
+
* `text` on the theme's bright cyan (`SGR_BG_BRIGHT_CYAN`).
|
|
670
|
+
*
|
|
671
|
+
* @param text the words to colour.
|
|
672
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
673
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
674
|
+
*/
|
|
366
675
|
bgBrightCyan(text: string): string {
|
|
367
676
|
return this.sgr(text, SGR_BG_BRIGHT_CYAN)
|
|
368
677
|
}
|
|
369
678
|
|
|
370
|
-
/**
|
|
679
|
+
/**
|
|
680
|
+
* `text` on the theme's bright white (`SGR_BG_BRIGHT_WHITE`).
|
|
681
|
+
*
|
|
682
|
+
* @param text the words to colour.
|
|
683
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
684
|
+
* when colour is off (the failsafe included) or `text` is empty.
|
|
685
|
+
*/
|
|
371
686
|
bgBrightWhite(text: string): string {
|
|
372
687
|
return this.sgr(text, SGR_BG_BRIGHT_WHITE)
|
|
373
688
|
}
|
|
374
689
|
|
|
375
|
-
/**
|
|
690
|
+
/**
|
|
691
|
+
* `text` bold (`SGR_BOLD`), under the failsafe too.
|
|
692
|
+
*
|
|
693
|
+
* @param text the words to mark up.
|
|
694
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
695
|
+
* when marking up is off or `text` is empty.
|
|
696
|
+
*/
|
|
376
697
|
bold(text: string): string {
|
|
377
698
|
return this.paint(text, SGR_BOLD, SGR_BOLD)
|
|
378
699
|
}
|
|
379
700
|
|
|
380
|
-
/**
|
|
701
|
+
/**
|
|
702
|
+
* `text` faint (`SGR_FAINT`), under the failsafe too.
|
|
703
|
+
*
|
|
704
|
+
* @param text the words to mark up.
|
|
705
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
706
|
+
* when marking up is off or `text` is empty.
|
|
707
|
+
*/
|
|
381
708
|
faint(text: string): string {
|
|
382
709
|
return this.paint(text, SGR_FAINT, SGR_FAINT)
|
|
383
710
|
}
|
|
384
711
|
|
|
385
|
-
/**
|
|
712
|
+
/**
|
|
713
|
+
* `text` italic (`SGR_ITALIC`), where the terminal has it, under the
|
|
714
|
+
* failsafe too.
|
|
715
|
+
*
|
|
716
|
+
* @param text the words to mark up.
|
|
717
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
718
|
+
* when marking up is off or `text` is empty.
|
|
719
|
+
*/
|
|
386
720
|
italic(text: string): string {
|
|
387
721
|
return this.paint(text, SGR_ITALIC, SGR_ITALIC)
|
|
388
722
|
}
|
|
389
723
|
|
|
390
|
-
/**
|
|
724
|
+
/**
|
|
725
|
+
* `text` underlined (`SGR_UNDERLINE`), under the failsafe too.
|
|
726
|
+
*
|
|
727
|
+
* @param text the words to mark up.
|
|
728
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
729
|
+
* when marking up is off or `text` is empty.
|
|
730
|
+
*/
|
|
391
731
|
underline(text: string): string {
|
|
392
732
|
return this.paint(text, SGR_UNDERLINE, SGR_UNDERLINE)
|
|
393
733
|
}
|
|
394
734
|
|
|
395
|
-
/**
|
|
735
|
+
/**
|
|
736
|
+
* `text` with foreground and background swapped (`SGR_INVERSE`), under
|
|
737
|
+
* the failsafe too.
|
|
738
|
+
*
|
|
739
|
+
* @param text the words to mark up.
|
|
740
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
741
|
+
* when marking up is off or `text` is empty.
|
|
742
|
+
*/
|
|
396
743
|
inverse(text: string): string {
|
|
397
744
|
return this.paint(text, SGR_INVERSE, SGR_INVERSE)
|
|
398
745
|
}
|
|
399
746
|
|
|
400
|
-
/**
|
|
747
|
+
/**
|
|
748
|
+
* `text` struck through (`SGR_STRIKETHROUGH`), under the failsafe too.
|
|
749
|
+
*
|
|
750
|
+
* @param text the words to mark up.
|
|
751
|
+
* @returns `text` wrapped in the escape and a reset, or `text` unchanged
|
|
752
|
+
* when marking up is off or `text` is empty.
|
|
753
|
+
*/
|
|
401
754
|
strikethrough(text: string): string {
|
|
402
755
|
return this.paint(text, SGR_STRIKETHROUGH, SGR_STRIKETHROUGH)
|
|
403
756
|
}
|
|
@@ -478,6 +831,9 @@ const styleOfPalette = (palette: i32): Style => {
|
|
|
478
831
|
* value for yes. Without it, the variables the agents that set one put in
|
|
479
832
|
* their commands' environment (Claude Code's `CLAUDECODE`, Gemini CLI's
|
|
480
833
|
* `GEMINI_CLI`) say yes.
|
|
834
|
+
*
|
|
835
|
+
* @returns `true` when an agent is judged to be at the keyboard, the answer
|
|
836
|
+
* `styleFor`'s `agent` takes; it reads the environment afresh each call.
|
|
481
837
|
*/
|
|
482
838
|
export const agentDriven = (): boolean => {
|
|
483
839
|
if (envIsSet("NISH_AGENT")) {
|
|
@@ -496,6 +852,14 @@ export const agentDriven = (): boolean => {
|
|
|
496
852
|
* colour is the theme's, asked of nothing: the reader is a pager or an editor
|
|
497
853
|
* that renders the escapes itself (Emacs's shell sets `TERM=dumb` and paints
|
|
498
854
|
* ANSI colour), so `TERM` does not describe it, and forcing forks nothing.
|
|
855
|
+
*
|
|
856
|
+
* @param fd the descriptor the painted text is written to, 1 for standard
|
|
857
|
+
* output or 2 for standard error; only the terminal check reads it.
|
|
858
|
+
* @param agent whether the reader is an agent, as `agentDriven` answered;
|
|
859
|
+
* `true` gives plain text, whatever forces colour.
|
|
860
|
+
* @returns a new `Style` each call, the caller's to keep and recolour: one
|
|
861
|
+
* that paints the theme, one that paints the failsafe, or one that paints
|
|
862
|
+
* nothing.
|
|
499
863
|
*/
|
|
500
864
|
export const styleFor = (fd: i32, agent: boolean): Style => {
|
|
501
865
|
const level = getenv("FORCE_COLOR")
|
|
@@ -544,13 +908,27 @@ const padTo = (width: i32, column: i32): string => spaces(width + 2 <= column ?
|
|
|
544
908
|
* up whether or not `style` paints, as long as the text is ASCII.
|
|
545
909
|
*/
|
|
546
910
|
export class HelpMenu {
|
|
547
|
-
style: Style
|
|
548
|
-
program: string
|
|
549
|
-
column: i32
|
|
550
|
-
usageColumn: i32
|
|
551
|
-
lines: string[]
|
|
552
|
-
usages: i32
|
|
911
|
+
private style: Style
|
|
912
|
+
private program: string
|
|
913
|
+
private column: i32
|
|
914
|
+
private usageColumn: i32
|
|
915
|
+
private lines: string[]
|
|
916
|
+
private usages: i32
|
|
553
917
|
|
|
918
|
+
/**
|
|
919
|
+
* An empty menu; nothing is written until `text` is asked for.
|
|
920
|
+
*
|
|
921
|
+
* @param style the painter for every line the menu builds. The menu keeps
|
|
922
|
+
* this same `Style`, not a copy, so a role recoloured on it later paints
|
|
923
|
+
* the lines added after.
|
|
924
|
+
* @param program the tool's name, which opens the title line and every
|
|
925
|
+
* usage line.
|
|
926
|
+
* @param column how many plain columns come before a row's description,
|
|
927
|
+
* counted from the start of the line; a row whose flag and placeholder
|
|
928
|
+
* reach within two columns of it gets two spaces instead.
|
|
929
|
+
* @param usageColumn the same for a usage line's description, counted from
|
|
930
|
+
* the start of `usage:`; set it past the longest command shape.
|
|
931
|
+
*/
|
|
554
932
|
constructor(style: Style, program: string, column: i32, usageColumn: i32) {
|
|
555
933
|
this.style = style
|
|
556
934
|
this.program = program
|
|
@@ -560,7 +938,14 @@ export class HelpMenu {
|
|
|
560
938
|
this.usages = 0
|
|
561
939
|
}
|
|
562
940
|
|
|
563
|
-
/**
|
|
941
|
+
/**
|
|
942
|
+
* The opening line, the program's name, `version` and a one-line `summary`,
|
|
943
|
+
* and a blank after it.
|
|
944
|
+
*
|
|
945
|
+
* @param version the version shown after the name, faint, such as `1.0.0`.
|
|
946
|
+
* @param summary what the tool is for, in a few words, faint, two spaces
|
|
947
|
+
* after the version.
|
|
948
|
+
*/
|
|
564
949
|
header(version: string, summary: string): void {
|
|
565
950
|
this.title(version, summary)
|
|
566
951
|
this.lines.push("")
|
|
@@ -569,6 +954,9 @@ export class HelpMenu {
|
|
|
569
954
|
/**
|
|
570
955
|
* The opening line alone, without `header`'s blank after it, for a menu that
|
|
571
956
|
* puts something under its title (`line`) before the blank.
|
|
957
|
+
*
|
|
958
|
+
* @param version the version shown after the name, faint.
|
|
959
|
+
* @param summary what the tool is for, faint, two spaces after the version.
|
|
572
960
|
*/
|
|
573
961
|
title(version: string, summary: string): void {
|
|
574
962
|
const style = this.style
|
|
@@ -578,6 +966,9 @@ export class HelpMenu {
|
|
|
578
966
|
/**
|
|
579
967
|
* A line exactly as given, painted (or not) by the caller with the menu's
|
|
580
968
|
* `style`: a rule, a banner, a blank. Its width is the caller's to keep.
|
|
969
|
+
*
|
|
970
|
+
* @param text the whole line, with any escapes already in it; `""` adds a
|
|
971
|
+
* blank line.
|
|
581
972
|
*/
|
|
582
973
|
line(text: string): void {
|
|
583
974
|
this.lines.push(text)
|
|
@@ -587,6 +978,11 @@ export class HelpMenu {
|
|
|
587
978
|
* A usage line: the command `shape` after the program's name, and what it
|
|
588
979
|
* is for (`description` may be empty). The first opens with `usage:` and
|
|
589
980
|
* the rest are indented under it.
|
|
981
|
+
*
|
|
982
|
+
* @param shape the arguments and flags that follow the program's name, such
|
|
983
|
+
* as `<file.ts> [flags]`, painted as a flag.
|
|
984
|
+
* @param description what this form of the command does, faint, starting at
|
|
985
|
+
* `usageColumn`; `""` ends the line after `shape`.
|
|
590
986
|
*/
|
|
591
987
|
usage(shape: string, description: string): void {
|
|
592
988
|
const style = this.style
|
|
@@ -597,7 +993,11 @@ export class HelpMenu {
|
|
|
597
993
|
this.usages = this.usages + 1
|
|
598
994
|
}
|
|
599
995
|
|
|
600
|
-
/**
|
|
996
|
+
/**
|
|
997
|
+
* A section: a blank line, then `title` as a heading.
|
|
998
|
+
*
|
|
999
|
+
* @param title the section's name, such as `Flags`, as it is shown.
|
|
1000
|
+
*/
|
|
601
1001
|
section(title: string): void {
|
|
602
1002
|
this.lines.push("")
|
|
603
1003
|
this.lines.push(this.style.heading(title))
|
|
@@ -606,6 +1006,12 @@ export class HelpMenu {
|
|
|
606
1006
|
/**
|
|
607
1007
|
* One row: the `flag` (or a command), its placeholder `meta` (may be
|
|
608
1008
|
* empty), and what it does, the description starting at `column`.
|
|
1009
|
+
*
|
|
1010
|
+
* @param flag the flag or command a person types, painted as a flag after
|
|
1011
|
+
* a two-space indent.
|
|
1012
|
+
* @param meta the placeholder for the flag's value, such as `<n>`, after
|
|
1013
|
+
* one space; `""` for a flag that takes none.
|
|
1014
|
+
* @param description what the flag does, faint.
|
|
609
1015
|
*/
|
|
610
1016
|
row(flag: string, meta: string, description: string): void {
|
|
611
1017
|
const style = this.style
|
|
@@ -616,17 +1022,32 @@ export class HelpMenu {
|
|
|
616
1022
|
)
|
|
617
1023
|
}
|
|
618
1024
|
|
|
619
|
-
/**
|
|
1025
|
+
/**
|
|
1026
|
+
* An indented line of prose, faint.
|
|
1027
|
+
*
|
|
1028
|
+
* @param text the prose, shown after two spaces.
|
|
1029
|
+
*/
|
|
620
1030
|
note(text: string): void {
|
|
621
1031
|
this.lines.push(` ${this.style.dim(text)}`)
|
|
622
1032
|
}
|
|
623
1033
|
|
|
624
|
-
/**
|
|
1034
|
+
/**
|
|
1035
|
+
* An indented line the reader fills in or opens, a path or a value, as a
|
|
1036
|
+
* placeholder.
|
|
1037
|
+
*
|
|
1038
|
+
* @param text the path or value, shown after two spaces.
|
|
1039
|
+
*/
|
|
625
1040
|
value(text: string): void {
|
|
626
1041
|
this.lines.push(` ${this.style.meta(text)}`)
|
|
627
1042
|
}
|
|
628
1043
|
|
|
629
|
-
/**
|
|
1044
|
+
/**
|
|
1045
|
+
* The menu so far, its lines joined by newlines, with no newline after the
|
|
1046
|
+
* last.
|
|
1047
|
+
*
|
|
1048
|
+
* @returns a new string each call; the menu keeps its lines, so a later
|
|
1049
|
+
* call also has what was added since.
|
|
1050
|
+
*/
|
|
630
1051
|
text(): string {
|
|
631
1052
|
return this.lines.join("\n")
|
|
632
1053
|
}
|