diff --git a/.nycrc b/.nycrc
index 5243a3489..d4b247808 100644
--- a/.nycrc
+++ b/.nycrc
@@ -3,6 +3,7 @@
"build/test/**",
"test/**"
],
+ "exclude-after-remap": true,
"reporter": [
"html",
"text"
@@ -10,4 +11,4 @@
"lines": 100,
"branches": "96",
"statements": "100"
-}
\ No newline at end of file
+}
diff --git a/browser.mjs b/browser.mjs
index d8a9f3de6..2d0d6e9e5 100644
--- a/browser.mjs
+++ b/browser.mjs
@@ -1,7 +1,7 @@
// Bootstrap yargs for browser:
import browserPlatformShim from './lib/platform-shims/browser.mjs';
-import {YargsWithShim} from './build/lib/yargs-factory.js';
+import {YargsFactory} from './build/lib/yargs-factory.js';
-const Yargs = YargsWithShim(browserPlatformShim);
+const Yargs = YargsFactory(browserPlatformShim);
export default Yargs;
diff --git a/deno.ts b/deno.ts
index 62613e5c9..2002f2093 100644
--- a/deno.ts
+++ b/deno.ts
@@ -1,8 +1,8 @@
// Bootstrap yargs for Deno platform:
import denoPlatformShim from './lib/platform-shims/deno.ts';
-import {YargsWithShim} from './build/lib/yargs-factory.js';
+import {YargsFactory} from './build/lib/yargs-factory.js';
-const WrappedYargs = YargsWithShim(denoPlatformShim);
+const WrappedYargs = YargsFactory(denoPlatformShim);
function Yargs(args?: string[]) {
return WrappedYargs(args);
diff --git a/docs/api.md b/docs/api.md
index 9bad6fcac..9bcf3e2cb 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -1439,43 +1439,6 @@ usage information and exit.
The default behavior is to set the value of any key not followed by an
option value to `true`.
-.reset() [DEPRECATED]
---------
-
-Reset the argument object built up so far. This is useful for
-creating nested command line interfaces. Use [global](#global)
-to specify keys that should not be reset.
-
-```js
-var yargs = require('yargs/yargs')(process.argv.slice(2))
- .usage('$0 command')
- .command('hello', 'hello command')
- .command('world', 'world command')
- .demandCommand(1, 'must provide a valid command'),
- argv = yargs.argv,
- command = argv._[0];
-
-if (command === 'hello') {
- yargs.reset()
- .usage('$0 hello')
- .help('h')
- .example('$0 hello', 'print the hello message!')
- .argv
-
- console.log('hello!');
-} else if (command === 'world'){
- yargs.reset()
- .usage('$0 world')
- .help('h')
- .example('$0 world', 'print the world message!')
- .argv
-
- console.log('world!');
-} else {
- yargs.showHelp();
-}
-```
-
.scriptName($0)
------------------
diff --git a/index.cjs b/index.cjs
index 7ac4d3588..d1a169885 100644
--- a/index.cjs
+++ b/index.cjs
@@ -11,6 +11,7 @@ module.exports = Argv;
function Argv(processArgs, cwd) {
const argv = Yargs(processArgs, cwd, require);
singletonify(argv);
+ // TODO(bcoe): warn if argv.parse() or argv.argv is used directly.
return argv;
}
@@ -22,7 +23,10 @@ function Argv(processArgs, cwd) {
to get a parsed version of process.argv.
*/
function singletonify(inst) {
- Object.keys(inst).forEach(key => {
+ [
+ ...Object.keys(inst),
+ ...Object.getOwnPropertyNames(inst.constructor.prototype),
+ ].forEach(key => {
if (key === 'argv') {
Argv.__defineGetter__(key, inst.__lookupGetter__(key));
} else if (typeof inst[key] === 'function') {
diff --git a/index.mjs b/index.mjs
index 23d908013..c6440b9ed 100644
--- a/index.mjs
+++ b/index.mjs
@@ -2,7 +2,7 @@
// Bootstraps yargs for ESM:
import esmPlatformShim from './lib/platform-shims/esm.mjs';
-import {YargsWithShim} from './build/lib/yargs-factory.js';
+import {YargsFactory} from './build/lib/yargs-factory.js';
-const Yargs = YargsWithShim(esmPlatformShim);
+const Yargs = YargsFactory(esmPlatformShim);
export default Yargs;
diff --git a/lib/cjs.ts b/lib/cjs.ts
index 64b57f8ba..82dae13e6 100644
--- a/lib/cjs.ts
+++ b/lib/cjs.ts
@@ -7,7 +7,7 @@ import {isPromise} from './utils/is-promise.js';
import {objFilter} from './utils/obj-filter.js';
import {parseCommand} from './parse-command.js';
import * as processArgv from './utils/process-argv.js';
-import {YargsWithShim, rebase} from './yargs-factory.js';
+import {YargsFactory} from './yargs-factory.js';
import {YError} from './yerror.js';
import cjsPlatformShim from './platform-shims/cjs.js';
@@ -27,7 +27,7 @@ if (process && process.version) {
}
const Parser = require('yargs-parser');
-const Yargs = YargsWithShim(cjsPlatformShim);
+const Yargs = YargsFactory(cjsPlatformShim);
export default {
applyExtends,
@@ -39,6 +39,5 @@ export default {
parseCommand,
Parser,
processArgv,
- rebase,
YError,
};
diff --git a/lib/command.ts b/lib/command.ts
index 6dde6c6bc..727d32a44 100644
--- a/lib/command.ts
+++ b/lib/command.ts
@@ -207,7 +207,7 @@ export class CommandInstance {
this.handlers[command!] ||
this.handlers[this.aliasMap[command!]] ||
this.defaultCommand;
- const currentContext = yargs.getContext();
+ const currentContext = yargs.getInternalMethods().getContext();
const parentCommands = currentContext.commands.slice();
if (command) {
currentContext.commands.push(command);
@@ -264,7 +264,10 @@ export class CommandInstance {
if (isCommandBuilderCallback(builder)) {
// A function can be provided, which builds
// up a yargs chain and possibly returns it.
- const builderOutput = builder(yargs.reset(aliases), helpOrVersionSet);
+ const builderOutput = builder(
+ yargs.getInternalMethods().reset(aliases),
+ helpOrVersionSet
+ );
// Support the use-case of async builders:
if (isPromise(builderOutput)) {
return builderOutput.then(output => {
@@ -282,7 +285,7 @@ export class CommandInstance {
} else if (isCommandBuilderOptionDefinitions(builder)) {
// as a short hand, an object can instead be provided, specifying
// the options that a command takes.
- innerYargs = yargs.reset(aliases);
+ innerYargs = yargs.getInternalMethods().reset(aliases);
Object.keys(commandHandler.builder).forEach(key => {
innerYargs.option(key, builder[key]);
});
@@ -307,9 +310,10 @@ export class CommandInstance {
// A null command indicates we are running the default command,
// if this is the case, we should show the root usage instructions
// rather than the usage instructions for the nested default command:
- if (!command) innerYargs.getUsageInstance().unfreeze();
+ if (!command) innerYargs.getInternalMethods().getUsageInstance().unfreeze();
if (this.shouldUpdateUsage(innerYargs)) {
innerYargs
+ .getInternalMethods()
.getUsageInstance()
.usage(
this.usageFromParentCommandsCommandHandler(
@@ -319,13 +323,15 @@ export class CommandInstance {
commandHandler.description
);
}
- const innerArgv = innerYargs._parseArgs(
- null,
- undefined,
- true,
- commandIndex,
- helpOnly
- );
+ const innerArgv = innerYargs
+ .getInternalMethods()
+ .runYargsParserAndExecuteCommands(
+ null,
+ undefined,
+ true,
+ commandIndex,
+ helpOnly
+ );
return {
aliases: (innerYargs.parsed as DetailedArguments).aliases,
innerArgv: innerArgv as Arguments,
@@ -333,8 +339,8 @@ export class CommandInstance {
}
private shouldUpdateUsage(yargs: YargsInstance) {
return (
- !yargs.getUsageInstance().getUsageDisabled() &&
- yargs.getUsageInstance().getUsage().length === 0
+ !yargs.getInternalMethods().getUsageInstance().getUsageDisabled() &&
+ yargs.getInternalMethods().getUsageInstance().getUsage().length === 0
);
}
private usageFromParentCommandsCommandHandler(
@@ -364,7 +370,7 @@ export class CommandInstance {
// execute middleware or handlers (these may perform expensive operations
// like creating a DB connection).
if (helpOnly) return innerArgv;
- if (!yargs._hasOutput()) {
+ if (!yargs.getInternalMethods().getHasOutput()) {
positionalMap = this.populatePositionals(
commandHandler,
innerArgv as Arguments,
@@ -380,27 +386,31 @@ export class CommandInstance {
// we apply validation post-hoc, so that custom
// checks get passed populated positional arguments.
- if (!yargs._hasOutput()) {
- const validation = yargs._runValidation(
- aliases,
- positionalMap,
- (yargs.parsed as DetailedArguments).error,
- !command
- );
+ if (!yargs.getInternalMethods().getHasOutput()) {
+ const validation = yargs
+ .getInternalMethods()
+ .runValidation(
+ aliases,
+ positionalMap,
+ (yargs.parsed as DetailedArguments).error,
+ !command
+ );
innerArgv = maybeAsyncResult(innerArgv, result => {
validation(result);
return result;
});
}
- if (commandHandler.handler && !yargs._hasOutput()) {
- yargs._setHasOutput();
+ if (commandHandler.handler && !yargs.getInternalMethods().getHasOutput()) {
+ yargs.getInternalMethods().setHasOutput();
// to simplify the parsing of positionals in commands,
// we temporarily populate '--' rather than _, with arguments
const populateDoubleDash = !!yargs.getOptions().configuration[
'populate--'
];
- yargs._postProcess(innerArgv, populateDoubleDash, false, false);
+ yargs
+ .getInternalMethods()
+ .postProcess(innerArgv, populateDoubleDash, false, false);
innerArgv = applyMiddleware(innerArgv, yargs, middlewares, false);
innerArgv = maybeAsyncResult(innerArgv, result => {
@@ -412,11 +422,14 @@ export class CommandInstance {
}
});
- yargs.getUsageInstance().cacheHelpMessage();
- if (isPromise(innerArgv) && !yargs._hasParseCallback()) {
+ yargs.getInternalMethods().getUsageInstance().cacheHelpMessage();
+ if (
+ isPromise(innerArgv) &&
+ !yargs.getInternalMethods().hasParseCallback()
+ ) {
innerArgv.catch(error => {
try {
- yargs.getUsageInstance().fail(null, error);
+ yargs.getInternalMethods().getUsageInstance().fail(null, error);
} catch (_err) {
// If .fail(false) is not set, and no parse cb() has been
// registered, run usage's default fail method.
@@ -560,7 +573,10 @@ export class CommandInstance {
);
if (parsed.error) {
- yargs.getUsageInstance().fail(parsed.error.message, parsed.error);
+ yargs
+ .getInternalMethods()
+ .getUsageInstance()
+ .fail(parsed.error.message, parsed.error);
} else {
// only copy over positional keys (don't overwrite
// flag arguments that were already parsed).
@@ -587,6 +603,7 @@ export class CommandInstance {
? this.defaultCommand.original
: this.defaultCommand.original.replace(/^[^[\]<>]*/, '$0 ');
yargs
+ .getInternalMethods()
.getUsageInstance()
.usage(commandString, this.defaultCommand.description);
}
diff --git a/lib/completion.ts b/lib/completion.ts
index 1f9cbeff6..15463af1e 100644
--- a/lib/completion.ts
+++ b/lib/completion.ts
@@ -57,7 +57,7 @@ export class Completion implements CompletionInstance {
if (handlers[args[i]] && handlers[args[i]].builder) {
const builder = handlers[args[i]].builder;
if (isCommandBuilderCallback(builder)) {
- const y = this.yargs.reset();
+ const y = this.yargs.getInternalMethods().reset();
builder(y, true);
return y.argv;
}
@@ -77,7 +77,8 @@ export class Completion implements CompletionInstance {
args: string[],
current: string
) {
- const parentCommands = this.yargs.getContext().commands;
+ const parentCommands = this.yargs.getInternalMethods().getContext()
+ .commands;
if (
!current.match(/^-/) &&
parentCommands[parentCommands.length - 1] !== current
diff --git a/lib/usage.ts b/lib/usage.ts
index 5b4989674..7650eec99 100644
--- a/lib/usage.ts
+++ b/lib/usage.ts
@@ -1,11 +1,6 @@
// this file handles outputting usage instructions,
// failures, etc. keeps logging in one place.
-import {
- Dictionary,
- assertNotStrictEqual,
- PlatformShim,
- Y18N,
-} from './typings/common-types.js';
+import {Dictionary, PlatformShim} from './typings/common-types.js';
import {objFilter} from './utils/obj-filter.js';
import {YargsInstance} from './yargs-factory.js';
import {YError} from './yerror.js';
@@ -16,8 +11,8 @@ function isBoolean(fail: FailureFunction | boolean): fail is boolean {
return typeof fail === 'boolean';
}
-export function usage(yargs: YargsInstance, y18n: Y18N, shim: PlatformShim) {
- const __ = y18n.__;
+export function usage(yargs: YargsInstance, shim: PlatformShim) {
+ const __ = shim.y18n.__;
const self = {} as UsageInstance;
// methods for ouputting/building failure message.
@@ -42,7 +37,7 @@ export function usage(yargs: YargsInstance, y18n: Y18N, shim: PlatformShim) {
let failureOutput = false;
self.fail = function fail(msg, err) {
- const logger = yargs._getLoggerInstance();
+ const logger = yargs.getInternalMethods().getLoggerInstance();
if (fails.length) {
for (let i = fails.length - 1; i >= 0; --i) {
@@ -74,7 +69,7 @@ export function usage(yargs: YargsInstance, y18n: Y18N, shim: PlatformShim) {
err = err || new YError(msg);
if (yargs.getExitProcess()) {
return yargs.exit(1);
- } else if (yargs._hasParseCallback()) {
+ } else if (yargs.getInternalMethods().hasParseCallback()) {
return yargs.exit(1, err);
} else {
throw err;
@@ -239,12 +234,15 @@ export function usage(yargs: YargsInstance, y18n: Y18N, shim: PlatformShim) {
if (commands.length > 1 || (commands.length === 1 && !commands[0][2])) {
ui.div(__('Commands:'));
- const context = yargs.getContext();
+ const context = yargs.getInternalMethods().getContext();
const parentCommands = context.commands.length
? `${context.commands.join(' ')} `
: '';
- if (yargs.getParserConfiguration()['sort-commands'] === true) {
+ if (
+ yargs.getInternalMethods().getParserConfiguration()['sort-commands'] ===
+ true
+ ) {
commands = commands.sort((a, b) => a[0].localeCompare(b[0]));
}
@@ -603,7 +601,7 @@ export function usage(yargs: YargsInstance, y18n: Y18N, shim: PlatformShim) {
}
self.showHelp = (level: 'error' | 'log' | ((message: string) => void)) => {
- const logger = yargs._getLoggerInstance();
+ const logger = yargs.getInternalMethods().getLoggerInstance();
if (!level) level = 'error';
const emit = typeof level === 'function' ? level : logger[level];
emit(self.help());
@@ -675,7 +673,7 @@ export function usage(yargs: YargsInstance, y18n: Y18N, shim: PlatformShim) {
};
self.showVersion = level => {
- const logger = yargs._getLoggerInstance();
+ const logger = yargs.getInternalMethods().getLoggerInstance();
if (!level) level = 'error';
const emit = typeof level === 'function' ? level : logger[level];
emit(version);
diff --git a/lib/validation.ts b/lib/validation.ts
index 871d4784a..b550a2957 100644
--- a/lib/validation.ts
+++ b/lib/validation.ts
@@ -2,7 +2,6 @@ import {argsert} from './argsert.js';
import {
Dictionary,
assertNotStrictEqual,
- Y18N,
PlatformShim,
} from './typings/common-types.js';
import {levenshtein as distance} from './utils/levenshtein.js';
@@ -18,11 +17,10 @@ const specialKeys = ['$0', '--', '_'];
export function validation(
yargs: YargsInstance,
usage: UsageInstance,
- y18n: Y18N,
shim: PlatformShim
) {
- const __ = y18n.__;
- const __n = y18n.__n;
+ const __ = shim.y18n.__;
+ const __n = shim.y18n.__n;
const self = {} as ValidationInstance;
// validate appropriate # of non-option
@@ -32,7 +30,8 @@ export function validation(
// don't count currently executing commands
const positionalCount =
argv._.length + (argv['--'] ? argv['--'].length : 0);
- const _s = positionalCount - yargs.getContext().commands.length;
+ const _s =
+ positionalCount - yargs.getInternalMethods().getContext().commands.length;
if (
demandedCommands._ &&
@@ -146,15 +145,21 @@ export function validation(
isDefaultCommand,
checkPositionals = true
) {
- const commandKeys = yargs.getCommandInstance().getCommands();
+ const commandKeys = yargs
+ .getInternalMethods()
+ .getCommandInstance()
+ .getCommands();
const unknown: string[] = [];
- const currentContext = yargs.getContext();
+ const currentContext = yargs.getInternalMethods().getContext();
Object.keys(argv).forEach(key => {
if (
specialKeys.indexOf(key) === -1 &&
!Object.prototype.hasOwnProperty.call(positionalMap, key) &&
- !Object.prototype.hasOwnProperty.call(yargs._getParseContext(), key) &&
+ !Object.prototype.hasOwnProperty.call(
+ yargs.getInternalMethods().getParseContext(),
+ key
+ ) &&
!self.isValidAndSomeAliasIsNotNew(key, aliases)
) {
unknown.push(key);
@@ -187,9 +192,12 @@ export function validation(
};
self.unknownCommands = function unknownCommands(argv) {
- const commandKeys = yargs.getCommandInstance().getCommands();
+ const commandKeys = yargs
+ .getInternalMethods()
+ .getCommandInstance()
+ .getCommands();
const unknown: string[] = [];
- const currentContext = yargs.getContext();
+ const currentContext = yargs.getInternalMethods().getContext();
if (currentContext.commands.length > 0 || commandKeys.length > 0) {
argv._.slice(currentContext.commands.length).forEach(key => {
diff --git a/lib/yargs-factory.ts b/lib/yargs-factory.ts
index 50f310560..d83767608 100644
--- a/lib/yargs-factory.ts
+++ b/lib/yargs-factory.ts
@@ -61,431 +61,288 @@ import {isPromise} from './utils/is-promise.js';
import {maybeAsyncResult} from './utils/maybe-async-result.js';
import setBlocking from './utils/set-blocking.js';
-let shim: PlatformShim;
-export function YargsWithShim(_shim: PlatformShim) {
- shim = _shim;
- return Yargs;
-}
-
-function Yargs(
- processArgs: string | string[] = [],
- cwd = shim.process.cwd(),
- parentRequire?: RequireType
-): YargsInstance {
- const self = {} as YargsInstance;
- let command: CommandInstance;
- let completion: CompletionInstance | null = null;
- let groups: Dictionary = {};
- let output = '';
- const preservedGroups: Dictionary = {};
- const globalMiddleware = new GlobalMiddleware(self);
- let usage: UsageInstance;
- let validation: ValidationInstance;
-
- const y18n = shim.y18n;
-
- self.scriptName = function (scriptName) {
- self.customScriptName = true;
- self.$0 = scriptName;
- return self;
+export function YargsFactory(_shim: PlatformShim) {
+ return (
+ processArgs: string | string[] = [],
+ cwd = _shim.process.cwd(),
+ parentRequire?: RequireType
+ ): YargsInstance => {
+ const yargs = new YargsInstance(processArgs, cwd, parentRequire, _shim);
+ // Legacy yargs.argv interface, it's recommended that you use .parse().
+ Object.defineProperty(yargs, 'argv', {
+ get: () => {
+ return yargs.parse();
+ },
+ enumerable: true,
+ });
+ // an app should almost always have --version and --help,
+ // if you *really* want to disable this use .help(false)/.version(false).
+ yargs.help();
+ yargs.version();
+ return yargs;
};
+}
- // ignore the node bin, specify this in your
- // bin file with #!/usr/bin/env node
- let default$0: string[];
- if (/\b(node|iojs|electron)(\.exe)?$/.test(shim.process.argv()[0])) {
- default$0 = shim.process.argv().slice(1, 2);
- } else {
- default$0 = shim.process.argv().slice(0, 1);
- }
-
- self.$0 = default$0
- .map(x => {
- const b = rebase(cwd, x);
- return x.match(/^(\/|([a-zA-Z]:)?\\)/) && b.length < x.length ? b : x;
- })
- .join(' ')
- .trim();
+// Used to expose private methods to other module-level classes,
+// such as the command parser and usage printer.
+const kCopyDoubleDash = Symbol('copyDoubleDash');
+const kCreateLogger = Symbol('copyDoubleDash');
+const kDeleteFromParserHintObject = Symbol('deleteFromParserHintObject');
+const kFreeze = Symbol('freeze');
+const kGetDollarZero = Symbol('getDollarZero');
+const kGetParserConfiguration = Symbol('getParserConfiguration');
+const kGuessLocale = Symbol('guessLocale');
+const kGuessVersion = Symbol('guessVersion');
+const kParsePositionalNumbers = Symbol('parsePositionalNumbers');
+const kPkgUp = Symbol('pkgUp');
+const kPopulateParserHintArray = Symbol('populateParserHintArray');
+const kPopulateParserHintSingleValueDictionary = Symbol(
+ 'populateParserHintSingleValueDictionary'
+);
+const kPopulateParserHintArrayDictionary = Symbol(
+ 'populateParserHintArrayDictionary'
+);
+const kPopulateParserHintDictionary = Symbol('populateParserHintDictionary');
+const kSanitizeKey = Symbol('sanitizeKey');
+const kSetKey = Symbol('setKey');
+const kUnfreeze = Symbol('unfreeze');
+const kValidateAsync = Symbol('validateAsync');
+const kGetCommandInstance = Symbol('getCommandInstance');
+const kGetContext = Symbol('getContext');
+const kGetHasOutput = Symbol('getHasOutput');
+const kGetLoggerInstance = Symbol('getLoggerInstance');
+const kGetParseContext = Symbol('getParseContext');
+const kGetUsageInstance = Symbol('getUsageInstance');
+const kGetValidationInstance = Symbol('getValidationInstance');
+const kHasParseCallback = Symbol('hasParseCallback');
+const kPostProcess = Symbol('postProcess');
+const kRebase = Symbol('rebase');
+const kReset = Symbol('reset');
+const kRunYargsParserAndExecuteCommands = Symbol(
+ 'runYargsParserAndExecuteCommands'
+);
+const kRunValidation = Symbol('runValidation');
+const kSetHasOutput = Symbol('setHasOutput');
+export interface YargsInternalMethods {
+ getCommandInstance(): CommandInstance;
+ getContext(): Context;
+ getHasOutput(): boolean;
+ getLoggerInstance(): LoggerInstance;
+ getParseContext(): Object;
+ getParserConfiguration(): Configuration;
+ getUsageInstance(): UsageInstance;
+ getValidationInstance(): ValidationInstance;
+ hasParseCallback(): boolean;
+ postProcess>(
+ argv: Arguments | Promise,
+ populateDoubleDash: boolean,
+ calledFromCommand: boolean,
+ runGlobalMiddleware: boolean
+ ): any;
+ reset(aliases?: Aliases): YargsInstance;
+ runValidation(
+ aliases: Dictionary,
+ positionalMap: Dictionary,
+ parseErrors: Error | null,
+ isDefaultCommand?: boolean
+ ): (argv: Arguments) => void;
+ runYargsParserAndExecuteCommands(
+ args: string | string[] | null,
+ shortCircuit?: boolean | null,
+ calledFromCommand?: boolean,
+ commandIndex?: number,
+ helpOnly?: boolean
+ ): Arguments | Promise;
+ setHasOutput(): void;
+}
- if (shim.getEnv('_') && shim.getProcessArgvBin() === shim.getEnv('_')) {
- self.$0 = shim
- .getEnv('_')!
- .replace(`${shim.path.dirname(shim.process.execPath())}/`, '');
- }
+export class YargsInstance {
+ $0: string;
+ argv?: Arguments;
+ customScriptName = false;
+ parsed: DetailedArguments | false = false;
+ #command: CommandInstance;
+ #cwd: string;
// use context object to keep track of resets, subcommand execution, etc.,
// submodules should modify and check the state of context as necessary:
- const context = {commands: [], fullCommands: []};
- self.getContext = () => context;
-
- let hasOutput = false;
- let exitError: YError | string | undefined | null = null;
- // maybe exit, always capture
- // context about why we wanted to exit.
- self.exit = (code, err) => {
- hasOutput = true;
- exitError = err;
- if (exitProcess) shim.process.exit(code);
- };
-
- let completionCommand: string | null = null;
- self.completion = function (
- cmd?: string,
- desc?: string | false | CompletionFunction,
- fn?: CompletionFunction
+ #context: Context = {commands: [], fullCommands: []};
+ #completion: CompletionInstance | null = null;
+ #completionCommand: string | null = null;
+ #defaultShowHiddenOpt = 'show-hidden';
+ #exitError: YError | string | undefined | null = null;
+ #detectLocale = true;
+ #exitProcess = true;
+ #frozens: FrozenYargsInstance[] = [];
+ #globalMiddleware: GlobalMiddleware;
+ #groups: Dictionary = {};
+ #hasOutput = false;
+ #helpOpt: string | null = null;
+ #logger: LoggerInstance;
+ #output = '';
+ #options: Options;
+ #parentRequire?: RequireType;
+ #parserConfig: Configuration = {};
+ #parseFn: ParseCallback | null = null;
+ #parseContext: object | null = null;
+ #pkgs: Dictionary<{[key: string]: string | {[key: string]: string}}> = {};
+ #preservedGroups: Dictionary = {};
+ #processArgs: string | string[];
+ #recommendCommands = false;
+ #shim: PlatformShim;
+ #strict = false;
+ #strictCommands = false;
+ #strictOptions = false;
+ #usage: UsageInstance;
+ #versionOpt: string | null = null;
+ #validation: ValidationInstance;
+
+ constructor(
+ processArgs: string | string[] = [],
+ cwd: string,
+ parentRequire: RequireType | undefined,
+ shim: PlatformShim
) {
- argsert(
- '[string] [string|boolean|function] [function]',
- [cmd, desc, fn],
- arguments.length
- );
-
- // a function to execute when generating
- // completions can be provided as the second
- // or third argument to completion.
- if (typeof desc === 'function') {
- fn = desc;
- desc = undefined;
- }
+ this.#shim = shim;
+ this.#processArgs = processArgs;
+ this.#cwd = cwd;
+ this.#parentRequire = parentRequire;
+ this.#globalMiddleware = new GlobalMiddleware(this);
+ this.$0 = this[kGetDollarZero]();
+ // #command, #validation, and #usage are initialized on first reset:
+ this[kReset]();
+ this.#command = this!.#command;
+ this.#usage = this!.#usage;
+ this.#validation = this!.#validation;
+ this.#options = this!.#options;
+ this.#options.showHiddenOpt = this.#defaultShowHiddenOpt;
+ this.#logger = this[kCreateLogger]();
+ }
+ addHelpOpt(opt?: string | false, msg?: string): YargsInstance {
+ const defaultHelpOpt = 'help';
+ argsert('[string|boolean] [string]', [opt, msg], arguments.length);
- // register the completion command.
- completionCommand = cmd || completionCommand || 'completion';
- if (!desc && desc !== false) {
- desc = 'generate completion script';
+ // nuke the key previously configured
+ // to return help.
+ if (this.#helpOpt) {
+ this[kDeleteFromParserHintObject](this.#helpOpt);
+ this.#helpOpt = null;
}
- self.command(completionCommand, desc);
-
- // a function can be provided
- if (fn) completion!.registerFunction(fn);
-
- return self;
- };
-
- // puts yargs back into an initial state. any keys
- // that have been set to "global" will not be reset
- // by this action.
- let options: Options;
- self.resetOptions = self.reset = function resetOptions(aliases = {}) {
- options = options || {};
- // put yargs back into an initial state, this
- // logic is used to build a nested command
- // hierarchy.
- const tmpOptions = {} as Options;
- tmpOptions.local = options.local ? options.local : [];
- tmpOptions.configObjects = options.configObjects
- ? options.configObjects
- : [];
- // if a key has been explicitly set as local,
- // we should reset it before passing options to command.
- const localLookup: Dictionary = {};
- tmpOptions.local.forEach(l => {
- localLookup[l] = true;
- (aliases[l] || []).forEach(a => {
- localLookup[a] = true;
- });
- });
+ if (opt === false && msg === undefined) return this;
- // add all groups not set to local to preserved groups
- Object.assign(
- preservedGroups,
- Object.keys(groups).reduce((acc, groupName) => {
- const keys = groups[groupName].filter(key => !(key in localLookup));
- if (keys.length > 0) {
- acc[groupName] = keys;
- }
- return acc;
- }, {} as Dictionary)
+ // use arguments, fallback to defaults for opt and msg
+ this.#helpOpt = typeof opt === 'string' ? opt : defaultHelpOpt;
+ this.boolean(this.#helpOpt);
+ this.describe(
+ this.#helpOpt,
+ msg || this.#usage.deferY18nLookup('Show help')
);
- // groups can now be reset
- groups = {};
-
- const arrayOptions: KeyOf[] = [
- 'array',
- 'boolean',
- 'string',
- 'skipValidation',
- 'count',
- 'normalize',
- 'number',
- 'hiddenOptions',
- ];
-
- const objectOptions: DictionaryKeyof[] = [
- 'narg',
- 'key',
- 'alias',
- 'default',
- 'defaultDescription',
- 'config',
- 'choices',
- 'demandedOptions',
- 'demandedCommands',
- 'deprecatedOptions',
- ];
-
- arrayOptions.forEach(k => {
- tmpOptions[k] = (options[k] || []).filter((k: string) => !localLookup[k]);
- });
-
- objectOptions.forEach(>(k: K) => {
- tmpOptions[k] = objFilter(options[k], k => !localLookup[k as string]);
- });
-
- tmpOptions.envPrefix = options.envPrefix;
- options = tmpOptions;
-
- // if this is the first time being executed, create
- // instances of all our helpers -- otherwise just reset.
- usage = usage ? usage.reset(localLookup) : Usage(self, y18n, shim);
- validation = validation
- ? validation.reset(localLookup)
- : Validation(self, usage, y18n, shim);
- command = command
- ? command.reset()
- : Command(usage, validation, globalMiddleware, shim);
- if (!completion) completion = Completion(self, usage, command, shim);
- globalMiddleware.reset();
-
- completionCommand = null;
- output = '';
- exitError = null;
- hasOutput = false;
- self.parsed = false;
-
- return self;
- };
- self.resetOptions();
-
- // temporary hack: allow "freezing" of reset-able state for parse(msg, cb)
- const frozens: FrozenYargsInstance[] = [];
- function freeze() {
- frozens.push({
- options,
- configObjects: options.configObjects.slice(0),
- exitProcess,
- groups,
- strict,
- strictCommands,
- strictOptions,
- completionCommand,
- output,
- exitError,
- hasOutput,
- parsed: self.parsed,
- parseFn,
- parseContext,
- });
- usage.freeze();
- validation.freeze();
- command.freeze();
- globalMiddleware.freeze();
- }
- function unfreeze() {
- const frozen = frozens.pop();
- assertNotStrictEqual(frozen, undefined, shim);
- let configObjects: Dictionary[];
- ({
- options,
- configObjects,
- exitProcess,
- groups,
- output,
- exitError,
- hasOutput,
- parsed: self.parsed,
- strict,
- strictCommands,
- strictOptions,
- completionCommand,
- parseFn,
- parseContext,
- } = frozen);
- options.configObjects = configObjects;
- usage.unfreeze();
- validation.unfreeze();
- command.unfreeze();
- globalMiddleware.unfreeze();
+ return this;
}
-
- self.boolean = function (keys) {
- argsert('', [keys], arguments.length);
- populateParserHintArray('boolean', keys);
- return self;
- };
-
- self.array = function (keys) {
- argsert('', [keys], arguments.length);
- populateParserHintArray('array', keys);
- return self;
- };
-
- self.number = function (keys) {
- argsert('', [keys], arguments.length);
- populateParserHintArray('number', keys);
- return self;
- };
-
- self.normalize = function (keys) {
- argsert('', [keys], arguments.length);
- populateParserHintArray('normalize', keys);
- return self;
- };
-
- self.count = function (keys) {
- argsert('', [keys], arguments.length);
- populateParserHintArray('count', keys);
- return self;
- };
-
- self.string = function (keys) {
- argsert('', [keys], arguments.length);
- populateParserHintArray('string', keys);
- return self;
- };
-
- self.requiresArg = function (keys) {
- // the 2nd paramter [number] in the argsert the assertion is mandatory
- // as populateParserHintSingleValueDictionary recursively calls requiresArg
- // with Nan as a 2nd parameter, although we ignore it
- argsert(' [number]', [keys], arguments.length);
- // If someone configures nargs at the same time as requiresArg,
- // nargs should take precedent,
- // see: https://github.com/yargs/yargs/pull/1572
- // TODO: make this work with aliases, using a check similar to
- // checkAllAliases() in yargs-parser.
- if (typeof keys === 'string' && options.narg[keys]) {
- return self;
- } else {
- populateParserHintSingleValueDictionary(
- self.requiresArg,
- 'narg',
- keys,
- NaN
- );
- }
- return self;
- };
-
- self.skipValidation = function (keys) {
- argsert('', [keys], arguments.length);
- populateParserHintArray('skipValidation', keys);
- return self;
- };
-
- function populateParserHintArray>(
- type: T,
- keys: string | string[]
- ) {
- keys = ([] as string[]).concat(keys);
- keys.forEach(key => {
- key = sanitizeKey(key);
- options[type].push(key);
- });
+ help(opt?: string, msg?: string): YargsInstance {
+ return this.addHelpOpt(opt, msg);
}
- self.nargs = function (
- key: string | string[] | Dictionary,
- value?: number
- ) {
- argsert(' [number]', [key, value], arguments.length);
- populateParserHintSingleValueDictionary(self.nargs, 'narg', key, value);
- return self;
- };
+ addShowHiddenOpt(opt?: string | false, msg?: string): YargsInstance {
+ argsert('[string|boolean] [string]', [opt, msg], arguments.length);
+ if (opt === false && msg === undefined) return this;
+ const showHiddenOpt =
+ typeof opt === 'string' ? opt : this.#defaultShowHiddenOpt;
+ this.boolean(showHiddenOpt);
+ this.describe(
+ showHiddenOpt,
+ msg || this.#usage.deferY18nLookup('Show hidden options')
+ );
+ this.#options.showHiddenOpt = showHiddenOpt;
+ return this;
+ }
+ showHidden(opt?: string | false, msg?: string): YargsInstance {
+ return this.addShowHiddenOpt(opt, msg);
+ }
- self.choices = function (
+ alias(
key: string | string[] | Dictionary,
value?: string | string[]
- ) {
+ ): YargsInstance {
argsert(
' [string|array]',
[key, value],
arguments.length
);
- populateParserHintArrayDictionary(self.choices, 'choices', key, value);
- return self;
- };
-
- self.alias = function (
+ this[kPopulateParserHintArrayDictionary](
+ this.alias.bind(this),
+ 'alias',
+ key,
+ value
+ );
+ return this;
+ }
+ array(keys: string | string[]): YargsInstance {
+ argsert('', [keys], arguments.length);
+ this[kPopulateParserHintArray]('array', keys);
+ return this;
+ }
+ boolean(keys: string | string[]): YargsInstance {
+ argsert('', [keys], arguments.length);
+ this[kPopulateParserHintArray]('boolean', keys);
+ return this;
+ }
+ check(f: (argv: Arguments) => any, global?: boolean): YargsInstance {
+ argsert(' [boolean]', [f, global], arguments.length);
+ this.middleware(
+ (
+ argv: Arguments,
+ _yargs: YargsInstance
+ ): Partial | Promise> => {
+ return maybeAsyncResult<
+ Partial | Promise> | any
+ >(
+ () => {
+ return f(argv);
+ },
+ (result: any): Partial | Promise> => {
+ if (!result) {
+ this.#usage.fail(
+ this.#shim.y18n.__('Argument check failed: %s', f.toString())
+ );
+ } else if (typeof result === 'string' || result instanceof Error) {
+ this.#usage.fail(result.toString(), result);
+ }
+ return argv;
+ },
+ (err: Error): Partial | Promise> => {
+ this.#usage.fail(err.message ? err.message : err.toString(), err);
+ return argv;
+ }
+ );
+ },
+ false,
+ global
+ );
+ return this;
+ }
+ choices(
key: string | string[] | Dictionary,
value?: string | string[]
- ) {
+ ): YargsInstance {
argsert(
' [string|array]',
[key, value],
arguments.length
);
- populateParserHintArrayDictionary(self.alias, 'alias', key, value);
- return self;
- };
-
- // TODO: actually deprecate self.defaults.
- self.default = self.defaults = function (
- key: string | string[] | Dictionary,
- value?: any,
- defaultDescription?: string
- ) {
- argsert(
- ' [*] [string]',
- [key, value, defaultDescription],
- arguments.length
- );
- if (defaultDescription) {
- assertSingleKey(key, shim);
- options.defaultDescription[key] = defaultDescription;
- }
- if (typeof value === 'function') {
- assertSingleKey(key, shim);
- if (!options.defaultDescription[key])
- options.defaultDescription[key] = usage.functionDescription(value);
- value = value.call();
- }
- populateParserHintSingleValueDictionary<'default'>(
- self.default,
- 'default',
+ this[kPopulateParserHintArrayDictionary](
+ this.choices.bind(this),
+ 'choices',
key,
value
);
- return self;
- };
-
- self.describe = function (
- key: string | string[] | Dictionary,
- desc?: string
- ) {
- argsert(' [string]', [key, desc], arguments.length);
- setKey(key, true);
- usage.describe(key, desc);
- return self;
- };
-
- function setKey(
- key: string | string[] | Dictionary,
- set?: boolean | string
- ) {
- populateParserHintSingleValueDictionary(setKey, 'key', key, set);
- return self;
- }
-
- function demandOption(
- keys: string | string[] | Dictionary,
- msg?: string
- ) {
- argsert(' [string]', [keys, msg], arguments.length);
- populateParserHintSingleValueDictionary(
- self.demandOption,
- 'demandedOptions',
- keys,
- msg
- );
- return self;
+ return this;
}
- self.demandOption = demandOption;
-
- self.coerce = function (
+ coerce(
keys: string | string[] | Dictionary,
value?: CoerceCallback
- ) {
+ ): YargsInstance {
argsert(
' [function]',
[keys, value],
@@ -496,14 +353,14 @@ function Yargs(
throw new YError('coerce callback must be provided');
}
for (const key of keys) {
- self.coerce(key, value);
+ this.coerce(key, value);
}
- return self;
+ return this;
} else if (typeof keys === 'object') {
for (const key of Object.keys(keys)) {
- self.coerce(key, keys[key]);
+ this.coerce(key, keys[key]);
}
- return self;
+ return this;
}
if (!value) {
throw new YError('coerce callback must be provided');
@@ -511,8 +368,8 @@ function Yargs(
// This noop tells yargs-parser about the existence of the option
// represented by "keys", so that it can apply camel case expansion
// if needed:
- self.alias(keys, keys);
- globalMiddleware.addCoerceMiddleware(
+ this.alias(keys, keys);
+ this.#globalMiddleware.addCoerceMiddleware(
(
argv: Arguments,
yargs: YargsInstance
@@ -541,117 +398,21 @@ function Yargs(
},
keys
);
- return self;
- };
-
- function populateParserHintSingleValueDictionary<
- T extends
- | Exclude, DictionaryKeyof>
- | 'default',
- K extends keyof Options[T] & string = keyof Options[T] & string,
- V extends ValueOf = ValueOf
- >(
- builder: (key: K, value: V, ...otherArgs: any[]) => YargsInstance,
- type: T,
- key: K | K[] | {[key in K]: V},
- value?: V
- ) {
- populateParserHintDictionary(
- builder,
- type,
- key,
- value,
- (type, key, value) => {
- options[type][key] = value as ValueOf;
- }
- );
- }
-
- function populateParserHintArrayDictionary<
- T extends DictionaryKeyof,
- K extends keyof Options[T] & string = keyof Options[T] & string,
- V extends ValueOf> | ValueOf>[] =
- | ValueOf>
- | ValueOf>[]
- >(
- builder: (key: K, value: V, ...otherArgs: any[]) => YargsInstance,
- type: T,
- key: K | K[] | {[key in K]: V},
- value?: V
- ) {
- populateParserHintDictionary(
- builder,
- type,
- key,
- value,
- (type, key, value) => {
- options[type][key] = (
- options[type][key] || ([] as Options[T][keyof Options[T]])
- ).concat(value);
- }
- );
- }
-
- function populateParserHintDictionary<
- T extends keyof Options,
- K extends keyof Options[T],
- V
- >(
- builder: (key: K, value: V, ...otherArgs: any[]) => YargsInstance,
- type: T,
- key: K | K[] | {[key in K]: V},
- value: V | undefined,
- singleKeyHandler: (type: T, key: K, value?: V) => void
- ) {
- if (Array.isArray(key)) {
- // an array of keys with one value ['x', 'y', 'z'], function parse () {}
- key.forEach(k => {
- builder(k, value!);
- });
- } else if (
- ((key): key is {[key in K]: V} => typeof key === 'object')(key)
- ) {
- // an object of key value pairs: {'x': parse () {}, 'y': parse() {}}
- for (const k of objectKeys(key)) {
- builder(k, key[k]);
- }
- } else {
- singleKeyHandler(type, sanitizeKey(key), value);
- }
- }
-
- // TODO(bcoe): in future major versions move more objects towards
- // Object.create(null):
- function sanitizeKey(key: K): K;
- function sanitizeKey(key: '__proto__'): '___proto___';
- function sanitizeKey(key: any) {
- if (key === '__proto__') return '___proto___';
- return key;
+ return this;
}
-
- function deleteFromParserHintObject(optionKey: string) {
- // delete from all parsing hints:
- // boolean, array, key, alias, etc.
- objectKeys(options).forEach((hintKey: keyof Options) => {
- // configObjects is not a parsing hint array
- if (((key): key is 'configObjects' => key === 'configObjects')(hintKey))
- return;
- const hint = options[hintKey];
- if (Array.isArray(hint)) {
- if (~hint.indexOf(optionKey)) hint.splice(hint.indexOf(optionKey), 1);
- } else if (typeof hint === 'object') {
- delete (hint as Dictionary)[optionKey];
- }
- });
- // now delete the description from usage.js.
- delete usage.getDescriptions()[optionKey];
+ conflicts(
+ key1: string | Dictionary,
+ key2?: string | string[]
+ ): YargsInstance {
+ argsert(' [string|array]', [key1, key2], arguments.length);
+ this.#validation.conflicts(key1, key2);
+ return this;
}
-
- self.config = function config(
+ config(
key: string | string[] | Dictionary = 'config',
msg?: string | ConfigCallback,
parseFn?: ConfigCallback
- ) {
+ ): YargsInstance {
argsert(
'[object|string] [string|function] [function]',
[key, msg, parseFn],
@@ -661,12 +422,14 @@ function Yargs(
if (typeof key === 'object' && !Array.isArray(key)) {
key = applyExtends(
key,
- cwd,
- self.getParserConfiguration()['deep-merge-config'] || false,
- shim
+ this.#cwd,
+ this[kGetParserConfiguration]()['deep-merge-config'] || false,
+ this.#shim
+ );
+ this.#options.configObjects = (this.#options.configObjects || []).concat(
+ key
);
- options.configObjects = (options.configObjects || []).concat(key);
- return self;
+ return this;
}
// allow for a custom parsing function.
@@ -675,46 +438,61 @@ function Yargs(
msg = undefined;
}
- self.describe(
+ this.describe(
key,
- msg || usage.deferY18nLookup('Path to JSON config file')
+ msg || this.#usage.deferY18nLookup('Path to JSON config file')
);
(Array.isArray(key) ? key : [key]).forEach(k => {
- options.config[k] = parseFn || true;
+ this.#options.config[k] = parseFn || true;
});
- return self;
- };
+ return this;
+ }
+ completion(
+ cmd?: string,
+ desc?: string | false | CompletionFunction,
+ fn?: CompletionFunction
+ ): YargsInstance {
+ argsert(
+ '[string] [string|boolean|function] [function]',
+ [cmd, desc, fn],
+ arguments.length
+ );
- self.example = function (
- cmd: string | [string, string?][],
- description?: string
- ) {
- argsert(' [string]', [cmd, description], arguments.length);
+ // a function to execute when generating
+ // completions can be provided as the second
+ // or third argument to completion.
+ if (typeof desc === 'function') {
+ fn = desc;
+ desc = undefined;
+ }
- if (Array.isArray(cmd)) {
- cmd.forEach(exampleParams => self.example(...exampleParams));
- } else {
- usage.example(cmd, description);
+ // register the completion command.
+ this.#completionCommand = cmd || this.#completionCommand || 'completion';
+ if (!desc && desc !== false) {
+ desc = 'generate completion script';
}
+ this.command(this.#completionCommand, desc);
- return self;
- };
+ // a function can be provided
+ if (fn) this.#completion!.registerFunction(fn);
- self.command = self.commands = function (
+ return this;
+ }
+ command(
cmd: string | CommandHandlerDefinition | DefinitionOrCommandName[],
description?: CommandHandler['description'],
builder?: CommandBuilderDefinition | CommandBuilder,
handler?: CommandHandlerCallback,
middlewares?: Middleware[],
deprecated?: boolean
- ) {
+ ): YargsInstance {
argsert(
' [string|boolean] [function|object] [function] [array] [boolean|string]',
[cmd, description, builder, handler, middlewares, deprecated],
arguments.length
);
- command.addHandler(
+ this.#command.addHandler(
cmd,
description,
builder,
@@ -722,30 +500,113 @@ function Yargs(
middlewares,
deprecated
);
- return self;
- };
-
- self.commandDir = function (dir, opts) {
+ return this;
+ }
+ commands(
+ cmd: string | CommandHandlerDefinition | DefinitionOrCommandName[],
+ description?: CommandHandler['description'],
+ builder?: CommandBuilderDefinition | CommandBuilder,
+ handler?: CommandHandlerCallback,
+ middlewares?: Middleware[],
+ deprecated?: boolean
+ ): YargsInstance {
+ return this.command(
+ cmd,
+ description,
+ builder,
+ handler,
+ middlewares,
+ deprecated
+ );
+ }
+ commandDir(dir: string, opts?: RequireDirectoryOptions): YargsInstance {
argsert(' [object]', [dir, opts], arguments.length);
- const req = parentRequire || shim.require;
- command.addDirectory(dir, req, shim.getCallerFile(), opts);
- return self;
- };
+ const req = this.#parentRequire || this.#shim.require;
+ this.#command.addDirectory(dir, req, this.#shim.getCallerFile(), opts);
+ return this;
+ }
+ count(keys: string | string[]): YargsInstance {
+ argsert('', [keys], arguments.length);
+ this[kPopulateParserHintArray]('count', keys);
+ return this;
+ }
+ default(
+ key: string | string[] | Dictionary,
+ value?: any,
+ defaultDescription?: string
+ ): YargsInstance {
+ argsert(
+ ' [*] [string]',
+ [key, value, defaultDescription],
+ arguments.length
+ );
+ if (defaultDescription) {
+ assertSingleKey(key, this.#shim);
+ this.#options.defaultDescription[key] = defaultDescription;
+ }
+ if (typeof value === 'function') {
+ assertSingleKey(key, this.#shim);
+ if (!this.#options.defaultDescription[key])
+ this.#options.defaultDescription[key] = this.#usage.functionDescription(
+ value
+ );
+ value = value.call();
+ }
+ this[kPopulateParserHintSingleValueDictionary]<'default'>(
+ this.default.bind(this),
+ 'default',
+ key,
+ value
+ );
+ return this;
+ }
+ defaults(
+ key: string | string[] | Dictionary,
+ value?: any,
+ defaultDescription?: string
+ ): YargsInstance {
+ return this.default(key, value, defaultDescription);
+ }
+ demandCommand(
+ min = 1,
+ max?: number | string,
+ minMsg?: string | null,
+ maxMsg?: string | null
+ ): YargsInstance {
+ argsert(
+ '[number] [number|string] [string|null|undefined] [string|null|undefined]',
+ [min, max, minMsg, maxMsg],
+ arguments.length
+ );
+
+ if (typeof max !== 'number') {
+ minMsg = max;
+ max = Infinity;
+ }
+
+ this.global('_', false);
+
+ this.#options.demandedCommands._ = {
+ min,
+ max,
+ minMsg,
+ maxMsg,
+ };
- // TODO: deprecate self.demand in favor of
- // .demandCommand() .demandOption().
- self.demand = self.required = self.require = function demand(
+ return this;
+ }
+ demand(
keys: string | string[] | Dictionary | number,
max?: number | string[] | string | true,
msg?: string | true
- ) {
+ ): YargsInstance {
// you can optionally provide a 'max' key,
// which will raise an exception if too many '_'
// options are provided.
if (Array.isArray(max)) {
max.forEach(key => {
- assertNotStrictEqual(msg, true as const, shim);
- demandOption(key, msg);
+ assertNotStrictEqual(msg, true as const, this.#shim);
+ this.demandOption(key, msg);
});
max = Infinity;
} else if (typeof max !== 'number') {
@@ -754,468 +615,511 @@ function Yargs(
}
if (typeof keys === 'number') {
- assertNotStrictEqual(msg, true as const, shim);
- self.demandCommand(keys, max, msg, msg);
+ assertNotStrictEqual(msg, true as const, this.#shim);
+ this.demandCommand(keys, max, msg, msg);
} else if (Array.isArray(keys)) {
keys.forEach(key => {
- assertNotStrictEqual(msg, true as const, shim);
- demandOption(key, msg);
+ assertNotStrictEqual(msg, true as const, this.#shim);
+ this.demandOption(key, msg);
});
} else {
if (typeof msg === 'string') {
- demandOption(keys, msg);
+ this.demandOption(keys, msg);
} else if (msg === true || typeof msg === 'undefined') {
- demandOption(keys);
+ this.demandOption(keys);
}
}
- return self;
- };
-
- self.demandCommand = function demandCommand(
- min = 1,
- max?: number | string,
- minMsg?: string | null,
- maxMsg?: string | null
- ) {
- argsert(
- '[number] [number|string] [string|null|undefined] [string|null|undefined]',
- [min, max, minMsg, maxMsg],
- arguments.length
+ return this;
+ }
+ demandOption(
+ keys: string | string[] | Dictionary,
+ msg?: string
+ ): YargsInstance {
+ argsert(' [string]', [keys, msg], arguments.length);
+ this[kPopulateParserHintSingleValueDictionary](
+ this.demandOption.bind(this),
+ 'demandedOptions',
+ keys,
+ msg
);
-
- if (typeof max !== 'number') {
- minMsg = max;
- max = Infinity;
- }
-
- self.global('_', false);
-
- options.demandedCommands._ = {
- min,
- max,
- minMsg,
- maxMsg,
- };
-
- return self;
- };
-
- self.getAliases = () => {
- return self.parsed ? self.parsed.aliases : {};
- };
-
- self.getDemandedOptions = () => {
- argsert([], 0);
- return options.demandedOptions;
- };
-
- self.getDemandedCommands = () => {
- argsert([], 0);
- return options.demandedCommands;
- };
-
- self.deprecateOption = function deprecateOption(option, message) {
+ return this;
+ }
+ deprecateOption(option: string, message: string | boolean): YargsInstance {
argsert(' [string|boolean]', [option, message], arguments.length);
- options.deprecatedOptions[option] = message;
- return self;
- };
-
- self.getDeprecatedOptions = () => {
- argsert([], 0);
- return options.deprecatedOptions;
- };
-
- self.implies = function (
- key: string | Dictionary,
- value?: KeyOrPos | KeyOrPos[]
- ) {
+ this.#options.deprecatedOptions[option] = message;
+ return this;
+ }
+ describe(
+ keys: string | string[] | Dictionary,
+ description?: string
+ ): YargsInstance {
argsert(
- ' [number|string|array]',
- [key, value],
+ ' [string]',
+ [keys, description],
arguments.length
);
- validation.implies(key, value);
- return self;
- };
+ this[kSetKey](keys, true);
+ this.#usage.describe(keys, description);
+ return this;
+ }
+ detectLocale(detect: boolean): YargsInstance {
+ argsert('', [detect], arguments.length);
+ this.#detectLocale = detect;
+ return this;
+ }
+ // as long as options.envPrefix is not undefined,
+ // parser will apply env vars matching prefix to argv
+ env(prefix?: string | false): YargsInstance {
+ argsert('[string|boolean]', [prefix], arguments.length);
+ if (prefix === false) delete this.#options.envPrefix;
+ else this.#options.envPrefix = prefix || '';
+ return this;
+ }
+ epilogue(msg: string): YargsInstance {
+ argsert('', [msg], arguments.length);
+ this.#usage.epilog(msg);
+ return this;
+ }
+ epilog(msg: string): YargsInstance {
+ return this.epilogue(msg);
+ }
+ example(
+ cmd: string | [string, string?][],
+ description?: string
+ ): YargsInstance {
+ argsert(' [string]', [cmd, description], arguments.length);
- self.conflicts = function (
- key1: string | Dictionary,
- key2?: string | string[]
- ) {
- argsert(' [string|array]', [key1, key2], arguments.length);
- validation.conflicts(key1, key2);
- return self;
- };
-
- self.usage = function (
- msg: string | null,
- description?: CommandHandler['description'],
- builder?: CommandBuilderDefinition | CommandBuilder,
- handler?: CommandHandlerCallback
- ) {
- argsert(
- ' [string|boolean] [function|object] [function]',
- [msg, description, builder, handler],
- arguments.length
- );
-
- if (description !== undefined) {
- assertNotStrictEqual(msg, null, shim);
- // .usage() can be used as an alias for defining
- // a default command.
- if ((msg || '').match(/^\$0( |$)/)) {
- return self.command(msg, description, builder, handler);
- } else {
- throw new YError(
- '.usage() description must start with $0 if being used as alias for .command()'
- );
- }
+ if (Array.isArray(cmd)) {
+ cmd.forEach(exampleParams => this.example(...exampleParams));
} else {
- usage.usage(msg);
- return self;
+ this.#usage.example(cmd, description);
}
- };
-
- self.epilogue = self.epilog = function (msg) {
- argsert('', [msg], arguments.length);
- usage.epilog(msg);
- return self;
- };
- self.fail = function (f) {
+ return this;
+ }
+ // maybe exit, always capture context about why we wanted to exit:
+ exit(code: number, err?: YError | string): void {
+ this.#hasOutput = true;
+ this.#exitError = err;
+ if (this.#exitProcess) this.#shim.process.exit(code);
+ }
+ exitProcess(enabled = true): YargsInstance {
+ argsert('[boolean]', [enabled], arguments.length);
+ this.#exitProcess = enabled;
+ return this;
+ }
+ fail(f: FailureFunction | boolean): YargsInstance {
argsert('', [f], arguments.length);
if (typeof f === 'boolean' && f !== false) {
throw new YError(
"Invalid first argument. Expected function or boolean 'false'"
);
}
- usage.failFn(f);
- return self;
- };
-
- self.check = function (f, global) {
- argsert(' [boolean]', [f, global], arguments.length);
- self.middleware(
- (
- argv: Arguments,
- _yargs: YargsInstance
- ): Partial | Promise> => {
- return maybeAsyncResult<
- Partial | Promise> | any
- >(
- () => {
- return f(argv);
- },
- (result: any): Partial | Promise> => {
- if (!result) {
- usage.fail(y18n.__('Argument check failed: %s', f.toString()));
- } else if (typeof result === 'string' || result instanceof Error) {
- usage.fail(result.toString(), result);
- }
- return argv;
- },
- (err: Error): Partial | Promise> => {
- usage.fail(err.message ? err.message : err.toString(), err);
- return argv;
- }
+ this.#usage.failFn(f);
+ return this;
+ }
+ getAliases(): Dictionary {
+ return this.parsed ? this.parsed.aliases : {};
+ }
+ async getCompletion(
+ args: string[],
+ done?: (err: Error | null, completions: string[] | undefined) => void
+ ): Promise {
+ argsert(' [function]', [args, done], arguments.length);
+ if (!done) {
+ return new Promise((resolve, reject) => {
+ this.#completion!.getCompletion(args, (err, completions) => {
+ if (err) reject(err);
+ else resolve(completions);
+ });
+ });
+ } else {
+ return this.#completion!.getCompletion(args, done);
+ }
+ }
+ getDemandedOptions() {
+ argsert([], 0);
+ return this.#options.demandedOptions;
+ }
+ getDemandedCommands() {
+ argsert([], 0);
+ return this.#options.demandedCommands;
+ }
+ getDeprecatedOptions() {
+ argsert([], 0);
+ return this.#options.deprecatedOptions;
+ }
+ getDetectLocale(): boolean {
+ return this.#detectLocale;
+ }
+ getExitProcess(): boolean {
+ return this.#exitProcess;
+ }
+ // combine explicit and preserved groups. explicit groups should be first
+ getGroups(): Dictionary {
+ return Object.assign({}, this.#groups, this.#preservedGroups);
+ }
+ getHelp(): Promise {
+ this.#hasOutput = true;
+ if (!this.#usage.hasCachedHelpMessage()) {
+ if (!this.parsed) {
+ // Run the parser as if --help was passed to it (this is what
+ // the last parameter `true` indicates).
+ const parse = this[kRunYargsParserAndExecuteCommands](
+ this.#processArgs,
+ undefined,
+ undefined,
+ 0,
+ true
);
- },
- false,
- global
- );
- return self;
- };
-
- self.middleware = (
- callback: MiddlewareCallback | MiddlewareCallback[],
- applyBeforeValidation?: boolean,
- global = true
- ) => {
- return globalMiddleware.addMiddleware(
- callback,
- !!applyBeforeValidation,
- global
- );
- };
-
- self.global = function global(globals, global) {
+ if (isPromise(parse)) {
+ return parse.then(() => {
+ return this.#usage.help();
+ });
+ }
+ }
+ }
+ return Promise.resolve(this.#usage.help());
+ }
+ getOptions(): Options {
+ return this.#options;
+ }
+ getStrict(): boolean {
+ return this.#strict;
+ }
+ getStrictCommands(): boolean {
+ return this.#strictCommands;
+ }
+ getStrictOptions(): boolean {
+ return this.#strictOptions;
+ }
+ global(globals: string | string[], global?: boolean): YargsInstance {
argsert(' [boolean]', [globals, global], arguments.length);
globals = ([] as string[]).concat(globals);
if (global !== false) {
- options.local = options.local.filter(l => globals.indexOf(l) === -1);
+ this.#options.local = this.#options.local.filter(
+ l => globals.indexOf(l) === -1
+ );
} else {
globals.forEach(g => {
- if (options.local.indexOf(g) === -1) options.local.push(g);
+ if (this.#options.local.indexOf(g) === -1) this.#options.local.push(g);
});
}
- return self;
- };
-
- self.pkgConf = function pkgConf(key, rootPath) {
- argsert(' [string]', [key, rootPath], arguments.length);
- let conf = null;
- // prefer cwd to require-main-filename in this method
- // since we're looking for e.g. "nyc" config in nyc consumer
- // rather than "yargs" config in nyc (where nyc is the main filename)
- const obj = pkgUp(rootPath || cwd);
-
- // If an object exists in the key, add it to options.configObjects
- if (obj[key] && typeof obj[key] === 'object') {
- conf = applyExtends(
- obj[key],
- rootPath || cwd,
- self.getParserConfiguration()['deep-merge-config'] || false,
- shim
- );
- options.configObjects = (options.configObjects || []).concat(conf);
+ return this;
+ }
+ group(opts: string | string[], groupName: string): YargsInstance {
+ argsert(' ', [opts, groupName], arguments.length);
+ const existing =
+ this.#preservedGroups[groupName] || this.#groups[groupName];
+ if (this.#preservedGroups[groupName]) {
+ // we now only need to track this group name in groups.
+ delete this.#preservedGroups[groupName];
}
-
- return self;
- };
- const pkgs: Dictionary = {};
- function pkgUp(rootPath?: string) {
- const npath = rootPath || '*';
- if (pkgs[npath]) return pkgs[npath];
-
- let obj = {};
- try {
- let startDir = rootPath || shim.mainFilename;
-
- // When called in an environment that lacks require.main.filename, such as a jest test runner,
- // startDir is already process.cwd(), and should not be shortened.
- // Whether or not it is _actually_ a directory (e.g., extensionless bin) is irrelevant, find-up handles it.
- if (!rootPath && shim.path.extname(startDir)) {
- startDir = shim.path.dirname(startDir);
- }
-
- const pkgJsonPath = shim.findUp(
- startDir,
- (dir: string[], names: string[]) => {
- if (names.includes('package.json')) {
- return 'package.json';
- } else {
- return undefined;
- }
- }
- );
- assertNotStrictEqual(pkgJsonPath, undefined, shim);
- obj = JSON.parse(shim.readFileSync(pkgJsonPath, 'utf8'));
- // eslint-disable-next-line no-empty
- } catch (_noop) {}
-
- pkgs[npath] = obj || {};
- return pkgs[npath];
+ const seen: Dictionary = {};
+ this.#groups[groupName] = (existing || []).concat(opts).filter(key => {
+ if (seen[key]) return false;
+ return (seen[key] = true);
+ });
+ return this;
}
-
- let parseFn: ParseCallback | null = null;
- let parseContext: object | null = null;
- self.parse = function parse(
- args?: string | string[],
- shortCircuit?: object | ParseCallback | boolean,
- _parseFn?: ParseCallback
- ) {
+ hide(key: string): YargsInstance {
+ argsert('', [key], arguments.length);
+ this.#options.hiddenOptions.push(key);
+ return this;
+ }
+ implies(
+ key: string | Dictionary,
+ value?: KeyOrPos | KeyOrPos[]
+ ): YargsInstance {
argsert(
- '[string|array] [function|boolean|object] [function]',
- [args, shortCircuit, _parseFn],
+ ' [number|string|array]',
+ [key, value],
arguments.length
);
- freeze(); // Push current state of parser onto stack.
- if (typeof args === 'undefined') {
- const argv = self._parseArgs(processArgs);
- const tmpParsed = self.parsed;
- unfreeze(); // Pop the stack.
- self.parsed = tmpParsed;
- return argv;
- }
-
- // a context object can optionally be provided, this allows
- // additional information to be passed to a command handler.
- if (typeof shortCircuit === 'object') {
- parseContext = shortCircuit;
- shortCircuit = _parseFn;
- }
-
- // by providing a function as a second argument to
- // parse you can capture output that would otherwise
- // default to printing to stdout/stderr.
- if (typeof shortCircuit === 'function') {
- parseFn = shortCircuit as ParseCallback;
- shortCircuit = false;
+ this.#validation.implies(key, value);
+ return this;
+ }
+ locale(locale?: string): YargsInstance | string {
+ argsert('[string]', [locale], arguments.length);
+ if (!locale) {
+ this[kGuessLocale]();
+ return this.#shim.y18n.getLocale();
}
- // completion short-circuits the parsing process,
- // skipping validation, etc.
- if (!shortCircuit) processArgs = args;
-
- if (parseFn) exitProcess = false;
-
- const parsed = self._parseArgs(args, !!shortCircuit);
- completion!.setParsed(self.parsed as DetailedArguments);
- if (parseFn) parseFn(exitError, parsed, output);
- unfreeze(); // Pop the stack.
-
- return parsed;
- };
-
- self._getParseContext = () => parseContext || {};
-
- self._hasParseCallback = () => !!parseFn;
-
- self.option = self.options = function option(
+ this.#detectLocale = false;
+ this.#shim.y18n.setLocale(locale);
+ return this;
+ }
+ middleware(
+ callback: MiddlewareCallback | MiddlewareCallback[],
+ applyBeforeValidation?: boolean,
+ global?: boolean
+ ): YargsInstance {
+ return this.#globalMiddleware.addMiddleware(
+ callback,
+ !!applyBeforeValidation,
+ global
+ );
+ }
+ nargs(
+ key: string | string[] | Dictionary,
+ value?: number
+ ): YargsInstance {
+ argsert(' [number]', [key, value], arguments.length);
+ this[kPopulateParserHintSingleValueDictionary](
+ this.nargs.bind(this),
+ 'narg',
+ key,
+ value
+ );
+ return this;
+ }
+ normalize(keys: string | string[]): YargsInstance {
+ argsert('', [keys], arguments.length);
+ this[kPopulateParserHintArray]('normalize', keys);
+ return this;
+ }
+ number(keys: string | string[]): YargsInstance {
+ argsert('', [keys], arguments.length);
+ this[kPopulateParserHintArray]('number', keys);
+ return this;
+ }
+ option(
key: string | Dictionary,
opt?: OptionDefinition
- ) {
+ ): YargsInstance {
argsert(' [object]', [key, opt], arguments.length);
if (typeof key === 'object') {
Object.keys(key).forEach(k => {
- self.options(k, key[k]);
+ this.options(k, key[k]);
});
} else {
if (typeof opt !== 'object') {
opt = {};
}
- options.key[key] = true; // track manually set keys.
+ this.#options.key[key] = true; // track manually set keys.
- if (opt.alias) self.alias(key, opt.alias);
+ if (opt.alias) this.alias(key, opt.alias);
const deprecate = opt.deprecate || opt.deprecated;
if (deprecate) {
- self.deprecateOption(key, deprecate);
+ this.deprecateOption(key, deprecate);
}
const demand = opt.demand || opt.required || opt.require;
// A required option can be specified via "demand: true".
if (demand) {
- self.demand(key, demand);
+ this.demand(key, demand);
}
if (opt.demandOption) {
- self.demandOption(
+ this.demandOption(
key,
typeof opt.demandOption === 'string' ? opt.demandOption : undefined
);
}
if (opt.conflicts) {
- self.conflicts(key, opt.conflicts);
+ this.conflicts(key, opt.conflicts);
}
if ('default' in opt) {
- self.default(key, opt.default);
+ this.default(key, opt.default);
}
if (opt.implies !== undefined) {
- self.implies(key, opt.implies);
+ this.implies(key, opt.implies);
}
if (opt.nargs !== undefined) {
- self.nargs(key, opt.nargs);
+ this.nargs(key, opt.nargs);
}
if (opt.config) {
- self.config(key, opt.configParser);
+ this.config(key, opt.configParser);
}
if (opt.normalize) {
- self.normalize(key);
+ this.normalize(key);
}
if (opt.choices) {
- self.choices(key, opt.choices);
+ this.choices(key, opt.choices);
}
if (opt.coerce) {
- self.coerce(key, opt.coerce);
+ this.coerce(key, opt.coerce);
}
if (opt.group) {
- self.group(key, opt.group);
+ this.group(key, opt.group);
}
if (opt.boolean || opt.type === 'boolean') {
- self.boolean(key);
- if (opt.alias) self.boolean(opt.alias);
+ this.boolean(key);
+ if (opt.alias) this.boolean(opt.alias);
}
if (opt.array || opt.type === 'array') {
- self.array(key);
- if (opt.alias) self.array(opt.alias);
+ this.array(key);
+ if (opt.alias) this.array(opt.alias);
}
if (opt.number || opt.type === 'number') {
- self.number(key);
- if (opt.alias) self.number(opt.alias);
+ this.number(key);
+ if (opt.alias) this.number(opt.alias);
}
if (opt.string || opt.type === 'string') {
- self.string(key);
- if (opt.alias) self.string(opt.alias);
+ this.string(key);
+ if (opt.alias) this.string(opt.alias);
}
if (opt.count || opt.type === 'count') {
- self.count(key);
+ this.count(key);
}
if (typeof opt.global === 'boolean') {
- self.global(key, opt.global);
+ this.global(key, opt.global);
}
if (opt.defaultDescription) {
- options.defaultDescription[key] = opt.defaultDescription;
+ this.#options.defaultDescription[key] = opt.defaultDescription;
}
if (opt.skipValidation) {
- self.skipValidation(key);
+ this.skipValidation(key);
}
const desc = opt.describe || opt.description || opt.desc;
- self.describe(key, desc);
+ this.describe(key, desc);
if (opt.hidden) {
- self.hide(key);
+ this.hide(key);
}
if (opt.requiresArg) {
- self.requiresArg(key);
+ this.requiresArg(key);
}
}
- return self;
- };
- self.getOptions = () => options;
+ return this;
+ }
+ options(
+ key: string | Dictionary,
+ opt?: OptionDefinition
+ ): YargsInstance {
+ return this.option(key, opt);
+ }
+ parse(
+ args?: string | string[],
+ shortCircuit?: object | ParseCallback | boolean,
+ _parseFn?: ParseCallback
+ ): Arguments | Promise {
+ argsert(
+ '[string|array] [function|boolean|object] [function]',
+ [args, shortCircuit, _parseFn],
+ arguments.length
+ );
+ this[kFreeze](); // Push current state of parser onto stack.
+ if (typeof args === 'undefined') {
+ const argv = this[kRunYargsParserAndExecuteCommands](this.#processArgs);
+ const tmpParsed = this.parsed;
+ this[kUnfreeze](); // Pop the stack.
+ this.parsed = tmpParsed;
+ return argv;
+ }
- self.positional = function (key, opts) {
- argsert('