lib/yargs-factory.ts
2437 LOC · 2437 covered · 0 uncovered · 555 ranges · 1119 concepts · 263 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
>
// Platform agnostic entrypoint for yargs, i.e., this factory is used to
3
>
// create an instance of yargs for CJS, ESM, Deno.
4
>
//
5
>
// Works by accepting a shim which shims methods that contain platform
6
>
// specific logic.
7
>
import {
8
>
command as Command,
9
>
CommandInstance,
10
>
CommandHandler,
11
>
CommandBuilderDefinition,
12
>
CommandBuilder,
13
>
CommandHandlerCallback,
14
>
CommandHandlerDefinition,
15
>
DefinitionOrCommandName,
16
>
} from './command.js';
17
>
import type {
18
>
Dictionary,
19
>
KeyOf,
20
>
DictionaryKeyof,
21
>
ValueOf,
22
>
RequireDirectoryOptions,
23
>
PlatformShim,
24
>
RequireType,
25
>
nil,
26
>
} from './typings/common-types.js';
27
>
import {
28
>
assertNotStrictEqual,
29
>
assertSingleKey,
30
>
objectKeys,
31
>
} from './typings/common-types.js';
32
>
import {
33
>
ArgsOutput,
34
>
DetailedArguments as ParserDetailedArguments,
35
>
Configuration as ParserConfiguration,
36
>
Options as ParserOptions,
37
>
ConfigCallback,
38
>
CoerceCallback,
39
>
} from './typings/yargs-parser-types.js';
40
>
import {YError} from './yerror.js';
41
>
import {UsageInstance, FailureFunction, usage as Usage} from './usage.js';
42
>
import {argsert} from './argsert.js';
43
>
import {
44
>
completion as Completion,
45
>
CompletionInstance,
46
>
CompletionFunction,
47
>
} from './completion.js';
48
>
import {
49
>
validation as Validation,
50
>
ValidationInstance,
51
>
KeyOrPos,
52
>
} from './validation.js';
53
>
import {objFilter} from './utils/obj-filter.js';
54
>
import {applyExtends} from './utils/apply-extends.js';
55
>
import {
56
>
applyMiddleware,
57
>
GlobalMiddleware,
58
>
MiddlewareCallback,
59
>
Middleware,
60
>
} from './middleware.js';
61
>
import {isPromise} from './utils/is-promise.js';
62
>
import {maybeAsyncResult} from './utils/maybe-async-result.js';
63
>
import setBlocking from './utils/set-blocking.js';
64
>
65
>
export function YargsFactory(_shim: PlatformShim) {
66
>
return (
68
>
cwd = _shim.process.cwd(),
69
>
parentRequire?: RequireType
70
>
): YargsInstance => {
71
>
const yargs = new YargsInstance(processArgs, cwd, parentRequire, _shim);
72
>
// Legacy yargs.argv interface, it's recommended that you use .parse().
73
>
Object.defineProperty(yargs, 'argv', {
74
>
get: () => {
77
>
enumerable: true,
78
>
});
79
>
// an app should almost always have --version and --help,
80
>
// if you *really* want to disable this use .help(false)/.version(false).
81
>
yargs.help();
82
>
yargs.version();
83
>
return yargs;
85
>
}
86
>
87
>
// Used to expose private methods to other module-level classes,
88
>
// such as the command parser and usage printer.
89
>
const kCopyDoubleDash = Symbol('copyDoubleDash');
90
>
const kCreateLogger = Symbol('copyDoubleDash');
91
>
const kDeleteFromParserHintObject = Symbol('deleteFromParserHintObject');
92
>
const kEmitWarning = Symbol('emitWarning');
93
>
const kFreeze = Symbol('freeze');
94
>
const kGetDollarZero = Symbol('getDollarZero');
95
>
const kGetParserConfiguration = Symbol('getParserConfiguration');
96
>
const kGetUsageConfiguration = Symbol('getUsageConfiguration');
97
>
const kGuessLocale = Symbol('guessLocale');
98
>
const kGuessVersion = Symbol('guessVersion');
99
>
const kParsePositionalNumbers = Symbol('parsePositionalNumbers');
100
>
const kPkgUp = Symbol('pkgUp');
101
>
const kPopulateParserHintArray = Symbol('populateParserHintArray');
102
>
const kPopulateParserHintSingleValueDictionary = Symbol(
103
>
'populateParserHintSingleValueDictionary'
104
>
);
105
>
const kPopulateParserHintArrayDictionary = Symbol(
106
>
'populateParserHintArrayDictionary'
107
>
);
108
>
const kPopulateParserHintDictionary = Symbol('populateParserHintDictionary');
109
>
const kSanitizeKey = Symbol('sanitizeKey');
110
>
const kSetKey = Symbol('setKey');
111
>
const kUnfreeze = Symbol('unfreeze');
112
>
const kValidateAsync = Symbol('validateAsync');
113
>
const kGetCommandInstance = Symbol('getCommandInstance');
114
>
const kGetContext = Symbol('getContext');
115
>
const kGetHasOutput = Symbol('getHasOutput');
116
>
const kGetLoggerInstance = Symbol('getLoggerInstance');
117
>
const kGetParseContext = Symbol('getParseContext');
118
>
const kGetUsageInstance = Symbol('getUsageInstance');
119
>
const kGetValidationInstance = Symbol('getValidationInstance');
120
>
const kHasParseCallback = Symbol('hasParseCallback');
121
>
const kIsGlobalContext = Symbol('isGlobalContext');
122
>
const kPostProcess = Symbol('postProcess');
123
>
const kRebase = Symbol('rebase');
124
>
const kReset = Symbol('reset');
125
>
const kRunYargsParserAndExecuteCommands = Symbol(
126
>
'runYargsParserAndExecuteCommands'
127
>
);
128
>
const kRunValidation = Symbol('runValidation');
129
>
const kSetHasOutput = Symbol('setHasOutput');
130
>
const kTrackManuallySetKeys = Symbol('kTrackManuallySetKeys');
131
>
const DEFAULT_LOCALE = 'en_US';
132
>
133
>
export interface YargsInternalMethods {
134
>
getCommandInstance(): CommandInstance;
135
>
getContext(): Context;
136
>
getHasOutput(): boolean;
137
>
getLoggerInstance(): LoggerInstance;
138
>
getParseContext(): object;
139
>
getParserConfiguration(): Configuration;
140
>
getUsageConfiguration(): UsageConfiguration;
141
>
getUsageInstance(): UsageInstance;
142
>
getValidationInstance(): ValidationInstance;
143
>
hasParseCallback(): boolean;
144
>
isGlobalContext(): boolean;
145
>
postProcess<T extends Arguments | Promise<Arguments>>(
146
>
argv: Arguments | Promise<Arguments>,
147
>
populateDoubleDash: boolean,
148
>
calledFromCommand: boolean,
149
>
runGlobalMiddleware: boolean
150
>
): any;
151
>
reset(aliases?: Aliases): YargsInstance;
152
>
runValidation(
153
>
aliases: Dictionary<string[]>,
154
>
positionalMap: Dictionary<string[]>,
155
>
parseErrors: Error | null,
156
>
isDefaultCommand?: boolean
157
>
): (argv: Arguments) => void;
158
>
runYargsParserAndExecuteCommands(
159
>
args: string | string[] | null,
160
>
shortCircuit?: boolean | null,
161
>
calledFromCommand?: boolean,
162
>
commandIndex?: number,
163
>
helpOnly?: boolean
164
>
): Arguments | Promise<Arguments>;
165
>
setHasOutput(): void;
166
>
}
167
>
168
>
export class YargsInstance {
169
>
$0: string;
170
>
argv?: Arguments;
171
>
customScriptName = false;
172
>
parsed: DetailedArguments | false = false;
173
>
174
>
#command: CommandInstance;
175
>
#cwd: string;
176
>
// use context object to keep track of resets, subcommand execution, etc.,
177
>
// submodules should modify and check the state of context as necessary:
178
>
#context: Context = {commands: [], fullCommands: []};
179
>
#completion: CompletionInstance | null = null;
180
>
#completionCommand: string | null = null;
181
>
#defaultShowHiddenOpt = 'show-hidden';
182
>
#exitError: YError | string | nil = null;
183
>
#detectLocale = true;
184
>
#emittedWarnings: Dictionary<boolean> = {};
185
>
#exitProcess = true;
186
>
#frozens: FrozenYargsInstance[] = [];
187
>
#globalMiddleware: GlobalMiddleware;
188
>
#groups: Dictionary<string[]> = {};
189
>
#hasOutput = false;
190
>
#helpOpt: string | null = null;
191
>
#isGlobalContext = true;
192
>
#logger: LoggerInstance;
193
>
#output = '';
194
>
#options: Options;
195
>
#parentRequire?: RequireType;
196
>
#parserConfig: Configuration = {};
197
>
#parseFn: ParseCallback | null = null;
198
>
#parseContext: object | null = null;
199
>
#pkgs: Dictionary<{[key: string]: string | {[key: string]: string}}> = {};
200
>
#preservedGroups: Dictionary<string[]> = {};
201
>
#processArgs: string | string[];
202
>
#recommendCommands = false;
203
>
#shim: PlatformShim;
204
>
#strict = false;
205
>
#strictCommands = false;
206
>
#strictOptions = false;
207
>
#usage: UsageInstance;
208
>
#usageConfig: UsageConfiguration = {};
209
>
#versionOpt: string | null = null;
210
>
#validation: ValidationInstance;
211
>
212
>
constructor(
214
>
cwd: string,
215
>
parentRequire: RequireType | undefined,
216
>
shim: PlatformShim
217
>
) {
218
>
this.#shim = shim;
219
>
this.#processArgs = processArgs;
220
>
this.#cwd = cwd;
221
>
this.#parentRequire = parentRequire;
222
>
this.#globalMiddleware = new GlobalMiddleware(this);
223
>
this.$0 = this[kGetDollarZero]();
224
>
// #command, #validation, and #usage are initialized on first reset:
225
>
this[kReset]();
226
>
this.#command = this!.#command;
227
>
this.#usage = this!.#usage;
228
>
this.#validation = this!.#validation;
229
>
this.#options = this!.#options;
230
>
this.#options.showHiddenOpt = this.#defaultShowHiddenOpt;
231
>
this.#logger = this[kCreateLogger]();
232
>
// y18n is a singleton intentionally, to prevent locales
233
>
// from being loaded multiple times off disk. We reset
234
>
// the language code whenever a new YargsInstance
235
>
// is created mainly for unit tests.
236
>
this.#shim.y18n.setLocale(DEFAULT_LOCALE);
237
>
}
240
>
argsert('[string|boolean] [string]', [opt, msg], arguments.length);
241
>
242
>
// nuke the key previously configured
243
>
// to return help.
244
>
if (this.#helpOpt) {
246
>
this.#helpOpt = null;
247
>
}
249
>
if (opt === false && msg === undefined) return this;
250
>
251
>
// use arguments, fallback to defaults for opt and msg
252
>
this.#helpOpt = typeof opt === 'string' ? opt : defaultHelpOpt;
253
>
this.boolean(this.#helpOpt);
254
>
this.describe(
255
>
this.#helpOpt,
256
>
msg || this.#usage.deferY18nLookup('Show help')
257
>
);
258
>
return this;
259
>
}
262
>
}
264
>
addShowHiddenOpt(opt?: string | false, msg?: string): YargsInstance {
266
>
if (opt === false && msg === undefined) return this;
267
>
const showHiddenOpt =
268
>
typeof opt === 'string' ? opt : this.#defaultShowHiddenOpt;
269
>
this.boolean(showHiddenOpt);
270
>
this.describe(
271
>
showHiddenOpt,
272
>
msg || this.#usage.deferY18nLookup('Show hidden options')
273
>
);
274
>
this.#options.showHiddenOpt = showHiddenOpt;
275
>
return this;
276
>
}
279
>
}
281
>
alias(
283
>
value?: string | string[]
284
>
): YargsInstance {
285
>
argsert(
286
>
'<object|string|array> [string|array]',
287
>
[key, value],
288
>
arguments.length
289
>
);
290
>
this[kPopulateParserHintArrayDictionary](
291
>
this.alias.bind(this),
292
>
'alias',
293
>
key,
294
>
value
295
>
);
296
>
return this;
297
>
}
300
>
this[kPopulateParserHintArray]('array', keys);
301
>
this[kTrackManuallySetKeys](keys);
302
>
return this;
303
>
}
306
>
this[kPopulateParserHintArray]('boolean', keys);
307
>
this[kTrackManuallySetKeys](keys);
308
>
return this;
309
>
}
312
>
global?: boolean
313
>
): YargsInstance {
314
>
argsert('<function> [boolean]', [f, global], arguments.length);
315
>
this.middleware(
316
>
(
318
>
_yargs: YargsInstance
319
>
): Partial<Arguments> | Promise<Partial<Arguments>> => {
320
>
return maybeAsyncResult<
321
>
Partial<Arguments> | Promise<Partial<Arguments>> | any
322
>
>(
323
>
() => {
324
>
return f(argv, _yargs.getOptions());
325
>
},
326
>
(result: any): Partial<Arguments> | Promise<Partial<Arguments>> => {
329
>
this.#shim.y18n.__('Argument check failed: %s', f.toString())
330
>
);
333
>
}
336
>
(err: Error): Partial<Arguments> | Promise<Partial<Arguments>> => {
338
>
return argv;
339
>
}
342
>
false,
343
>
global
344
>
);
345
>
return this;
346
>
}
349
>
value?: string | string[]
350
>
): YargsInstance {
351
>
argsert(
352
>
'<object|string|array> [string|array]',
353
>
[key, value],
354
>
arguments.length
355
>
);
356
>
this[kPopulateParserHintArrayDictionary](
357
>
this.choices.bind(this),
358
>
'choices',
359
>
key,
360
>
value
361
>
);
362
>
return this;
363
>
}
366
>
value?: CoerceCallback
367
>
): YargsInstance {
368
>
argsert(
369
>
'<object|string|array> [function]',
370
>
[keys, value],
371
>
arguments.length
372
>
);
373
>
if (Array.isArray(keys)) {
376
>
}
378
>
this.coerce(key, value);
379
>
}
380
>
return this;
383
>
this.coerce(key, keys[key]);
384
>
}
385
>
return this;
386
>
}
389
>
}
391
>
// Handled multiple above, down to one key.
392
>
const coerceKey = keys;
393
>
// This noop tells yargs-parser about the existence of the option
394
>
// represented by "coerceKey", so that it can apply camel case expansion
395
>
// if needed:
396
>
this.#options.key[coerceKey] = true;
397
>
this.#globalMiddleware.addCoerceMiddleware(
398
>
(
400
>
yargs: YargsInstance
401
>
): Partial<Arguments> | Promise<Partial<Arguments>> => {
402
>
// Narrow down the possible keys to the ones present in argv.
403
>
const coerceKeyAliases = yargs.getAliases()[coerceKey] ?? [];
404
>
const argvKeys = [coerceKey, ...coerceKeyAliases].filter(key =>
405
>
Object.prototype.hasOwnProperty.call(argv, key)
406
>
);
407
>
408
>
// Skip coerce if nothing to coerce.
409
>
if (argvKeys.length === 0) {
411
>
}
413
>
return maybeAsyncResult<
414
>
Partial<Arguments> | Promise<Partial<Arguments>> | any
415
>
>(
416
>
() => {
417
>
return value(argv[argvKeys[0]]);
418
>
},
419
>
(result: any): Partial<Arguments> => {
421
>
argv[key] = result;
422
>
});
423
>
return argv;
425
>
(err: Error): Partial<Arguments> | Promise<Partial<Arguments>> => {
427
>
}
430
>
coerceKey
431
>
);
432
>
return this;
433
>
}
436
>
key2?: string | string[]
437
>
): YargsInstance {
438
>
argsert('<string|object> [string|array]', [key1, key2], arguments.length);
439
>
this.#validation.conflicts(key1, key2);
440
>
return this;
441
>
}
444
>
msg?: string | ConfigCallback,
445
>
parseFn?: ConfigCallback
446
>
): YargsInstance {
447
>
argsert(
448
>
'[object|string] [string|function] [function]',
449
>
[key, msg, parseFn],
450
>
arguments.length
451
>
);
452
>
// allow a config object to be provided directly.
453
>
if (typeof key === 'object' && !Array.isArray(key)) {
455
>
key,
456
>
this.#cwd,
457
>
this[kGetParserConfiguration]()['deep-merge-config'] || false,
458
>
this.#shim
459
>
);
460
>
this.#options.configObjects = (this.#options.configObjects || []).concat(
461
>
key
462
>
);
463
>
return this;
464
>
}
466
>
// allow for a custom parsing function.
467
>
if (typeof msg === 'function') {
469
>
msg = undefined;
470
>
}
472
>
this.describe(
473
>
key,
474
>
msg || this.#usage.deferY18nLookup('Path to JSON config file')
476
>
(Array.isArray(key) ? key : [key]).forEach(k => {
479
>
480
>
return this;
481
>
}
484
>
desc?: string | false | CompletionFunction,
485
>
fn?: CompletionFunction
486
>
): YargsInstance {
487
>
argsert(
488
>
'[string] [string|boolean|function] [function]',
489
>
[cmd, desc, fn],
490
>
arguments.length
491
>
);
492
>
493
>
// a function to execute when generating
494
>
// completions can be provided as the second
495
>
// or third argument to completion.
496
>
if (typeof desc === 'function') {
498
>
desc = undefined;
499
>
}
501
>
// register the completion command.
502
>
this.#completionCommand = cmd || this.#completionCommand || 'completion';
503
>
if (!desc && desc !== false) {
505
>
}
507
>
508
>
// a function can be provided
509
>
if (fn) this.#completion!.registerFunction(fn);
510
>
511
>
return this;
512
>
}
515
>
description?: CommandHandler['description'],
516
>
builder?: CommandBuilderDefinition | CommandBuilder,
517
>
handler?: CommandHandlerCallback,
518
>
middlewares?: Middleware[],
519
>
deprecated?: boolean
520
>
): YargsInstance {
521
>
argsert(
522
>
'<string|array|object> [string|boolean] [function|object] [function] [array] [boolean|string]',
523
>
[cmd, description, builder, handler, middlewares, deprecated],
524
>
arguments.length
525
>
);
526
>
this.#command.addHandler(
527
>
cmd,
528
>
description,
529
>
builder,
530
>
handler,
531
>
middlewares,
532
>
deprecated
533
>
);
534
>
return this;
535
>
}
538
>
description?: CommandHandler['description'],
539
>
builder?: CommandBuilderDefinition | CommandBuilder,
540
>
handler?: CommandHandlerCallback,
541
>
middlewares?: Middleware[],
542
>
deprecated?: boolean
543
>
): YargsInstance {
544
>
return this.command(
545
>
cmd,
546
>
description,
547
>
builder,
548
>
handler,
549
>
middlewares,
550
>
deprecated
551
>
);
552
>
}
553
>
commandDir(dir: string, opts?: RequireDirectoryOptions): YargsInstance {
yargs-factory.ts ×124
555
>
const req = this.#parentRequire || this.#shim.require;
556
>
this.#command.addDirectory(dir, req, this.#shim.getCallerFile(), opts);
557
>
return this;
558
>
}
561
>
this[kPopulateParserHintArray]('count', keys);
562
>
this[kTrackManuallySetKeys](keys);
563
>
return this;
564
>
}
567
>
value?: any,
568
>
defaultDescription?: string
569
>
): YargsInstance {
570
>
argsert(
571
>
'<object|string|array> [*] [string]',
572
>
[key, value, defaultDescription],
573
>
arguments.length
574
>
);
575
>
if (defaultDescription) {
577
>
this.#options.defaultDescription[key] = defaultDescription;
578
>
}
581
>
if (!this.#options.defaultDescription[key])
582
>
this.#options.defaultDescription[key] =
585
>
}
587
>
this.default.bind(this),
588
>
'default',
589
>
key,
590
>
value
591
>
);
592
>
return this;
593
>
}
596
>
value?: any,
597
>
defaultDescription?: string
598
>
): YargsInstance {
599
>
return this.default(key, value, defaultDescription);
600
>
}
603
>
max?: number | string,
604
>
minMsg?: string | null,
605
>
maxMsg?: string | null
606
>
): YargsInstance {
607
>
argsert(
608
>
'[number] [number|string] [string|null|undefined] [string|null|undefined]',
609
>
[min, max, minMsg, maxMsg],
610
>
arguments.length
611
>
);
612
>
613
>
if (typeof max !== 'number') {
615
>
max = Infinity;
616
>
}
618
>
this.global('_', false);
619
>
620
>
this.#options.demandedCommands._ = {
621
>
min,
622
>
max,
623
>
minMsg,
624
>
maxMsg,
625
>
};
626
>
627
>
return this;
628
>
}
631
>
max?: number | string[] | string | true,
632
>
msg?: string | true
633
>
): YargsInstance {
634
>
// you can optionally provide a 'max' key,
635
>
// which will raise an exception if too many '_'
636
>
// options are provided.
637
>
if (Array.isArray(max)) {
639
>
assertNotStrictEqual(msg, true as const, this.#shim);
640
>
this.demandOption(key, msg);
641
>
});
642
>
max = Infinity;
645
>
max = Infinity;
646
>
}
648
>
if (typeof keys === 'number') {
650
>
this.demandCommand(keys, max, msg, msg);
653
>
assertNotStrictEqual(msg, true as const, this.#shim);
654
>
this.demandOption(key, msg);
655
>
});
661
>
}
664
>
return this;
665
>
}
668
>
msg?: string
669
>
): YargsInstance {
670
>
argsert('<object|string|array> [string]', [keys, msg], arguments.length);
671
>
this[kPopulateParserHintSingleValueDictionary](
672
>
this.demandOption.bind(this),
673
>
'demandedOptions',
674
>
keys,
675
>
msg
676
>
);
677
>
return this;
678
>
}
679
>
deprecateOption(option: string, message: string | boolean): YargsInstance {
yargs-factory.ts ×124
681
>
this.#options.deprecatedOptions[option] = message;
682
>
return this;
683
>
}
686
>
description?: string
687
>
): YargsInstance {
688
>
argsert(
689
>
'<object|string|array> [string]',
690
>
[keys, description],
691
>
arguments.length
692
>
);
693
>
this[kSetKey](keys, true);
694
>
this.#usage.describe(keys, description);
695
>
return this;
696
>
}
699
>
this.#detectLocale = detect;
700
>
return this;
701
>
}
703
>
// parser will apply env vars matching prefix to argv
704
>
env(prefix?: string | false): YargsInstance {
706
>
if (prefix === false) delete this.#options.envPrefix;
709
>
}
712
>
this.#usage.epilog(msg);
713
>
return this;
714
>
}
717
>
}
720
>
description?: string
721
>
): YargsInstance {
722
>
argsert('<string|array> [string]', [cmd, description], arguments.length);
723
>
724
>
if (Array.isArray(cmd)) {
727
>
this.#usage.example(cmd, description);
728
>
}
729
>
730
>
return this;
731
>
}
733
>
exit(code: number, err?: YError | string): void {
735
>
this.#exitError = err;
736
>
if (this.#exitProcess) this.#shim.process.exit(code);
737
>
}
740
>
this.#exitProcess = enabled;
741
>
return this;
742
>
}
745
>
if (typeof f === 'boolean' && f !== false) {
747
>
"Invalid first argument. Expected function or boolean 'false'"
748
>
);
749
>
}
751
>
return this;
752
>
}
755
>
}
758
>
done?: (err: Error | null, completions: string[] | undefined) => void
759
>
): Promise<string[] | void> {
760
>
argsert('<array> [function]', [args, done], arguments.length);
761
>
if (!done) {
763
>
this.#completion!.getCompletion(args, (err, completions) => {
764
>
if (err) reject(err);
765
>
else resolve(completions);
766
>
});
767
>
});
770
>
}
774
>
return this.#options.demandedOptions;
775
>
}
778
>
return this.#options.demandedCommands;
779
>
}
782
>
return this.#options.deprecatedOptions;
783
>
}
786
>
}
789
>
}
790
>
// combine explicit and preserved groups. explicit groups should be first
yargs-factory.ts ×124
791
>
getGroups(): Dictionary<string[]> {
793
>
}
796
>
if (!this.#usage.hasCachedHelpMessage()) {
799
>
// the last parameter `true` indicates).
800
>
const parse = this[kRunYargsParserAndExecuteCommands](
801
>
this.#processArgs,
802
>
undefined,
803
>
undefined,
804
>
0,
805
>
true
806
>
);
807
>
if (isPromise(parse)) {
809
>
return this.#usage.help();
810
>
});
811
>
}
814
>
const builderResponse = this.#command.runDefaultBuilderOn(this);
815
>
if (isPromise(builderResponse)) {
817
>
return this.#usage.help();
818
>
});
819
>
}
822
>
}
825
>
}
828
>
}
831
>
}
834
>
}
837
>
globals = ([] as string[]).concat(globals);
838
>
if (global !== false) {
840
>
l => globals.indexOf(l) === -1
841
>
);
844
>
if (!this.#options.local.includes(g)) this.#options.local.push(g);
845
>
});
846
>
}
848
>
}
851
>
const existing =
852
>
this.#preservedGroups[groupName] || this.#groups[groupName];
853
>
if (this.#preservedGroups[groupName]) {
855
>
delete this.#preservedGroups[groupName];
856
>
}
858
>
this.#groups[groupName] = (existing || []).concat(opts).filter(key => {
859
>
if (seen[key]) return false;
860
>
return (seen[key] = true);
861
>
});
862
>
return this;
863
>
}
866
>
this.#options.hiddenOptions.push(key);
867
>
return this;
868
>
}
871
>
value?: KeyOrPos | KeyOrPos[]
872
>
): YargsInstance {
873
>
argsert(
874
>
'<string|object> [number|string|array]',
875
>
[key, value],
876
>
arguments.length
877
>
);
878
>
this.#validation.implies(key, value);
879
>
return this;
880
>
}
883
>
if (locale === undefined) {
885
>
return this.#shim.y18n.getLocale();
886
>
}
888
>
this.#shim.y18n.setLocale(locale);
889
>
return this;
890
>
}
893
>
applyBeforeValidation?: boolean,
894
>
global?: boolean
895
>
): YargsInstance {
896
>
return this.#globalMiddleware.addMiddleware(
897
>
callback,
898
>
!!applyBeforeValidation,
899
>
global
900
>
);
901
>
}
904
>
value?: number
905
>
): YargsInstance {
906
>
argsert('<string|object|array> [number]', [key, value], arguments.length);
907
>
this[kPopulateParserHintSingleValueDictionary](
908
>
this.nargs.bind(this),
909
>
'narg',
910
>
key,
911
>
value
912
>
);
913
>
return this;
914
>
}
917
>
this[kPopulateParserHintArray]('normalize', keys);
918
>
return this;
919
>
}
922
>
this[kPopulateParserHintArray]('number', keys);
923
>
this[kTrackManuallySetKeys](keys);
924
>
return this;
925
>
}
928
>
opt?: OptionDefinition
929
>
): YargsInstance {
930
>
argsert('<string|object> [object]', [key, opt], arguments.length);
931
>
if (typeof key === 'object') {
933
>
this.options(k, key[k]);
934
>
});
936
>
if (typeof opt !== 'object') {
938
>
}
940
>
this[kTrackManuallySetKeys](key);
941
>
942
>
// Warn about version name collision
943
>
// Addresses: https://github.com/yargs/yargs/issues/1979
944
>
if (this.#versionOpt && (key === 'version' || opt?.alias === 'version')) {
946
>
[
947
>
'"version" is a reserved word.',
948
>
'Please do one of the following:',
949
>
'- Disable version with `yargs.version(false)` if using "version" as an option',
950
>
'- Use the built-in `yargs.version` method instead (if applicable)',
951
>
'- Use a different option key',
952
>
'https://yargs.js.org/docs/#api-reference-version',
953
>
].join('\n'),
954
>
undefined,
955
>
'versionWarning' // TODO: better dedupeId
956
>
);
957
>
}
959
>
this.#options.key[key] = true; // track manually set keys.
960
>
961
>
if (opt.alias) this.alias(key, opt.alias);
962
>
963
>
const deprecate = opt.deprecate || opt.deprecated;
964
>
965
>
if (deprecate) {
967
>
}
969
>
const demand = opt.demand || opt.required || opt.require;
970
>
971
>
// A required option can be specified via "demand: true".
972
>
if (demand) {
974
>
}
976
>
if (opt.demandOption) {
978
>
key,
979
>
typeof opt.demandOption === 'string' ? opt.demandOption : undefined
980
>
);
981
>
}
983
>
if (opt.conflicts) {
985
>
}
987
>
if ('default' in opt) {
989
>
}
991
>
if (opt.implies !== undefined) {
993
>
}
995
>
if (opt.nargs !== undefined) {
997
>
}
999
>
if (opt.config) {
1001
>
}
1003
>
if (opt.normalize) {
1005
>
}
1007
>
if (opt.choices) {
1009
>
}
1011
>
if (opt.coerce) {
1013
>
}
1015
>
if (opt.group) {
1017
>
}
1019
>
if (opt.boolean || opt.type === 'boolean') {
1021
>
if (opt.alias) this.boolean(opt.alias);
1022
>
}
1024
>
if (opt.array || opt.type === 'array') {
1026
>
if (opt.alias) this.array(opt.alias);
1027
>
}
1029
>
if (opt.number || opt.type === 'number') {
1031
>
if (opt.alias) this.number(opt.alias);
1032
>
}
1034
>
if (opt.string || opt.type === 'string') {
1036
>
if (opt.alias) this.string(opt.alias);
1037
>
}
1039
>
if (opt.count || opt.type === 'count') {
1041
>
}
1043
>
if (typeof opt.global === 'boolean') {
1045
>
}
1047
>
if (opt.defaultDescription) {
1049
>
}
1051
>
if (opt.skipValidation) {
1053
>
}
1055
>
const desc = opt.describe || opt.description || opt.desc;
1056
>
const descriptions = this.#usage.getDescriptions();
1057
>
if (
1058
>
!Object.prototype.hasOwnProperty.call(descriptions, key) ||
1062
>
}
1064
>
if (opt.hidden) {
1066
>
}
1068
>
if (opt.requiresArg) {
1070
>
}
1072
>
1073
>
return this;
1074
>
}
1077
>
opt?: OptionDefinition
1078
>
): YargsInstance {
1079
>
return this.option(key, opt);
1080
>
}
1083
>
shortCircuit?: object | ParseCallback | boolean,
1084
>
_parseFn?: ParseCallback
1085
>
): Arguments | Promise<Arguments> {
1086
>
argsert(
1087
>
'[string|array] [function|boolean|object] [function]',
1088
>
[args, shortCircuit, _parseFn],
1089
>
arguments.length
1090
>
);
1091
>
this[kFreeze](); // Push current state of parser onto stack.
1092
>
if (typeof args === 'undefined') {
1094
>
}
1096
>
// a context object can optionally be provided, this allows
1097
>
// additional information to be passed to a command handler.
1098
>
if (typeof shortCircuit === 'object') {
1100
>
shortCircuit = _parseFn;
1101
>
}
1103
>
// by providing a function as a second argument to
1104
>
// parse you can capture output that would otherwise
1105
>
// default to printing to stdout/stderr.
1106
>
if (typeof shortCircuit === 'function') {
1108
>
shortCircuit = false;
1109
>
}
1111
>
// skipping validation, etc.
1112
>
if (!shortCircuit) this.#processArgs = args;
1113
>
1114
>
if (this.#parseFn) this.#exitProcess = false;
1115
>
1116
>
const parsed = this[kRunYargsParserAndExecuteCommands](
1117
>
args,
1118
>
!!shortCircuit
1119
>
);
1120
>
const tmpParsed = this.parsed;
1121
>
this.#completion!.setParsed(this.parsed as DetailedArguments);
1122
>
if (isPromise(parsed)) {
1124
>
.then(argv => {
1126
>
return argv;
1128
>
.catch(err => {
1131
>
err,
1132
>
(this.parsed as DetailedArguments).argv,
1133
>
this.#output
1134
>
);
1135
>
}
1138
>
.finally(() => {
1139
>
this[kUnfreeze](); // Pop the stack.
1140
>
this.parsed = tmpParsed;
1141
>
});
1144
>
this[kUnfreeze](); // Pop the stack.
1145
>
this.parsed = tmpParsed;
1146
>
}
1147
>
return parsed;
1148
>
}
1151
>
shortCircuit?: object | ParseCallback | boolean,
1152
>
_parseFn?: ParseCallback
1153
>
): Promise<Arguments> {
1154
>
const maybePromise = this.parse(args, shortCircuit, _parseFn);
1155
>
return !isPromise(maybePromise)
1156
>
? Promise.resolve(maybePromise)
1157
>
: maybePromise;
1158
>
}
1161
>
shortCircuit?: object | ParseCallback | boolean,
1162
>
_parseFn?: ParseCallback
1163
>
): Arguments {
1164
>
const maybePromise = this.parse(args, shortCircuit, _parseFn);
1165
>
if (isPromise(maybePromise)) {
1167
>
'.parseSync() must not be used with asynchronous builders, handlers, or middleware'
1168
>
);
1169
>
}
1171
>
}
1174
>
this.#parserConfig = config;
1175
>
return this;
1176
>
}
1179
>
let conf = null;
1180
>
// prefer cwd to require-main-filename in this method
1181
>
// since we're looking for e.g. "nyc" config in nyc consumer
1182
>
// rather than "yargs" config in nyc (where nyc is the main filename)
1183
>
const obj = this[kPkgUp](rootPath || this.#cwd);
1184
>
1185
>
// If an object exists in the key, add it to options.configObjects
1186
>
if (obj[key] && typeof obj[key] === 'object') {
1188
>
obj[key] as {[key: string]: string},
1189
>
rootPath || this.#cwd,
1190
>
this[kGetParserConfiguration]()['deep-merge-config'] || false,
1191
>
this.#shim
1192
>
);
1193
>
this.#options.configObjects = (this.#options.configObjects || []).concat(
1194
>
conf
1195
>
);
1196
>
}
1198
>
}
1201
>
// .positional() only supports a subset of the configuration
1202
>
// options available to .option():
1203
>
const supportedOpts: (keyof PositionalDefinition)[] = [
1204
>
'default',
1205
>
'defaultDescription',
1206
>
'implies',
1207
>
'normalize',
1208
>
'choices',
1209
>
'conflicts',
1210
>
'coerce',
1211
>
'type',
1212
>
'describe',
1213
>
'desc',
1214
>
'description',
1215
>
'alias',
1216
>
];
1217
>
opts = objFilter(opts, (k, v) => {
1219
>
if (k === 'type' && !['string', 'number', 'boolean'].includes(v))
1220
>
return false;
1221
>
return supportedOpts.includes(k);
1223
>
1224
>
// copy over any settings that can be inferred from the command string.
1225
>
const fullCommand =
1226
>
this.#context.fullCommands[this.#context.fullCommands.length - 1];
1227
>
const parseOptions = fullCommand
1228
>
? this.#command.cmdToParseOptions(fullCommand)
1229
>
: {
1231
>
alias: {},
1232
>
default: {},
1233
>
demand: {},
1234
>
};
1236
>
const parseOption = parseOptions[pk];
1237
>
if (Array.isArray(parseOption)) {
1238
>
if (parseOption.indexOf(key) !== -1) opts[pk] = true;
1239
>
} else {
1240
>
if (parseOption[key] && !(pk in opts)) opts[pk] = parseOption[key];
1241
>
}
1242
>
});
1243
>
this.group(key, this.#usage.getPositionalGroupName());
1244
>
return this.option(key, opts);
1245
>
}
1248
>
this.#recommendCommands = recommend;
1249
>
return this;
1250
>
}
1253
>
max?: number | string[] | string | true,
1254
>
msg?: string | true
1255
>
): YargsInstance {
1256
>
return this.demand(keys, max, msg);
1257
>
}
1260
>
max?: number | string[] | string | true,
1261
>
msg?: string | true
1262
>
): YargsInstance {
1263
>
return this.demand(keys, max, msg);
1264
>
}
1267
>
// as populateParserHintSingleValueDictionary recursively calls requiresArg
1268
>
// with Nan as a 2nd parameter, although we ignore it
1269
>
argsert('<array|string|object> [number]', [keys], arguments.length);
1270
>
// If someone configures nargs at the same time as requiresArg,
1271
>
// nargs should take precedence,
1272
>
// see: https://github.com/yargs/yargs/pull/1572
1273
>
// TODO: make this work with aliases, using a check similar to
1274
>
// checkAllAliases() in yargs-parser.
1275
>
if (typeof keys === 'string' && this.#options.narg[keys]) {
1279
>
this.requiresArg.bind(this),
1280
>
'narg',
1281
>
keys,
1282
>
NaN
1283
>
);
1284
>
}
1285
>
return this;
1286
>
}
1289
>
$0 = $0 || this.$0;
1290
>
this.#logger.log(
1291
>
this.#completion!.generateCompletionScript(
1292
>
$0,
1293
>
cmd || this.#completionCommand || 'completion'
1294
>
)
1295
>
);
1296
>
return this;
1297
>
}
1300
>
): YargsInstance {
1301
>
argsert('[string|function]', [level], arguments.length);
1302
>
this.#hasOutput = true;
1303
>
if (!this.#usage.hasCachedHelpMessage()) {
1306
>
// the last parameter `true` indicates).
1307
>
const parse = this[kRunYargsParserAndExecuteCommands](
1308
>
this.#processArgs,
1309
>
undefined,
1310
>
undefined,
1311
>
0,
1312
>
true
1313
>
);
1314
>
if (isPromise(parse)) {
1316
>
this.#usage.showHelp(level);
1317
>
});
1318
>
return this;
1319
>
}
1322
>
const builderResponse = this.#command.runDefaultBuilderOn(this);
1323
>
if (isPromise(builderResponse)) {
1325
>
this.#usage.showHelp(level);
1326
>
});
1327
>
return this;
1328
>
}
1331
>
return this;
1332
>
}
1335
>
this.$0 = scriptName;
1336
>
return this;
1337
>
}
1338
>
showHelpOnFail(enabled?: string | boolean, message?: string): YargsInstance {
yargs-factory.ts ×124
1340
>
this.#usage.showHelpOnFail(enabled, message);
1341
>
return this;
1342
>
}
1345
>
): YargsInstance {
1346
>
argsert('[string|function]', [level], arguments.length);
1347
>
this.#usage.showVersion(level);
1348
>
return this;
1349
>
}
1352
>
this[kPopulateParserHintArray]('skipValidation', keys);
1353
>
return this;
1354
>
}
1357
>
this.#strict = enabled !== false;
1358
>
return this;
1359
>
}
1362
>
this.#strictCommands = enabled !== false;
1363
>
return this;
1364
>
}
1367
>
this.#strictOptions = enabled !== false;
1368
>
return this;
1369
>
}
1372
>
this[kPopulateParserHintArray]('string', keys);
1373
>
this[kTrackManuallySetKeys](keys);
1374
>
return this;
1375
>
}
1378
>
return this.#shim.process.stdColumns;
1379
>
}
1382
>
}
1385
>
this.#detectLocale = false;
1386
>
this.#shim.y18n.updateLocale(obj);
1387
>
return this;
1388
>
}
1391
>
description?: CommandHandler['description'],
1392
>
builder?: CommandBuilderDefinition | CommandBuilder,
1393
>
handler?: CommandHandlerCallback
1394
>
): YargsInstance {
1395
>
argsert(
1396
>
'<string|null|undefined> [string|boolean] [function|object] [function]',
1397
>
[msg, description, builder, handler],
1398
>
arguments.length
1399
>
);
1400
>
1401
>
if (description !== undefined) {
1403
>
// .usage() can be used as an alias for defining
1404
>
// a default command.
1405
>
if ((msg || '').match(/^\$0( |$)/)) {
1409
>
'.usage() description must start with $0 if being used as alias for .command()'
1410
>
);
1411
>
}
1414
>
return this;
1415
>
}
1419
>
this.#usageConfig = config;
1420
>
return this;
1421
>
}
1422
>
version(opt?: string | false, msg?: string, ver?: string): YargsInstance {
yargs-factory.ts ×124
1424
>
argsert(
1425
>
'[boolean|string] [string] [string]',
1426
>
[opt, msg, ver],
1427
>
arguments.length
1428
>
);
1429
>
1430
>
// nuke the key previously configured
1431
>
// to return version #.
1432
>
if (this.#versionOpt) {
1434
>
this.#usage.version(undefined);
1435
>
this.#versionOpt = null;
1436
>
}
1438
>
if (arguments.length === 0) {
1439
>
ver = this[kGuessVersion]();
1440
>
opt = defaultVersionOpt;
1441
>
} else if (arguments.length === 1) {
1444
>
return this;
1445
>
}
1447
>
opt = defaultVersionOpt;
1450
>
msg = undefined;
1451
>
}
1453
>
this.#versionOpt = typeof opt === 'string' ? opt : defaultVersionOpt;
1454
>
msg = msg || this.#usage.deferY18nLookup('Show version number');
1455
>
1456
>
this.#usage.version(ver || undefined);
1457
>
this.boolean(this.#versionOpt);
1458
>
this.describe(this.#versionOpt, msg);
1459
>
return this;
1460
>
}
1463
>
this.#usage.wrap(cols);
1464
>
return this;
1465
>
}
1467
>
// to simplify the parsing of positionals in commands,
1468
>
// we temporarily populate '--' rather than _, with arguments
1469
>
// after the '--' directive. After the parse, we copy these back.
1470
>
[kCopyDoubleDash](argv: Arguments): any {
1473
>
argv._.push.apply(argv._, argv['--']);
1474
>
1475
>
// We catch an error here, in case someone has called Object.seal()
1476
>
// on the parsed object, see: https://github.com/babel/babel/pull/10733
1477
>
try {
1478
>
delete argv['--'];
1479
>
// eslint-disable-next-line no-empty
1480
>
} catch (_err) {}
1481
>
1482
>
return argv;
1483
>
}
1486
>
log: (...args: any[]) => {
1488
>
this.#hasOutput = true;
1489
>
if (this.#output.length) this.#output += '\n';
1490
>
this.#output += args.join(' ');
1492
>
error: (...args: any[]) => {
1494
>
this.#hasOutput = true;
1495
>
if (this.#output.length) this.#output += '\n';
1496
>
this.#output += args.join(' ');
1498
>
};
1499
>
}
1502
>
// boolean, array, key, alias, etc.
1503
>
objectKeys(this.#options).forEach((hintKey: keyof Options) => {
1504
>
// configObjects is not a parsing hint array
1505
>
if (((key): key is 'configObjects' => key === 'configObjects')(hintKey))
1506
>
return;
1507
>
const hint = this.#options[hintKey];
1508
>
if (Array.isArray(hint)) {
1509
>
if (hint.includes(optionKey)) hint.splice(hint.indexOf(optionKey), 1);
1510
>
} else if (typeof hint === 'object') {
1511
>
delete (hint as Dictionary)[optionKey];
1512
>
}
1513
>
});
1514
>
// now delete the description from usage.js.
1515
>
delete this.#usage.getDescriptions()[optionKey];
1516
>
}
1519
>
type: string | undefined,
1520
>
deduplicationId: string
1521
>
) {
1522
>
// prevent duplicate warning emissions
1523
>
if (!this.#emittedWarnings[deduplicationId]) {
1524
>
this.#shim.process.emitWarning(warning, type);
1525
>
this.#emittedWarnings[deduplicationId] = true;
1526
>
}
1527
>
}
1530
>
options: this.#options,
1531
>
configObjects: this.#options.configObjects.slice(0),
1532
>
exitProcess: this.#exitProcess,
1533
>
groups: this.#groups,
1534
>
strict: this.#strict,
1535
>
strictCommands: this.#strictCommands,
1536
>
strictOptions: this.#strictOptions,
1537
>
completionCommand: this.#completionCommand,
1538
>
output: this.#output,
1539
>
exitError: this.#exitError!,
1540
>
hasOutput: this.#hasOutput,
1541
>
parsed: this.parsed,
1542
>
parseFn: this.#parseFn!,
1543
>
parseContext: this.#parseContext,
1544
>
});
1545
>
this.#usage.freeze();
1546
>
this.#validation.freeze();
1547
>
this.#command.freeze();
1548
>
this.#globalMiddleware.freeze();
1549
>
}
1552
>
// ignore the node bin, specify this in your
1553
>
// bin file with #!/usr/bin/env node
1554
>
let default$0: string[];
1555
>
if (
1556
>
/\b(node|iojs|electron|bun)(\.exe)?$/.test(this.#shim.process.argv()[0])
1557
>
) {
1561
>
}
1563
>
$0 = default$0
1564
>
.map(x => {
1565
>
const b = this[kRebase](this.#cwd, x);
1566
>
return x.match(/^(\/|([a-zA-Z]:)?\\)/) && b.length < x.length ? b : x;
1567
>
})
1568
>
.join(' ')
1569
>
.trim();
1570
>
1571
>
if (
1572
>
this.#shim.getEnv('_') &&
1573
>
this.#shim.getProcessArgvBin() === this.#shim.getEnv('_')
1574
>
) {
1576
>
.getEnv('_')!
1577
>
.replace(
1578
>
`${this.#shim.path.dirname(this.#shim.process.execPath())}/`,
1579
>
''
1580
>
);
1581
>
}
1583
>
}
1586
>
}
1589
>
}
1593
>
this.#shim.getEnv('LC_ALL') ||
1595
>
this.#shim.getEnv('LANG') ||
1596
>
this.#shim.getEnv('LANGUAGE') ||
1597
>
'en_US';
1598
>
this.locale(locale.replace(/[.:].*/, ''));
1599
>
}
1602
>
return (obj.version as string) || 'unknown';
1603
>
}
1604
>
// We wait to coerce numbers for positionals until after the initial parse.
yargs-factory.ts ×124
1605
>
// This allows commands to configure number parsing on a positional by
1606
>
// positional basis:
1607
>
[kParsePositionalNumbers](argv: Arguments): any {
1609
>
1610
>
for (let i = 0, arg; (arg = args[i]) !== undefined; i++) {
1612
>
this.#shim.Parser.looksLikeNumber(arg) &&
1616
>
}
1619
>
}
1622
>
if (this.#pkgs[npath]) return this.#pkgs[npath];
1623
>
1624
>
let obj = {};
1625
>
try {
1626
>
let startDir = rootPath || this.#shim.mainFilename;
1627
>
// If a file path is provided for root, remove the file and keep path.
1628
>
if (this.#shim.path.extname(startDir)) {
1630
>
}
1632
>
const pkgJsonPath = this.#shim.findUp(
1633
>
startDir,
1634
>
(dir: string[], names: string[]) => {
1635
>
if (names.includes('package.json')) {
1636
>
return 'package.json';
1637
>
} else {
1639
>
}
1641
>
);
1642
>
assertNotStrictEqual(pkgJsonPath, undefined, this.#shim);
1643
>
obj = JSON.parse(this.#shim.readFileSync(pkgJsonPath, 'utf8'));
1644
>
// eslint-disable-next-line no-empty
1645
>
} catch (_noop) {}
1646
>
1647
>
this.#pkgs[npath] = obj || {};
1648
>
return this.#pkgs[npath];
1649
>
}
1652
>
keys: string | string[]
1653
>
) {
1654
>
keys = ([] as string[]).concat(keys);
1655
>
keys.forEach(key => {
1656
>
key = this[kSanitizeKey](key);
1657
>
this.#options[type].push(key);
1658
>
});
1659
>
}
1662
>
| Exclude<DictionaryKeyof<Options>, DictionaryKeyof<Options, any[]>>
1663
>
| 'default',
1664
>
K extends keyof Options[T] & string = keyof Options[T] & string,
1665
>
V extends ValueOf<Options[T]> = ValueOf<Options[T]>,
1666
>
>(
1667
>
builder: (key: K, value: V, ...otherArgs: any[]) => YargsInstance,
1668
>
type: T,
1669
>
key: K | K[] | {[key in K]: V | undefined},
1670
>
value?: V
1671
>
) {
1672
>
this[kPopulateParserHintDictionary]<T, K, V>(
1673
>
builder,
1674
>
type,
1675
>
key,
1676
>
value,
1677
>
(type, key, value) => {
1678
>
this.#options[type][key] = value as ValueOf<Options[T]>;
1679
>
}
1680
>
);
1681
>
}
1684
>
K extends keyof Options[T] & string = keyof Options[T] & string,
1685
>
V extends ValueOf<ValueOf<Options[T]>> | ValueOf<ValueOf<Options[T]>>[] =
1686
>
ValueOf<ValueOf<Options[T]>> | ValueOf<ValueOf<Options[T]>>[],
1687
>
>(
1688
>
builder: (key: K, value: V, ...otherArgs: any[]) => YargsInstance,
1689
>
type: T,
1690
>
key: K | K[] | {[key in K]: V},
1691
>
value?: V
1692
>
) {
1693
>
this[kPopulateParserHintDictionary]<T, K, V>(
1694
>
builder,
1695
>
type,
1696
>
key,
1697
>
value,
1698
>
(type, key, value) => {
1699
>
this.#options[type][key] = (
1700
>
this.#options[type][key] || ([] as Options[T][keyof Options[T]])
1701
>
).concat(value);
1702
>
}
1703
>
);
1704
>
}
1707
>
K extends keyof Options[T],
1708
>
V,
1709
>
>(
1710
>
builder: (key: K, value: V, ...otherArgs: any[]) => YargsInstance,
1711
>
type: T,
1712
>
key: K | K[] | {[key in K]: V | undefined},
1713
>
value: V | undefined,
1714
>
singleKeyHandler: (type: T, key: K, value?: V) => void
1715
>
) {
1716
>
if (Array.isArray(key)) {
1718
>
key.forEach(k => {
1719
>
builder(k, value!);
1720
>
});
1722
>
((key): key is {[key in K]: V} => typeof key === 'object')(key)
1723
>
) {
1725
>
for (const k of objectKeys(key)) {
1726
>
builder(k, key[k]);
1727
>
}
1729
>
singleKeyHandler(type, this[kSanitizeKey](key), value);
1730
>
}
1731
>
}
1734
>
return key;
1735
>
}
1738
>
set?: boolean | string
1739
>
) {
1740
>
this[kPopulateParserHintSingleValueDictionary](
1741
>
this[kSetKey].bind(this),
1742
>
'key',
1743
>
key,
1744
>
set
1745
>
);
1746
>
return this;
1747
>
}
1750
>
assertNotStrictEqual(frozen, undefined, this.#shim);
1751
>
let configObjects: Dictionary[];
1752
>
({
1753
>
options: this.#options,
1754
>
configObjects,
1755
>
exitProcess: this.#exitProcess,
1756
>
groups: this.#groups,
1757
>
output: this.#output,
1758
>
exitError: this.#exitError,
1759
>
hasOutput: this.#hasOutput,
1760
>
parsed: this.parsed,
1761
>
strict: this.#strict,
1762
>
strictCommands: this.#strictCommands,
1763
>
strictOptions: this.#strictOptions,
1764
>
completionCommand: this.#completionCommand,
1765
>
parseFn: this.#parseFn,
1766
>
parseContext: this.#parseContext,
1767
>
} = frozen);
1768
>
this.#options.configObjects = configObjects;
1769
>
this.#usage.unfreeze();
1770
>
this.#validation.unfreeze();
1771
>
this.#command.unfreeze();
1772
>
this.#globalMiddleware.unfreeze();
1773
>
}
1774
>
// If argv is a promise (which is possible if async middleware is used)
yargs-factory.ts ×124
1775
>
// delay applying validation until the promise has resolved:
1776
>
[kValidateAsync](
1778
>
argv: Arguments | Promise<Arguments>
1779
>
): Arguments | Promise<Arguments> {
1780
>
return maybeAsyncResult<Arguments>(argv, result => {
1781
>
validation(result);
1782
>
return result;
1783
>
});
1784
>
}
1786
>
// Note: these method names could change at any time, and should not be
1787
>
// depended upon externally:
1788
>
getInternalMethods(): YargsInternalMethods {
1790
>
getCommandInstance: this[kGetCommandInstance].bind(this),
1791
>
getContext: this[kGetContext].bind(this),
1792
>
getHasOutput: this[kGetHasOutput].bind(this),
1793
>
getLoggerInstance: this[kGetLoggerInstance].bind(this),
1794
>
getParseContext: this[kGetParseContext].bind(this),
1795
>
getParserConfiguration: this[kGetParserConfiguration].bind(this),
1796
>
getUsageConfiguration: this[kGetUsageConfiguration].bind(this),
1797
>
getUsageInstance: this[kGetUsageInstance].bind(this),
1798
>
getValidationInstance: this[kGetValidationInstance].bind(this),
1799
>
hasParseCallback: this[kHasParseCallback].bind(this),
1800
>
isGlobalContext: this[kIsGlobalContext].bind(this),
1801
>
postProcess: this[kPostProcess].bind(this),
1802
>
reset: this[kReset].bind(this),
1803
>
runValidation: this[kRunValidation].bind(this),
1804
>
runYargsParserAndExecuteCommands:
1805
>
this[kRunYargsParserAndExecuteCommands].bind(this),
1806
>
setHasOutput: this[kSetHasOutput].bind(this),
1807
>
};
1808
>
}
1811
>
}
1814
>
}
1817
>
}
1820
>
}
1823
>
}
1826
>
}
1829
>
}
1832
>
}
1835
>
}
1838
>
populateDoubleDash: boolean,
1839
>
calledFromCommand: boolean,
1840
>
runGlobalMiddleware: boolean
1841
>
): any {
1842
>
if (calledFromCommand) return argv;
1846
>
}
1848
>
this[kGetParserConfiguration]()['parse-positional-numbers'] ||
1849
>
this[kGetParserConfiguration]()['parse-positional-numbers'] === undefined;
yargs-factory.ts ×2
1850
>
if (parsePositionalNumbers) {
1852
>
}
1853
>
if (runGlobalMiddleware) {
1855
>
argv,
1856
>
this,
1857
>
this.#globalMiddleware.getMiddleware(),
1858
>
false
1859
>
);
1860
>
}
1862
>
}
1863
>
// put yargs back into an initial state; this is used mainly for running
yargs-factory.ts ×124
1864
>
// commands in a breadth first manner:
1865
>
[kReset](aliases: Aliases = {}): YargsInstance {
1867
>
const tmpOptions = {} as Options;
1868
>
tmpOptions.local = this.#options.local || [];
1869
>
tmpOptions.configObjects = this.#options.configObjects || [];
1870
>
1871
>
// if a key has been explicitly set as local,
1872
>
// we should reset it before passing options to command.
1873
>
const localLookup: Dictionary<boolean> = {};
1874
>
tmpOptions.local.forEach(l => {
1876
>
(aliases[l] || []).forEach(a => {
1880
>
1881
>
// add all groups not set to local to preserved groups
1882
>
Object.assign(
1883
>
this.#preservedGroups,
1884
>
Object.keys(this.#groups).reduce(
1885
>
(acc, groupName) => {
1887
>
key => !(key in localLookup)
1888
>
);
1889
>
if (keys.length > 0) {
1891
>
}
1894
>
{} as Dictionary<string[]>
1895
>
)
1896
>
);
1897
>
// groups can now be reset
1898
>
this.#groups = {};
1899
>
1900
>
const arrayOptions: KeyOf<Options, string[]>[] = [
1901
>
'array',
1902
>
'boolean',
1903
>
'string',
1904
>
'skipValidation',
1905
>
'count',
1906
>
'normalize',
1907
>
'number',
1908
>
'hiddenOptions',
1909
>
];
1910
>
1911
>
const objectOptions: DictionaryKeyof<Options>[] = [
1912
>
'narg',
1913
>
'key',
1914
>
'alias',
1915
>
'default',
1916
>
'defaultDescription',
1917
>
'config',
1918
>
'choices',
1919
>
'demandedOptions',
1920
>
'demandedCommands',
1921
>
'deprecatedOptions',
1922
>
];
1923
>
1924
>
arrayOptions.forEach(k => {
1925
>
tmpOptions[k] = (this.#options[k] || []).filter(
1926
>
(k: string) => !localLookup[k]
1927
>
);
1928
>
});
1929
>
1930
>
objectOptions.forEach(<K extends DictionaryKeyof<Options>>(k: K) => {
1931
>
tmpOptions[k] = objFilter(
1932
>
this.#options[k],
1933
>
k => !localLookup[k as string]
1934
>
);
1935
>
});
1936
>
1937
>
tmpOptions.envPrefix = this.#options.envPrefix;
1938
>
this.#options = tmpOptions;
1939
>
1940
>
// if this is the first time being executed, create
1941
>
// instances of all our helpers -- otherwise just reset.
1942
>
this.#usage = this.#usage
1943
>
? this.#usage.reset(localLookup)
1944
>
: Usage(this, this.#shim);
1945
>
this.#validation = this.#validation
1946
>
? this.#validation.reset(localLookup)
1947
>
: Validation(this, this.#usage, this.#shim);
1948
>
this.#command = this.#command
1949
>
? this.#command.reset()
1950
>
: Command(
1951
>
this.#usage,
1952
>
this.#validation,
1953
>
this.#globalMiddleware,
1954
>
this.#shim
1955
>
);
1956
>
if (!this.#completion)
1957
>
this.#completion = Completion(
1958
>
this,
1959
>
this.#usage,
1960
>
this.#command,
1961
>
this.#shim
1962
>
);
1963
>
this.#globalMiddleware.reset();
1964
>
1965
>
this.#completionCommand = null;
1966
>
this.#output = '';
1967
>
this.#exitError = null;
1968
>
this.#hasOutput = false;
1969
>
this.parsed = false;
1970
>
1971
>
return this;
1972
>
}
1975
>
}
1978
>
shortCircuit?: boolean | null,
1979
>
calledFromCommand?: boolean,
1980
>
commandIndex = 0,
1981
>
helpOnly = false
1982
>
): Arguments | Promise<Arguments> {
1983
>
let skipValidation = !!calledFromCommand || helpOnly;
1984
>
args = args || this.#processArgs;
1985
>
1986
>
this.#options.__ = this.#shim.y18n.__;
1987
>
this.#options.configuration = this[kGetParserConfiguration]();
1988
>
1989
>
const populateDoubleDash = !!this.#options.configuration['populate--'];
1990
>
const config = Object.assign({}, this.#options.configuration, {
1991
>
'populate--': true,
1992
>
});
1993
>
const parsed = this.#shim.Parser.detailed(
1994
>
args,
1995
>
Object.assign({}, this.#options, {
1996
>
configuration: {'parse-positional-numbers': false, ...config},
1997
>
})
1998
>
) as DetailedArguments;
1999
>
2000
>
const argv: Arguments = Object.assign(
2001
>
parsed.argv,
2002
>
this.#parseContext
2003
>
) as Arguments;
2004
>
let argvPromise: Arguments | Promise<Arguments> | undefined = undefined;
2005
>
const aliases = parsed.aliases;
2006
>
2007
>
let helpOptSet = false;
2008
>
let versionOptSet = false;
2009
>
Object.keys(argv).forEach(key => {
2010
>
if (key === this.#helpOpt && argv[key]) {
2014
>
}
2016
>
2017
>
argv.$0 = this.$0;
2018
>
this.parsed = parsed;
2019
>
2020
>
// A single yargs instance may be used multiple times, e.g.
2021
>
// const y = yargs(); y.parse('foo --bar'); yargs.parse('bar --foo').
2022
>
// When a prior parse has completed and a new parse is beginning, we
2023
>
// need to clear the cached help message from the previous parse:
2024
>
if (commandIndex === 0) {
2025
>
this.#usage.clearCachedHelpMessage();
2026
>
}
2027
>
2028
>
try {
2029
>
this[kGuessLocale](); // guess locale lazily, so that it can be turned off in chain.
2030
>
2031
>
// while building up the argv object, there
2032
>
// are two passes through the parser. If completion
2033
>
// is being performed short-circuit on the first pass.
2034
>
if (shortCircuit) {
2036
>
argv,
2037
>
populateDoubleDash,
2038
>
!!calledFromCommand,
2039
>
false // Don't run middleware when figuring out completion.
2040
>
);
2041
>
}
2043
>
// if there's a handler associated with a
2044
>
// command defer processing to it.
2045
>
if (this.#helpOpt) {
2047
>
// unless all helpOpt aliases are single-char
2048
>
// note that parsed.aliases is a normalized bidirectional map :)
2049
>
const helpCmds = [this.#helpOpt]
2050
>
.concat(aliases[this.#helpOpt] || [])
2051
>
.filter(k => k.length > 1);
2052
>
// check if help should trigger and strip it from _.
2053
>
if (helpCmds.includes('' + argv._[argv._.length - 1])) {
2055
>
helpOptSet = true;
2056
>
}
2059
>
this.#isGlobalContext = false;
2060
>
2061
>
const handlerKeys = this.#command.getCommands();
2062
>
2064
>
? [
2066
>
...(this.getAliases()[this.#completion?.completionKey] ?? []),
2067
>
].some((key: string) =>
2068
>
Object.prototype.hasOwnProperty.call(argv, key)
2070
>
: false;
2071
>
2072
>
const skipRecommendation = helpOptSet || requestCompletions || helpOnly;
2073
>
if (argv._.length) {
2076
>
for (let i = commandIndex || 0, cmd; argv._[i] !== undefined; i++) {
2077
>
cmd = String(argv._[i]);
2078
>
if (handlerKeys.includes(cmd) && cmd !== this.#completionCommand) {
2080
>
// the deepest command first; we keep track of the position in the
2081
>
// argv._ array that is currently being executed.
2082
>
const innerArgv = this.#command.runCommand(
2083
>
cmd,
2084
>
this,
2085
>
parsed,
2086
>
i + 1,
2087
>
// Don't run a handler, just figure out the help string:
2088
>
helpOnly,
2089
>
// Passed to builder so that expensive commands can be deferred:
2090
>
helpOptSet || versionOptSet || helpOnly
2091
>
);
2092
>
return this[kPostProcess](
2093
>
innerArgv,
2094
>
populateDoubleDash,
2095
>
!!calledFromCommand,
2096
>
false
2097
>
);
2100
>
cmd !== this.#completionCommand
2101
>
) {
2103
>
break;
2104
>
}
2107
>
// been enabled, and no commands were found to execute
2108
>
if (
2109
>
!this.#command.hasDefaultCommand() &&
2111
>
firstUnknownCommand &&
2115
>
firstUnknownCommand,
2116
>
handlerKeys
2117
>
);
2118
>
}
2121
>
// generate a completion script for adding to ~/.bashrc.
2122
>
if (
2123
>
this.#completionCommand &&
2124
>
argv._.includes(this.#completionCommand) &&
2128
>
this.showCompletionScript();
2129
>
this.exit(0);
2130
>
}
2135
>
null,
2136
>
this,
2137
>
parsed,
2138
>
0,
2139
>
helpOnly,
2140
>
helpOptSet || versionOptSet || helpOnly
2141
>
);
2142
>
return this[kPostProcess](
2143
>
innerArgv,
2144
>
populateDoubleDash,
2145
>
!!calledFromCommand,
2146
>
false
2147
>
);
2148
>
}
2150
>
// we must run completions first, a user might
2151
>
// want to complete the --help or --version option.
2152
>
if (requestCompletions) {
2154
>
2155
>
// we allow for asynchronous completions,
2156
>
// e.g., loading in a list of commands from an API.
2157
>
args = ([] as string[]).concat(args);
2158
>
const completionArgs = args.slice(
2159
>
args.indexOf(`--${this.#completion!.completionKey}`) + 1
2160
>
);
2161
>
this.#completion!.getCompletion(completionArgs, (err, completions) => {
2162
>
if (err) throw new YError(err.message);
2163
>
(completions || []).forEach(completion => {
2166
>
this.exit(0);
2167
>
});
2168
>
return this[kPostProcess](
2169
>
argv,
2170
>
!populateDoubleDash,
2171
>
!!calledFromCommand,
2172
>
false // Don't run middleware when figuring out completion.
2173
>
);
2174
>
}
2176
>
// Handle 'help' and 'version' options
2177
>
// if we haven't already output help!
2178
>
if (!this.#hasOutput) {
2181
>
skipValidation = true;
2182
>
this.showHelp(message => {
2183
>
this.#logger.log(message);
2184
>
this.exit(0);
2185
>
});
2188
>
skipValidation = true;
2189
>
this.#usage.showVersion('log');
2190
>
this.exit(0);
2191
>
}
2194
>
// Check if any of the options to skip validation were provided
2197
>
key =>
2198
>
this.#options.skipValidation.indexOf(key) >= 0 && argv[key] === true
2199
>
);
2200
>
}
2202
>
// If the help or version options were used and exitProcess is false,
2203
>
// or if explicitly skipped, we won't run validations.
2204
>
if (!skipValidation) {
2207
>
// if we're executed via bash completion, don't
2208
>
// bother with validation.
2209
>
if (!requestCompletions) {
2210
>
const validation = this[kRunValidation](aliases, {}, parsed.error);
2211
>
if (!calledFromCommand) {
2212
>
argvPromise = applyMiddleware(
2213
>
argv,
2214
>
this,
2215
>
this.#globalMiddleware.getMiddleware(),
2216
>
true
2217
>
);
2218
>
}
2219
>
argvPromise = this[kValidateAsync](validation, argvPromise ?? argv);
2220
>
if (isPromise(argvPromise) && !calledFromCommand) {
2223
>
argv,
2224
>
this,
2225
>
this.#globalMiddleware.getMiddleware(),
2226
>
false
2227
>
);
2229
>
}
2237
>
return this[kPostProcess](
2239
>
populateDoubleDash,
2240
>
!!calledFromCommand,
2241
>
true
2242
>
);
2243
>
}
2246
>
positionalMap: Dictionary<string[]>,
2247
>
parseErrors: Error | null,
2248
>
isDefaultCommand?: boolean
2249
>
): (argv: Arguments) => void {
2250
>
const demandedOptions = {...this.getDemandedOptions()};
2251
>
return (argv: Arguments) => {
2253
>
this.#validation.nonOptionCount(argv);
2254
>
this.#validation.requiredArguments(argv, demandedOptions);
2255
>
let failedStrictCommands = false;
2256
>
if (this.#strictCommands) {
2258
>
}
2261
>
argv,
2262
>
aliases,
2263
>
positionalMap,
2264
>
!!isDefaultCommand
2265
>
);
2268
>
}
2270
>
this.#validation.implications(argv);
2271
>
this.#validation.conflicting(argv);
2273
>
}
2276
>
}
2279
>
this.#options.key[keys] = true;
2280
>
} else {
2283
>
}
2287
>
2288
>
export function isYargsInstance(y: YargsInstance | void): y is YargsInstance {
2290
>
}
2292
>
/** Yargs' context. */
2293
>
export interface Context {
2294
>
commands: string[];
2295
>
fullCommands: string[];
2296
>
}
2297
>
2298
>
interface LoggerInstance {
2299
>
error: Function;
2300
>
log: Function;
2301
>
}
2302
>
2303
>
export interface Options extends ParserOptions {
2304
>
__: (format: any, ...param: any[]) => string;
2305
>
alias: Dictionary<string[]>;
2306
>
array: string[];
2307
>
boolean: string[];
2308
>
choices: Dictionary<string[]>;
2309
>
config: Dictionary<ConfigCallback | boolean>;
2310
>
configObjects: Dictionary[];
2311
>
configuration: Configuration;
2312
>
count: string[];
2313
>
defaultDescription: Dictionary<string | undefined>;
2314
>
demandedCommands: Dictionary<{
2315
>
min: number;
2316
>
max: number;
2317
>
minMsg?: string | null;
2318
>
maxMsg?: string | null;
2319
>
}>;
2320
>
demandedOptions: Dictionary<string | undefined>;
2321
>
deprecatedOptions: Dictionary<string | boolean | undefined>;
2322
>
hiddenOptions: string[];
2323
>
/** Manually set keys */
2324
>
key: Dictionary<boolean | string>;
2325
>
local: string[];
2326
>
normalize: string[];
2327
>
number: string[];
2328
>
showHiddenOpt: string;
2329
>
skipValidation: string[];
2330
>
string: string[];
2331
>
}
2332
>
2333
>
export interface Configuration extends Partial<ParserConfiguration> {
2334
>
/** Should a config object be deep-merged with the object config it extends? */
2335
>
'deep-merge-config'?: boolean;
2336
>
/** Should commands be sorted in help? */
2337
>
'sort-commands'?: boolean;
2338
>
}
2339
>
2340
>
export interface UsageConfiguration {
2341
>
/** Should types be hidden when usage is displayed */
2342
>
'hide-types'?: boolean;
2343
>
}
2344
>
2345
>
export interface OptionDefinition {
2346
>
alias?: string | string[];
2347
>
array?: boolean;
2348
>
boolean?: boolean;
2349
>
choices?: string | string[];
2350
>
coerce?: CoerceCallback;
2351
>
config?: boolean;
2352
>
configParser?: ConfigCallback;
2353
>
conflicts?: string | string[];
2354
>
count?: boolean;
2355
>
default?: any;
2356
>
defaultDescription?: string;
2357
>
deprecate?: string | boolean;
2358
>
deprecated?: OptionDefinition['deprecate'];
2359
>
desc?: string;
2360
>
describe?: OptionDefinition['desc'];
2361
>
description?: OptionDefinition['desc'];
2362
>
demand?: string | true;
2363
>
demandOption?: OptionDefinition['demand'];
2364
>
global?: boolean;
2365
>
group?: string;
2366
>
hidden?: boolean;
2367
>
implies?: string | number | KeyOrPos[];
2368
>
nargs?: number;
2369
>
normalize?: boolean;
2370
>
number?: boolean;
2371
>
require?: OptionDefinition['demand'];
2372
>
required?: OptionDefinition['demand'];
2373
>
requiresArg?: boolean;
2374
>
skipValidation?: boolean;
2375
>
string?: boolean;
2376
>
type?: 'array' | 'boolean' | 'count' | 'number' | 'string';
2377
>
}
2378
>
2379
>
interface PositionalDefinition extends Pick<
2380
>
OptionDefinition,
2381
>
| 'alias'
2382
>
| 'array'
2383
>
| 'coerce'
2384
>
| 'choices'
2385
>
| 'conflicts'
2386
>
| 'default'
2387
>
| 'defaultDescription'
2388
>
| 'demand'
2389
>
| 'desc'
2390
>
| 'describe'
2391
>
| 'description'
2392
>
| 'implies'
2393
>
| 'normalize'
2394
>
> {
2395
>
type?: 'boolean' | 'number' | 'string';
2396
>
}
2397
>
2398
>
interface FrozenYargsInstance {
2399
>
options: Options;
2400
>
configObjects: Dictionary[];
2401
>
exitProcess: boolean;
2402
>
groups: Dictionary<string[]>;
2403
>
strict: boolean;
2404
>
strictCommands: boolean;
2405
>
strictOptions: boolean;
2406
>
completionCommand: string | null;
2407
>
output: string;
2408
>
exitError: YError | string | nil;
2409
>
hasOutput: boolean;
2410
>
parsed: DetailedArguments | false;
2411
>
parseFn: ParseCallback | null;
2412
>
parseContext: object | null;
2413
>
}
2414
>
2415
>
interface ParseCallback {
2416
>
(err: YError | string | nil, argv: Arguments, output: string): void;
2417
>
}
2418
>
2419
>
interface Aliases {
2420
>
[key: string]: Array<string>;
2421
>
}
2422
>
2423
>
export interface Arguments {
2424
>
/** The script name or node command */
2425
>
$0: string;
2426
>
/** Non-option arguments */
2427
>
_: ArgsOutput;
2428
>
/** Arguments after the end-of-options flag `--` */
2429
>
'--'?: ArgsOutput;
2430
>
/** All remaining options */
2431
>
[argName: string]: any;
2432
>
}
2433
>
2434
>
export interface DetailedArguments extends ParserDetailedArguments {
2435
>
argv: Arguments;
2436
>
aliases: Dictionary<string[]>;
2437
>
}