lib/usage.ts
835 LOC · 835 covered · 0 uncovered · 195 ranges · 1119 concepts · 85 introducers · 788 tests
File neighbourhood
The centred file is linked to every concept that introduces one of its ranges, every test that runs code from the file, and the gray connector concepts standing between those tests and the file's own introducer concepts. Undirected links join concepts to every file where they introduce source and concepts to the tests they introduce; arrows show specialization between the displayed concepts and bridge only concepts omitted from this view. Concept colors match the source ranges below; connector concepts have no source color and are shown in gray.
Focused file, its introducer and connector concepts, their introduced files, and tests that run code from the file
In the embedded map, ordinary wheel input scrolls the page; use the visible controls to zoom and drag to pan. Open the full-screen map for canvas navigation: wheel pans, Ctrl/Command plus wheel zooms, and arrow keys pan when this region is focused. On touch screens, open the full-screen map to pan or pinch. If JavaScript or WebGL is unavailable, use the related-file, concept, and source links on this page.
Graph controls are ready.
Interactive rendering requires JavaScript and WebGL. Use the related-file, concept, and source links on this page while the interactive map is unavailable.
2
>
// failures, etc. keeps logging in one place.
3
>
import {Dictionary, PlatformShim, nil} from './typings/common-types.js';
4
>
import {objFilter} from './utils/obj-filter.js';
5
>
import {YargsInstance} from './yargs-factory.js';
6
>
import {YError} from './yerror.js';
7
>
import {DetailedArguments} from './typings/yargs-parser-types.js';
8
>
import setBlocking from './utils/set-blocking.js';
9
>
11
>
return typeof fail === 'boolean';
12
>
}
14
>
export function usage(yargs: YargsInstance, shim: PlatformShim) {
16
>
const self = {} as UsageInstance;
17
>
18
>
// methods for outputting/building failure message.
19
>
const fails: (FailureFunction | boolean)[] = [];
20
>
self.failFn = function failFn(f) {
23
>
let failMessage: string | nil = null;
24
>
let globalFailMessage: string | nil = null;
25
>
let showHelpOnFail = true;
26
>
self.showHelpOnFail = function showHelpOnFailFn(
28
>
arg2?: string
29
>
) {
30
>
const [enabled, message] =
31
>
typeof arg1 === 'string' ? [true, arg1] : [arg1, arg2];
32
>
33
>
// If global context, set globalFailMessage
34
>
// Addresses: https://github.com/yargs/yargs/issues/2085
35
>
if (yargs.getInternalMethods().isGlobalContext()) {
37
>
}
39
>
failMessage = message;
40
>
showHelpOnFail = enabled;
41
>
return self;
43
>
44
>
let failureOutput = false;
45
>
self.fail = function fail(msg, err) {
47
>
48
>
if (fails.length) {
50
>
const fail = fails[i];
51
>
if (isBoolean(fail)) {
56
>
}
60
>
61
>
// don't output failure message more than once
62
>
if (!failureOutput) {
63
>
failureOutput = true;
64
>
if (showHelpOnFail) {
66
>
logger.error();
67
>
}
69
>
const globalOrCommandFailMessage = failMessage || globalFailMessage;
70
>
if (globalOrCommandFailMessage) {
72
>
logger.error(globalOrCommandFailMessage);
73
>
}
75
>
76
>
err = err || new YError(msg);
77
>
if (yargs.getExitProcess()) {
83
>
}
86
>
87
>
// methods for outputting/building help (usage) message.
88
>
let usages: [string, string][] = [];
89
>
let usageDisabled = false;
90
>
self.usage = (msg, description) => {
93
>
usages = [];
94
>
return self;
95
>
}
98
>
return self;
100
>
self.getUsage = () => {
103
>
self.getUsageDisabled = () => {
106
>
107
>
self.getPositionalGroupName = () => {
110
>
111
>
let examples: [string, string][] = [];
112
>
self.example = (cmd, description) => {
115
>
116
>
let commands: [string, string, boolean, string[], boolean][] = [];
117
>
self.command = function command(
119
>
description,
120
>
isDefault,
121
>
aliases,
122
>
deprecated = false
123
>
) {
124
>
// the last default wins, so cancel out any previously set default
125
>
if (isDefault) {
128
>
return cmdArray;
130
>
}
133
>
self.getCommands = () => commands;
134
>
135
>
let descriptions: Dictionary<string | undefined> = {};
136
>
self.describe = function describe(
137
>
keyOrKeys: string | string[] | Dictionary<string>,
138
>
desc?: string
139
>
) {
140
>
if (Array.isArray(keyOrKeys)) {
142
>
self.describe(k, desc);
143
>
});
146
>
self.describe(k, keyOrKeys[k]);
147
>
});
149
>
descriptions[keyOrKeys] = desc;
150
>
}
151
>
};
152
>
self.getDescriptions = () => descriptions;
153
>
154
>
let epilogs: string[] = [];
155
>
self.epilog = msg => {
158
>
159
>
let wrapSet = false;
160
>
let wrap: number | nil;
161
>
self.wrap = cols => {
163
>
wrap = cols;
165
>
166
>
self.getWrap = () => {
169
>
}
172
>
wrapSet = true;
173
>
}
175
>
return wrap;
177
>
178
>
const deferY18nLookupPrefix = '__yargsString__:';
179
>
self.deferY18nLookup = str => deferY18nLookupPrefix + str;
180
>
181
>
self.help = function help() {
183
>
normalizeAliases();
184
>
185
>
// handle old demanded API
186
>
const base$0 = yargs.customScriptName
187
>
? yargs.$0
188
>
: shim.path.basename(yargs.$0);
189
>
const demandedOptions = yargs.getDemandedOptions();
190
>
const demandedCommands = yargs.getDemandedCommands();
191
>
const deprecatedOptions = yargs.getDeprecatedOptions();
192
>
const groups = yargs.getGroups();
193
>
const options = yargs.getOptions();
194
>
195
>
let keys: string[] = [];
196
>
keys = keys.concat(Object.keys(descriptions));
197
>
keys = keys.concat(Object.keys(demandedOptions));
198
>
keys = keys.concat(Object.keys(demandedCommands));
199
>
keys = keys.concat(Object.keys(options.default));
200
>
keys = keys.filter(filterHiddenOptions);
201
>
keys = Object.keys(
202
>
keys.reduce((acc, key) => {
203
>
if (key !== '_') acc[key] = true;
204
>
return acc;
205
>
}, {} as Dictionary<boolean>)
206
>
);
207
>
208
>
const theWrap = self.getWrap();
209
>
const ui = shim.cliui({
210
>
width: theWrap,
211
>
wrap: !!theWrap,
212
>
});
213
>
214
>
// the usage string.
215
>
if (!usageDisabled) {
218
>
usages.forEach(usage => {
219
>
ui.div({text: `${usage[0].replace(/\$0/g, base$0)}`});
220
>
if (usage[1]) {
222
>
}
224
>
ui.div();
227
>
// demonstrate how commands are used.
228
>
if (demandedCommands._) {
232
>
}
234
>
}
237
>
// your application's commands, i.e., non-option
238
>
// arguments populated in '_'.
239
>
//
240
>
// If there's only a single command, and it's the default command
241
>
// (represented by commands[0][2]) don't show command stanza:
242
>
//
243
>
// TODO(@bcoe): why isn't commands[0][2] an object with a named property?
244
>
if (commands.length > 1 || (commands.length === 1 && !commands[0][2])) {
246
>
247
>
const context = yargs.getInternalMethods().getContext();
248
>
const parentCommands = context.commands.length
249
>
? `${context.commands.join(' ')} `
250
>
: '';
251
>
252
>
if (
253
>
yargs.getInternalMethods().getParserConfiguration()['sort-commands'] ===
254
>
true
255
>
) {
257
>
}
259
>
const prefix = base$0 ? `${base$0} ` : '';
260
>
261
>
commands.forEach(command => {
262
>
const commandString = `${prefix}${parentCommands}${command[0].replace(
263
>
/^\$0 ?/,
264
>
''
265
>
)}`; // drop $0 from default commands.
266
>
ui.span(
267
>
{
268
>
text: commandString,
269
>
padding: [0, 2, 0, 2],
270
>
width:
271
>
maxWidth(commands, theWrap, `${base$0}${parentCommands}`) + 4,
272
>
},
273
>
{text: command[1]}
274
>
);
275
>
const hints = [];
276
>
if (command[2]) hints.push(`[${__('default')}]`);
277
>
if (command[3] && command[3].length) {
279
>
}
285
>
}
289
>
text: hints.join(' '),
290
>
padding: [0, 0, 0, 2],
291
>
align: 'right',
292
>
});
295
>
}
297
>
298
>
ui.div();
299
>
}
301
>
// perform some cleanup on the keys array, making it
302
>
// only include top-level keys not their aliases.
303
>
const aliasKeys = (Object.keys(options.alias) || []).concat(
304
>
Object.keys((yargs.parsed as DetailedArguments).newAliases) || []
305
>
);
306
>
307
>
keys = keys.filter(
308
>
key =>
310
>
aliasKeys.every(
311
>
alias => (options.alias[alias] || []).indexOf(key) === -1
313
>
);
314
>
315
>
// populate 'Options:' group with any keys that have not
316
>
// explicitly had a group set.
317
>
const defaultGroup = __('Options:');
318
>
if (!groups[defaultGroup]) groups[defaultGroup] = [];
319
>
addUngroupedKeys(keys, options.alias, groups, defaultGroup);
320
>
321
>
const isLongSwitch = (sw: string | IndentedText) => /^--/.test(getText(sw));
322
>
323
>
// prepare 'Options:' tables display
324
>
const displayedGroups = Object.keys(groups)
325
>
.filter(groupName => groups[groupName].length > 0)
326
>
.map(groupName => {
328
>
// normalizedKeys should contain only 'foobar'.
329
>
const normalizedKeys: string[] = groups[groupName]
330
>
.filter(filterHiddenOptions)
331
>
.map(key => {
332
>
if (aliasKeys.includes(key)) return key;
334
>
let i = 0, aliasKey;
335
>
(aliasKey = aliasKeys[i]) !== undefined;
336
>
i++
337
>
) {
339
>
return aliasKey;
340
>
}
343
>
344
>
return {groupName, normalizedKeys};
346
>
.filter(({normalizedKeys}) => normalizedKeys.length > 0)
347
>
.map(({groupName, normalizedKeys}) => {
349
>
const switches: Dictionary<string | IndentedText> =
350
>
normalizedKeys.reduce((acc, key) => {
351
>
acc[key] = [key]
352
>
.concat(options.alias[key] || [])
353
>
.map(sw => {
354
>
// for the special positional group don't
355
>
// add '--' or '-' prefix.
356
>
if (groupName === self.getPositionalGroupName()) return sw;
357
>
else {
358
>
return (
359
>
// matches yargs-parser logic in which single-digits
360
>
// aliases declared with a boolean type are now valid
361
>
(/^[0-9]$/.test(sw)
362
>
? options.boolean.includes(key)
364
>
: '--'
366
>
? '--'
367
>
: '-') + sw
368
>
);
369
>
}
370
>
})
371
>
// place short switches first (see #1403)
372
>
.sort((sw1, sw2) =>
374
>
? 0
375
>
: isLongSwitch(sw1)
377
>
: -1
379
>
.join(', ');
380
>
381
>
return acc;
382
>
}, {} as Dictionary<string>);
383
>
384
>
return {groupName, normalizedKeys, switches};
386
>
387
>
// if some options use short switches, indent long-switches only options (see #1403)
388
>
const shortSwitchesUsed = displayedGroups
389
>
.filter(({groupName}) => groupName !== self.getPositionalGroupName())
390
>
.some(
391
>
({normalizedKeys, switches}) =>
394
>
395
>
if (shortSwitchesUsed) {
397
>
.filter(({groupName}) => groupName !== self.getPositionalGroupName())
398
>
.forEach(({normalizedKeys, switches}) => {
399
>
normalizedKeys.forEach(key => {
400
>
if (isLongSwitch(switches[key])) {
402
>
}
404
>
});
405
>
}
407
>
// display 'Options:' table along with any custom tables:
408
>
displayedGroups.forEach(({groupName, normalizedKeys, switches}) => {
410
>
411
>
normalizedKeys.forEach(key => {
412
>
const kswitch = switches[key];
413
>
let desc = descriptions[key] || '';
414
>
let type = null;
415
>
416
>
if (desc.includes(deferY18nLookupPrefix))
417
>
desc = __(desc.substring(deferY18nLookupPrefix.length));
418
>
419
>
if (options.boolean.includes(key)) type = `[${__('boolean')}]`;
420
>
if (options.count.includes(key)) type = `[${__('count')}]`;
421
>
if (options.string.includes(key)) type = `[${__('string')}]`;
422
>
if (options.normalize.includes(key)) type = `[${__('string')}]`;
423
>
if (options.array.includes(key)) type = `[${__('array')}]`;
424
>
if (options.number.includes(key)) type = `[${__('number')}]`;
425
>
426
>
const deprecatedExtra = (deprecated?: string | boolean) =>
428
>
? `[${__('deprecated: %s', deprecated)}]`
430
>
431
>
const extra = [
432
>
key in deprecatedOptions
433
>
? deprecatedExtra(deprecatedOptions[key])
434
>
: null,
435
>
type,
436
>
key in demandedOptions ? `[${__('required')}]` : null,
437
>
options.choices && options.choices[key]
438
>
? `[${__('choices:')} ${self.stringifiedValues(
440
>
)}]`
442
>
defaultString(options.default[key], options.defaultDescription[key]),
443
>
]
444
>
.filter(Boolean)
445
>
.join(' ');
446
>
447
>
ui.span(
448
>
{
449
>
text: getText(kswitch),
450
>
padding: [0, 2, 0, 2 + getIndentation(kswitch)],
451
>
width: maxWidth(switches, theWrap) + 4,
452
>
},
453
>
desc
454
>
);
455
>
456
>
const shouldHideOptionExtras =
457
>
yargs.getInternalMethods().getUsageConfiguration()['hide-types'] ===
458
>
true;
459
>
460
>
if (extra && !shouldHideOptionExtras)
461
>
ui.div({text: extra, padding: [0, 0, 0, 2], align: 'right'});
464
>
465
>
ui.div();
467
>
468
>
// describe some common use-cases for your application.
469
>
if (examples.length) {
471
>
472
>
examples.forEach(example => {
473
>
example[0] = example[0].replace(/\$0/g, base$0);
474
>
});
475
>
476
>
examples.forEach(example => {
477
>
if (example[1] === '') {
479
>
text: example[0],
480
>
padding: [0, 2, 0, 2],
481
>
});
484
>
{
485
>
text: example[0],
486
>
padding: [0, 2, 0, 2],
487
>
width: maxWidth(examples, theWrap) + 4,
488
>
},
489
>
{
490
>
text: example[1],
491
>
}
492
>
);
493
>
}
495
>
496
>
ui.div();
497
>
}
499
>
// the usage string.
500
>
if (epilogs.length > 0) {
502
>
.map(epilog => epilog.replace(/\$0/g, base$0))
503
>
.join('\n');
504
>
ui.div(`${e}\n`);
505
>
}
507
>
// Remove the trailing white spaces
508
>
return ui.toString().replace(/\s*$/, '');
510
>
511
>
// return the maximum width of a string
512
>
// in the left-hand column of a table.
513
>
function maxWidth(
515
>
[string | IndentedText, ...any[]][] | Dictionary<string | IndentedText>,
516
>
theWrap?: number | null,
517
>
modifier?: string
518
>
) {
519
>
let width = 0;
520
>
521
>
// table might be of the form [leftColumn],
522
>
// or {key: leftColumn}
523
>
if (!Array.isArray(table)) {
524
>
table = Object.values(table).map<[string | IndentedText]>(v => [v]);
525
>
}
526
>
527
>
table.forEach(v => {
528
>
// column might be of the form "text"
529
>
// or { text: "text", indent: 4 }
530
>
width = Math.max(
531
>
shim.stringWidth(
532
>
modifier ? `${modifier} ${getText(v[0])}` : getText(v[0])
533
>
) + getIndentation(v[0]),
534
>
width
535
>
);
536
>
});
537
>
538
>
// if we've enabled 'wrap' we should limit
539
>
// the max-width of the left-column.
540
>
if (theWrap)
541
>
width = Math.min(width, parseInt((theWrap * 0.5).toString(), 10));
542
>
543
>
return width;
544
>
}
546
>
// make sure any options set for aliases,
547
>
// are copied to the keys being aliased.
548
>
function normalizeAliases() {
550
>
const demandedOptions = yargs.getDemandedOptions();
551
>
const options = yargs.getOptions();
552
>
553
>
(Object.keys(options.alias) || []).forEach(key => {
556
>
if (descriptions[alias]) self.describe(key, descriptions[alias]);
557
>
// copy demanded.
558
>
if (alias in demandedOptions)
559
>
yargs.demandOption(key, demandedOptions[alias]);
560
>
// type messages.
561
>
if (options.boolean.includes(alias)) yargs.boolean(key);
562
>
if (options.count.includes(alias)) yargs.count(key);
563
>
if (options.string.includes(alias)) yargs.string(key);
564
>
if (options.normalize.includes(alias)) yargs.normalize(key);
565
>
if (options.array.includes(alias)) yargs.array(key);
566
>
if (options.number.includes(alias)) yargs.number(key);
569
>
}
571
>
// if yargs is executing an async handler, we take a snapshot of the
572
>
// help message to display on failure:
573
>
let cachedHelpMessage: string | undefined;
574
>
self.cacheHelpMessage = function () {
577
>
578
>
// however this snapshot must be cleared afterwards
579
>
// not to be be used by next calls to parse
580
>
self.clearCachedHelpMessage = function () {
583
>
584
>
self.hasCachedHelpMessage = function () {
587
>
588
>
// given a set of keys, place any keys that are
589
>
// ungrouped under the 'Options:' grouping.
590
>
function addUngroupedKeys(
592
>
aliases: Dictionary<string[]>,
593
>
groups: Dictionary<string[]>,
594
>
defaultGroup: string
595
>
) {
596
>
let groupedKeys = [] as string[];
597
>
let toCheck = null;
598
>
Object.keys(groups).forEach(group => {
599
>
groupedKeys = groupedKeys.concat(groups[group]);
600
>
});
601
>
602
>
keys.forEach(key => {
604
>
if (!toCheck.some(k => groupedKeys.indexOf(k) !== -1)) {
606
>
}
608
>
return groupedKeys;
609
>
}
611
>
function filterHiddenOptions(key: string) {
613
>
yargs.getOptions().hiddenOptions.indexOf(key) < 0 ||
616
>
}
618
>
self.showHelp = (level: 'error' | 'log' | ((message: string) => void)) => {
620
>
if (!level) level = 'error';
621
>
const emit = typeof level === 'function' ? level : logger[level];
622
>
emit(self.help());
624
>
625
>
self.functionDescription = fn => {
627
>
? shim.Parser.decamelize(fn.name, '-')
628
>
: __('generated-value');
629
>
return ['(', description, ')'].join('');
631
>
632
>
self.stringifiedValues = function stringifiedValues(values, separator) {
634
>
const sep = separator || ', ';
635
>
const array = ([] as any[]).concat(values);
636
>
637
>
if (!values || !array.length) return string;
638
>
639
>
array.forEach(value => {
640
>
if (string.length) string += sep;
641
>
string += JSON.stringify(value);
642
>
});
643
>
644
>
return string;
646
>
647
>
// format the default-value-string displayed in
648
>
// the right-hand column.
649
>
function defaultString(value: any, defaultDescription?: string) {
651
>
652
>
if (value === undefined && !defaultDescription) return null;
654
>
if (defaultDescription) {
658
>
case 'string':
660
>
break;
663
>
break;
667
>
}
669
>
return `${string}]`;
670
>
}
672
>
// guess the width of the console window, max-width 80.
673
>
function windowWidth() {
675
>
// CI is not a TTY
677
>
if (shim.process.stdColumns) {
678
>
return Math.min(maxWidth, shim.process.stdColumns);
680
>
return maxWidth;
681
>
}
682
>
}
684
>
// logic for displaying application version.
685
>
let version: any = null;
686
>
self.version = ver => {
687
>
version = ver;
688
>
};
689
>
690
>
self.showVersion = level => {
692
>
if (!level) level = 'error';
693
>
const emit = typeof level === 'function' ? level : logger[level];
694
>
emit(version);
696
>
697
>
self.reset = function reset(localLookup) {
699
>
// do not reset fails here
700
>
failMessage = null;
701
>
failureOutput = false;
702
>
usages = [];
703
>
usageDisabled = false;
704
>
epilogs = [];
705
>
examples = [];
706
>
commands = [];
707
>
descriptions = objFilter(descriptions, k => !localLookup[k]);
708
>
return self;
710
>
711
>
const frozens = [] as FrozenUsageInstance[];
712
>
self.freeze = function freeze() {
714
>
failMessage,
715
>
failureOutput,
716
>
usages,
717
>
usageDisabled,
718
>
epilogs,
719
>
examples,
720
>
commands,
721
>
descriptions,
722
>
});
724
>
self.unfreeze = function unfreeze(defaultCommand = false) {
726
>
// In the case of running a defaultCommand, we reset
727
>
// usage early to ensure we receive the top level instructions.
728
>
// unfreezing again should just be a noop:
729
>
if (!frozen) return;
730
>
// Addresses: https://github.com/yargs/yargs/issues/2030
731
>
if (defaultCommand) {
733
>
commands = [...frozen.commands, ...commands];
734
>
usages = [...frozen.usages, ...usages];
735
>
examples = [...frozen.examples, ...examples];
736
>
epilogs = [...frozen.epilogs, ...epilogs];
739
>
failMessage,
740
>
failureOutput,
741
>
usages,
742
>
usageDisabled,
743
>
epilogs,
744
>
examples,
745
>
commands,
746
>
descriptions,
747
>
} = frozen);
748
>
}
750
>
751
>
return self;
752
>
}
754
>
/** Instance of the usage module. */
755
>
export interface UsageInstance {
756
>
cacheHelpMessage(): void;
757
>
clearCachedHelpMessage(): void;
758
>
hasCachedHelpMessage(): boolean;
759
>
command(
760
>
cmd: string,
761
>
description: string | undefined,
762
>
isDefault: boolean,
763
>
aliases: string[],
764
>
deprecated?: boolean
765
>
): void;
766
>
deferY18nLookup(str: string): string;
767
>
describe(keys: string | string[] | Dictionary<string>, desc?: string): void;
768
>
epilog(msg: string): void;
769
>
example(cmd: string, description?: string): void;
770
>
fail(msg?: string | null, err?: YError | string): void;
771
>
failFn(f: FailureFunction | boolean): void;
772
>
freeze(): void;
773
>
functionDescription(fn: {name?: string}): string;
774
>
getCommands(): [string, string, boolean, string[], boolean][];
775
>
getDescriptions(): Dictionary<string | undefined>;
776
>
getPositionalGroupName(): string;
777
>
getUsage(): [string, string][];
778
>
getUsageDisabled(): boolean;
779
>
getWrap(): number | nil;
780
>
help(): string;
781
>
reset(localLookup: Dictionary<boolean>): UsageInstance;
782
>
showHelp(level?: 'error' | 'log' | ((message: string) => void)): void;
783
>
showHelpOnFail(enabled?: boolean | string, message?: string): UsageInstance;
784
>
showVersion(level?: 'error' | 'log' | ((message: string) => void)): void;
785
>
stringifiedValues(values?: any[], separator?: string): string;
786
>
unfreeze(defaultCommand?: boolean): void;
787
>
usage(msg: string | null, description?: string | false): UsageInstance;
788
>
version(ver: any): void;
789
>
wrap(cols: number | nil): void;
790
>
}
791
>
792
>
export interface FailureFunction {
793
>
(
794
>
msg: string | nil,
795
>
err: YError | string | undefined,
796
>
usage: UsageInstance
797
>
): void;
798
>
}
799
>
800
>
export interface FrozenUsageInstance {
801
>
failMessage: string | nil;
802
>
failureOutput: boolean;
803
>
usages: [string, string][];
804
>
usageDisabled: boolean;
805
>
epilogs: string[];
806
>
examples: [string, string][];
807
>
commands: [string, string, boolean, string[], boolean][];
808
>
descriptions: Dictionary<string | undefined>;
809
>
}
810
>
811
>
interface IndentedText {
812
>
text: string;
813
>
indentation: number;
814
>
}
815
>
817
>
return typeof text === 'object';
818
>
}
821
>
text: string | IndentedText,
822
>
indent: number
823
>
): IndentedText {
824
>
return isIndentedText(text)
825
>
? {text: text.text, indentation: text.indentation + indent}
826
>
: {text, indentation: indent};
827
>
}
830
>
return isIndentedText(text) ? text.indentation : 0;
831
>
}
834
>
return isIndentedText(text) ? text.text : text;
835
>
}