From 2db6defc0b555d93d2363ba6c6dfa19df7dc7c11 Mon Sep 17 00:00:00 2001 From: littleblack111 Date: Sat, 14 Oct 2023 16:27:06 +0800 Subject: update --- node_modules/commander/index.js | 3298 ++++++++++++++++----------------------- 1 file changed, 1365 insertions(+), 1933 deletions(-) (limited to 'node_modules/commander/index.js') diff --git a/node_modules/commander/index.js b/node_modules/commander/index.js index 985a8cfc..37d20cc5 100644 --- a/node_modules/commander/index.js +++ b/node_modules/commander/index.js @@ -2,499 +2,91 @@ * Module dependencies. */ -const EventEmitter = require('events').EventEmitter; -const childProcess = require('child_process'); -const path = require('path'); -const fs = require('fs'); - -// @ts-check - -// Although this is a class, methods are static in style to allow override using subclass or just functions. -class Help { - constructor() { - this.helpWidth = undefined; - this.sortSubcommands = false; - this.sortOptions = false; - } - - /** - * Get an array of the visible subcommands. Includes a placeholder for the implicit help command, if there is one. - * - * @param {Command} cmd - * @returns {Command[]} - */ - - visibleCommands(cmd) { - const visibleCommands = cmd.commands.filter(cmd => !cmd._hidden); - if (cmd._hasImplicitHelpCommand()) { - // Create a command matching the implicit help command. - const args = cmd._helpCommandnameAndArgs.split(/ +/); - const helpCommand = cmd.createCommand(args.shift()) - .helpOption(false); - helpCommand.description(cmd._helpCommandDescription); - helpCommand._parseExpectedArgs(args); - visibleCommands.push(helpCommand); - } - if (this.sortSubcommands) { - visibleCommands.sort((a, b) => { - return a.name().localeCompare(b.name()); - }); - } - return visibleCommands; - } - - /** - * Get an array of the visible options. Includes a placeholder for the implicit help option, if there is one. - * - * @param {Command} cmd - * @returns {Option[]} - */ - - visibleOptions(cmd) { - const visibleOptions = cmd.options.filter((option) => !option.hidden); - // Implicit help - const showShortHelpFlag = cmd._hasHelpOption && cmd._helpShortFlag && !cmd._findOption(cmd._helpShortFlag); - const showLongHelpFlag = cmd._hasHelpOption && !cmd._findOption(cmd._helpLongFlag); - if (showShortHelpFlag || showLongHelpFlag) { - let helpOption; - if (!showShortHelpFlag) { - helpOption = cmd.createOption(cmd._helpLongFlag, cmd._helpDescription); - } else if (!showLongHelpFlag) { - helpOption = cmd.createOption(cmd._helpShortFlag, cmd._helpDescription); - } else { - helpOption = cmd.createOption(cmd._helpFlags, cmd._helpDescription); - } - visibleOptions.push(helpOption); - } - if (this.sortOptions) { - const getSortKey = (option) => { - // WYSIWYG for order displayed in help with short before long, no special handling for negated. - return option.short ? option.short.replace(/^-/, '') : option.long.replace(/^--/, ''); - }; - visibleOptions.sort((a, b) => { - return getSortKey(a).localeCompare(getSortKey(b)); - }); - } - return visibleOptions; - } - - /** - * Get an array of the arguments which have descriptions. - * - * @param {Command} cmd - * @returns {{ term: string, description:string }[]} - */ - - visibleArguments(cmd) { - if (cmd._argsDescription && cmd._args.length) { - return cmd._args.map((argument) => { - return { term: argument.name, description: cmd._argsDescription[argument.name] || '' }; - }, 0); - } - return []; - } - - /** - * Get the command term to show in the list of subcommands. - * - * @param {Command} cmd - * @returns {string} - */ - - subcommandTerm(cmd) { - // Legacy. Ignores custom usage string, and nested commands. - const args = cmd._args.map(arg => humanReadableArgName(arg)).join(' '); - return cmd._name + - (cmd._aliases[0] ? '|' + cmd._aliases[0] : '') + - (cmd.options.length ? ' [options]' : '') + // simplistic check for non-help option - (args ? ' ' + args : ''); - } - - /** - * Get the option term to show in the list of options. - * - * @param {Option} option - * @returns {string} - */ - - optionTerm(option) { - return option.flags; - } - - /** - * Get the longest command term length. - * - * @param {Command} cmd - * @param {Help} helper - * @returns {number} - */ - - longestSubcommandTermLength(cmd, helper) { - return helper.visibleCommands(cmd).reduce((max, command) => { - return Math.max(max, helper.subcommandTerm(command).length); - }, 0); - }; - - /** - * Get the longest option term length. - * - * @param {Command} cmd - * @param {Help} helper - * @returns {number} - */ - - longestOptionTermLength(cmd, helper) { - return helper.visibleOptions(cmd).reduce((max, option) => { - return Math.max(max, helper.optionTerm(option).length); - }, 0); - }; - - /** - * Get the longest argument term length. - * - * @param {Command} cmd - * @param {Help} helper - * @returns {number} - */ - - longestArgumentTermLength(cmd, helper) { - return helper.visibleArguments(cmd).reduce((max, argument) => { - return Math.max(max, argument.term.length); - }, 0); - }; - - /** - * Get the command usage to be displayed at the top of the built-in help. - * - * @param {Command} cmd - * @returns {string} - */ - - commandUsage(cmd) { - // Usage - let cmdName = cmd._name; - if (cmd._aliases[0]) { - cmdName = cmdName + '|' + cmd._aliases[0]; - } - let parentCmdNames = ''; - for (let parentCmd = cmd.parent; parentCmd; parentCmd = parentCmd.parent) { - parentCmdNames = parentCmd.name() + ' ' + parentCmdNames; - } - return parentCmdNames + cmdName + ' ' + cmd.usage(); - } - - /** - * Get the description for the command. - * - * @param {Command} cmd - * @returns {string} - */ - - commandDescription(cmd) { - // @ts-ignore: overloaded return type - return cmd.description(); - } - - /** - * Get the command description to show in the list of subcommands. - * - * @param {Command} cmd - * @returns {string} - */ - - subcommandDescription(cmd) { - // @ts-ignore: overloaded return type - return cmd.description(); - } - - /** - * Get the option description to show in the list of options. - * - * @param {Option} option - * @return {string} - */ - - optionDescription(option) { - if (option.negate) { - return option.description; - } - const extraInfo = []; - if (option.argChoices) { - extraInfo.push( - // use stringify to match the display of the default value - `choices: ${option.argChoices.map((choice) => JSON.stringify(choice)).join(', ')}`); - } - if (option.defaultValue !== undefined) { - extraInfo.push(`default: ${option.defaultValueDescription || JSON.stringify(option.defaultValue)}`); - } - if (extraInfo.length > 0) { - return `${option.description} (${extraInfo.join(', ')})`; - } - return option.description; - }; - - /** - * Generate the built-in help text. - * - * @param {Command} cmd - * @param {Help} helper - * @returns {string} - */ - - formatHelp(cmd, helper) { - const termWidth = helper.padWidth(cmd, helper); - const helpWidth = helper.helpWidth || 80; - const itemIndentWidth = 2; - const itemSeparatorWidth = 2; // between term and description - function formatItem(term, description) { - if (description) { - const fullText = `${term.padEnd(termWidth + itemSeparatorWidth)}${description}`; - return helper.wrap(fullText, helpWidth - itemIndentWidth, termWidth + itemSeparatorWidth); - } - return term; - }; - function formatList(textArray) { - return textArray.join('\n').replace(/^/gm, ' '.repeat(itemIndentWidth)); - } +var EventEmitter = require('events').EventEmitter; +var spawn = require('child_process').spawn; +var path = require('path'); +var dirname = path.dirname; +var basename = path.basename; +var fs = require('fs'); - // Usage - let output = [`Usage: ${helper.commandUsage(cmd)}`, '']; +/** + * Inherit `Command` from `EventEmitter.prototype`. + */ - // Description - const commandDescription = helper.commandDescription(cmd); - if (commandDescription.length > 0) { - output = output.concat([commandDescription, '']); - } +require('util').inherits(Command, EventEmitter); - // Arguments - const argumentList = helper.visibleArguments(cmd).map((argument) => { - return formatItem(argument.term, argument.description); - }); - if (argumentList.length > 0) { - output = output.concat(['Arguments:', formatList(argumentList), '']); - } +/** + * Expose the root command. + */ - // Options - const optionList = helper.visibleOptions(cmd).map((option) => { - return formatItem(helper.optionTerm(option), helper.optionDescription(option)); - }); - if (optionList.length > 0) { - output = output.concat(['Options:', formatList(optionList), '']); - } +exports = module.exports = new Command(); - // Commands - const commandList = helper.visibleCommands(cmd).map((cmd) => { - return formatItem(helper.subcommandTerm(cmd), helper.subcommandDescription(cmd)); - }); - if (commandList.length > 0) { - output = output.concat(['Commands:', formatList(commandList), '']); - } +/** + * Expose `Command`. + */ - return output.join('\n'); - } +exports.Command = Command; - /** - * Calculate the pad width from the maximum term length. - * - * @param {Command} cmd - * @param {Help} helper - * @returns {number} - */ +/** + * Expose `Option`. + */ - padWidth(cmd, helper) { - return Math.max( - helper.longestOptionTermLength(cmd, helper), - helper.longestSubcommandTermLength(cmd, helper), - helper.longestArgumentTermLength(cmd, helper) - ); - }; +exports.Option = Option; - /** - * Wrap the given string to width characters per line, with lines after the first indented. - * Do not wrap if insufficient room for wrapping (minColumnWidth), or string is manually formatted. - * - * @param {string} str - * @param {number} width - * @param {number} indent - * @param {number} [minColumnWidth=40] - * @return {string} - * - */ +/** + * Initialize a new `Option` with the given `flags` and `description`. + * + * @param {String} flags + * @param {String} description + * @api public + */ - wrap(str, width, indent, minColumnWidth = 40) { - // Detect manually wrapped and indented strings by searching for line breaks - // followed by multiple spaces/tabs. - if (str.match(/[\n]\s+/)) return str; - // Do not wrap if not enough room for a wrapped column of text (as could end up with a word per line). - const columnWidth = width - indent; - if (columnWidth < minColumnWidth) return str; - - const leadingStr = str.substr(0, indent); - const columnText = str.substr(indent); - - const indentString = ' '.repeat(indent); - const regex = new RegExp('.{1,' + (columnWidth - 1) + '}([\\s\u200B]|$)|[^\\s\u200B]+?([\\s\u200B]|$)', 'g'); - const lines = columnText.match(regex) || []; - return leadingStr + lines.map((line, i) => { - if (line.slice(-1) === '\n') { - line = line.slice(0, line.length - 1); - } - return ((i > 0) ? indentString : '') + line.trimRight(); - }).join('\n'); - } +function Option(flags, description) { + this.flags = flags; + this.required = flags.indexOf('<') >= 0; // A value must be supplied when the option is specified. + this.optional = flags.indexOf('[') >= 0; // A value is optional when the option is specified. + this.mandatory = false; // The option must have a value after parsing, which usually means it must be specified on command line. + this.negate = flags.indexOf('-no-') !== -1; + flags = flags.split(/[ ,|]+/); + if (flags.length > 1 && !/^[[<]/.test(flags[1])) this.short = flags.shift(); + this.long = flags.shift(); + this.description = description || ''; } -class Option { - /** - * Initialize a new `Option` with the given `flags` and `description`. - * - * @param {string} flags - * @param {string} [description] - */ - - constructor(flags, description) { - this.flags = flags; - this.description = description || ''; - - this.required = flags.includes('<'); // A value must be supplied when the option is specified. - this.optional = flags.includes('['); // A value is optional when the option is specified. - // variadic test ignores et al which might be used to describe custom splitting of single argument - this.variadic = /\w\.\.\.[>\]]$/.test(flags); // The option can take multiple values. - this.mandatory = false; // The option must have a value after parsing, which usually means it must be specified on command line. - const optionFlags = _parseOptionFlags(flags); - this.short = optionFlags.shortFlag; - this.long = optionFlags.longFlag; - this.negate = false; - if (this.long) { - this.negate = this.long.startsWith('--no-'); - } - this.defaultValue = undefined; - this.defaultValueDescription = undefined; - this.parseArg = undefined; - this.hidden = false; - this.argChoices = undefined; - } - - /** - * Set the default value, and optionally supply the description to be displayed in the help. - * - * @param {any} value - * @param {string} [description] - * @return {Option} - */ - - default(value, description) { - this.defaultValue = value; - this.defaultValueDescription = description; - return this; - }; - - /** - * Set the custom handler for processing CLI option arguments into option values. - * - * @param {Function} [fn] - * @return {Option} - */ - - argParser(fn) { - this.parseArg = fn; - return this; - }; - - /** - * Whether the option is mandatory and must have a value after parsing. - * - * @param {boolean} [mandatory=true] - * @return {Option} - */ - - makeOptionMandatory(mandatory = true) { - this.mandatory = !!mandatory; - return this; - }; - - /** - * Hide option in help. - * - * @param {boolean} [hide=true] - * @return {Option} - */ - - hideHelp(hide = true) { - this.hidden = !!hide; - return this; - }; - - /** - * @api private - */ - - _concatValue(value, previous) { - if (previous === this.defaultValue || !Array.isArray(previous)) { - return [value]; - } - - return previous.concat(value); - } - - /** - * Only allow option value to be one of choices. - * - * @param {string[]} values - * @return {Option} - */ - - choices(values) { - this.argChoices = values; - this.parseArg = (arg, previous) => { - if (!values.includes(arg)) { - throw new InvalidOptionArgumentError(`Allowed choices are ${values.join(', ')}.`); - } - if (this.variadic) { - return this._concatValue(arg, previous); - } - return arg; - }; - return this; - }; - - /** - * Return option name. - * - * @return {string} - */ +/** + * Return option name. + * + * @return {String} + * @api private + */ - name() { - if (this.long) { - return this.long.replace(/^--/, ''); - } - return this.short.replace(/^-/, ''); - }; +Option.prototype.name = function() { + return this.long.replace(/^--/, ''); +}; - /** - * Return option name, in a camelcase format that can be used - * as a object attribute key. - * - * @return {string} - * @api private - */ +/** + * Return option name, in a camelcase format that can be used + * as a object attribute key. + * + * @return {String} + * @api private + */ - attributeName() { - return camelcase(this.name().replace(/^no-/, '')); - }; +Option.prototype.attributeName = function() { + return camelcase(this.name().replace(/^no-/, '')); +}; - /** - * Check if `arg` matches the short or long flag. - * - * @param {string} arg - * @return {boolean} - * @api private - */ +/** + * Check if `arg` matches the short or long flag. + * + * @param {String} arg + * @return {Boolean} + * @api private + */ - is(arg) { - return this.short === arg || this.long === arg; - }; -} +Option.prototype.is = function(arg) { + return this.short === arg || this.long === arg; +}; /** * CommanderError class @@ -503,9 +95,9 @@ class Option { class CommanderError extends Error { /** * Constructs the CommanderError class - * @param {number} exitCode suggested exit code which could be used with process.exit - * @param {string} code an id string representing the error - * @param {string} message human-readable description of the error + * @param {Number} exitCode suggested exit code which could be used with process.exit + * @param {String} code an id string representing the error + * @param {String} message human-readable description of the error * @constructor */ constructor(exitCode, code, message) { @@ -515,1619 +107,1470 @@ class CommanderError extends Error { this.name = this.constructor.name; this.code = code; this.exitCode = exitCode; - this.nestedError = undefined; } } +exports.CommanderError = CommanderError; + /** - * InvalidOptionArgumentError class - * @class + * Initialize a new `Command`. + * + * @param {String} [name] + * @api public */ -class InvalidOptionArgumentError extends CommanderError { - /** - * Constructs the InvalidOptionArgumentError class - * @param {string} [message] explanation of why argument is invalid - * @constructor - */ - constructor(message) { - super(1, 'commander.invalidOptionArgument', message); - // properly capture stack trace in Node.js - Error.captureStackTrace(this, this.constructor); - this.name = this.constructor.name; - } -} -class Command extends EventEmitter { - /** - * Initialize a new `Command`. - * - * @param {string} [name] - */ - - constructor(name) { - super(); - this.commands = []; - this.options = []; - this.parent = null; - this._allowUnknownOption = false; - this._allowExcessArguments = true; - this._args = []; - this.rawArgs = null; - this._scriptPath = null; - this._name = name || ''; - this._optionValues = {}; - this._storeOptionsAsProperties = false; - this._actionResults = []; - this._actionHandler = null; - this._executableHandler = false; - this._executableFile = null; // custom name for executable - this._defaultCommandName = null; - this._exitCallback = null; - this._aliases = []; - this._combineFlagAndOptionalValue = true; - this._description = ''; - this._argsDescription = undefined; - this._enablePositionalOptions = false; - this._passThroughOptions = false; - - // see .configureOutput() for docs - this._outputConfiguration = { - writeOut: (str) => process.stdout.write(str), - writeErr: (str) => process.stderr.write(str), - getOutHelpWidth: () => process.stdout.isTTY ? process.stdout.columns : undefined, - getErrHelpWidth: () => process.stderr.isTTY ? process.stderr.columns : undefined, - outputError: (str, write) => write(str) - }; - - this._hidden = false; - this._hasHelpOption = true; - this._helpFlags = '-h, --help'; - this._helpDescription = 'display help for command'; - this._helpShortFlag = '-h'; - this._helpLongFlag = '--help'; - this._addImplicitHelpCommand = undefined; // Deliberately undefined, not decided whether true or false - this._helpCommandName = 'help'; - this._helpCommandnameAndArgs = 'help [command]'; - this._helpCommandDescription = 'display help for command'; - this._helpConfiguration = {}; - } - - /** - * Define a command. - * - * There are two styles of command: pay attention to where to put the description. - * - * Examples: - * - * // Command implemented using action handler (description is supplied separately to `.command`) - * program - * .command('clone [destination]') - * .description('clone a repository into a newly created directory') - * .action((source, destination) => { - * console.log('clone command called'); - * }); - * - * // Command implemented using separate executable file (description is second parameter to `.command`) - * program - * .command('start ', 'start named service') - * .command('stop [service]', 'stop named service, or all if no name supplied'); - * - * @param {string} nameAndArgs - command name and arguments, args are `` or `[optional]` and last may also be `variadic...` - * @param {Object|string} [actionOptsOrExecDesc] - configuration options (for action), or description (for executable) - * @param {Object} [execOpts] - configuration options (for executable) - * @return {Command} returns new command for action handler, or `this` for executable command - */ - - command(nameAndArgs, actionOptsOrExecDesc, execOpts) { - let desc = actionOptsOrExecDesc; - let opts = execOpts; - if (typeof desc === 'object' && desc !== null) { - opts = desc; - desc = null; - } - opts = opts || {}; - const args = nameAndArgs.split(/ +/); - const cmd = this.createCommand(args.shift()); - - if (desc) { - cmd.description(desc); - cmd._executableHandler = true; - } - if (opts.isDefault) this._defaultCommandName = cmd._name; - - cmd._outputConfiguration = this._outputConfiguration; - - cmd._hidden = !!(opts.noHelp || opts.hidden); // noHelp is deprecated old name for hidden - cmd._hasHelpOption = this._hasHelpOption; - cmd._helpFlags = this._helpFlags; - cmd._helpDescription = this._helpDescription; - cmd._helpShortFlag = this._helpShortFlag; - cmd._helpLongFlag = this._helpLongFlag; - cmd._helpCommandName = this._helpCommandName; - cmd._helpCommandnameAndArgs = this._helpCommandnameAndArgs; - cmd._helpCommandDescription = this._helpCommandDescription; - cmd._helpConfiguration = this._helpConfiguration; - cmd._exitCallback = this._exitCallback; - cmd._storeOptionsAsProperties = this._storeOptionsAsProperties; - cmd._combineFlagAndOptionalValue = this._combineFlagAndOptionalValue; - cmd._allowExcessArguments = this._allowExcessArguments; - cmd._enablePositionalOptions = this._enablePositionalOptions; - - cmd._executableFile = opts.executableFile || null; // Custom name for executable file, set missing to null to match constructor - this.commands.push(cmd); - cmd._parseExpectedArgs(args); - cmd.parent = this; - - if (desc) return this; - return cmd; - }; - - /** - * Factory routine to create a new unattached command. - * - * See .command() for creating an attached subcommand, which uses this routine to - * create the command. You can override createCommand to customise subcommands. - * - * @param {string} [name] - * @return {Command} new command - */ - - createCommand(name) { - return new Command(name); - }; - - /** - * You can customise the help with a subclass of Help by overriding createHelp, - * or by overriding Help properties using configureHelp(). - * - * @return {Help} - */ - - createHelp() { - return Object.assign(new Help(), this.configureHelp()); - }; - - /** - * You can customise the help by overriding Help properties using configureHelp(), - * or with a subclass of Help by overriding createHelp(). - * - * @param {Object} [configuration] - configuration options - * @return {Command|Object} `this` command for chaining, or stored configuration - */ +function Command(name) { + this.commands = []; + this.options = []; + this._execs = new Set(); + this._allowUnknownOption = false; + this._args = []; + this._name = name || ''; + this._optionValues = {}; + this._storeOptionsAsProperties = true; // backwards compatible by default + this._passCommandToAction = true; // backwards compatible by default + this._actionResults = []; + + this._helpFlags = '-h, --help'; + this._helpDescription = 'output usage information'; + this._helpShortFlag = '-h'; + this._helpLongFlag = '--help'; +} - configureHelp(configuration) { - if (configuration === undefined) return this._helpConfiguration; +/** + * Define a command. + * + * There are two styles of command: pay attention to where to put the description. + * + * Examples: + * + * // Command implemented using action handler (description is supplied separately to `.command`) + * program + * .command('clone [destination]') + * .description('clone a repository into a newly created directory') + * .action((source, destination) => { + * console.log('clone command called'); + * }); + * + * // Command implemented using separate executable file (description is second parameter to `.command`) + * program + * .command('start ', 'start named service') + * .command('stop [service]', 'stop named service, or all if no name supplied'); + * + * @param {string} nameAndArgs - command name and arguments, args are `` or `[optional]` and last may also be `variadic...` + * @param {Object|string} [actionOptsOrExecDesc] - configuration options (for action), or description (for executable) + * @param {Object} [execOpts] - configuration options (for executable) + * @return {Command} returns new command for action handler, or top-level command for executable command + * @api public + */ - this._helpConfiguration = configuration; - return this; +Command.prototype.command = function(nameAndArgs, actionOptsOrExecDesc, execOpts) { + var desc = actionOptsOrExecDesc; + var opts = execOpts; + if (typeof desc === 'object' && desc !== null) { + opts = desc; + desc = null; } - - /** - * The default output goes to stdout and stderr. You can customise this for special - * applications. You can also customise the display of errors by overriding outputError. - * - * The configuration properties are all functions: - * - * // functions to change where being written, stdout and stderr - * writeOut(str) - * writeErr(str) - * // matching functions to specify width for wrapping help - * getOutHelpWidth() - * getErrHelpWidth() - * // functions based on what is being written out - * outputError(str, write) // used for displaying errors, and not used for displaying help - * - * @param {Object} [configuration] - configuration options - * @return {Command|Object} `this` command for chaining, or stored configuration - */ - - configureOutput(configuration) { - if (configuration === undefined) return this._outputConfiguration; - - Object.assign(this._outputConfiguration, configuration); - return this; + opts = opts || {}; + var args = nameAndArgs.split(/ +/); + var cmd = new Command(args.shift()); + + if (desc) { + cmd.description(desc); + this.executables = true; + this._execs.add(cmd._name); + if (opts.isDefault) this.defaultExecutable = cmd._name; } + cmd._noHelp = !!opts.noHelp; + cmd._helpFlags = this._helpFlags; + cmd._helpDescription = this._helpDescription; + cmd._helpShortFlag = this._helpShortFlag; + cmd._helpLongFlag = this._helpLongFlag; + cmd._exitCallback = this._exitCallback; + cmd._storeOptionsAsProperties = this._storeOptionsAsProperties; + cmd._passCommandToAction = this._passCommandToAction; + + cmd._executableFile = opts.executableFile; // Custom name for executable file + this.commands.push(cmd); + cmd.parseExpectedArgs(args); + cmd.parent = this; + + if (desc) return this; + return cmd; +}; - /** - * Add a prepared subcommand. - * - * See .command() for creating an attached subcommand which inherits settings from its parent. - * - * @param {Command} cmd - new subcommand - * @param {Object} [opts] - configuration options - * @return {Command} `this` command for chaining - */ - - addCommand(cmd, opts) { - if (!cmd._name) throw new Error('Command passed to .addCommand() must have a name'); - - // To keep things simple, block automatic name generation for deeply nested executables. - // Fail fast and detect when adding rather than later when parsing. - function checkExplicitNames(commandArray) { - commandArray.forEach((cmd) => { - if (cmd._executableHandler && !cmd._executableFile) { - throw new Error(`Must specify executableFile for deeply nested executable: ${cmd.name()}`); - } - checkExplicitNames(cmd.commands); - }); - } - checkExplicitNames(cmd.commands); +/** + * Define argument syntax for the top-level command. + * + * @api public + */ - opts = opts || {}; - if (opts.isDefault) this._defaultCommandName = cmd._name; - if (opts.noHelp || opts.hidden) cmd._hidden = true; // modifying passed command due to existing implementation +Command.prototype.arguments = function(desc) { + return this.parseExpectedArgs(desc.split(/ +/)); +}; - this.commands.push(cmd); - cmd.parent = this; - return this; - }; +/** + * Add an implicit `help [cmd]` subcommand + * which invokes `--help` for the given command. + * + * @api private + */ - /** - * Define argument syntax for the command. - */ +Command.prototype.addImplicitHelpCommand = function() { + this.command('help [cmd]', 'display help for [cmd]'); +}; - arguments(desc) { - return this._parseExpectedArgs(desc.split(/ +/)); - }; +/** + * Parse expected `args`. + * + * For example `["[type]"]` becomes `[{ required: false, name: 'type' }]`. + * + * @param {Array} args + * @return {Command} for chaining + * @api public + */ - /** - * Override default decision whether to add implicit help command. - * - * addHelpCommand() // force on - * addHelpCommand(false); // force off - * addHelpCommand('help [cmd]', 'display help for [cmd]'); // force on with custom details - * - * @return {Command} `this` command for chaining - */ +Command.prototype.parseExpectedArgs = function(args) { + if (!args.length) return; + var self = this; + args.forEach(function(arg) { + var argDetails = { + required: false, + name: '', + variadic: false + }; - addHelpCommand(enableOrNameAndArgs, description) { - if (enableOrNameAndArgs === false) { - this._addImplicitHelpCommand = false; - } else { - this._addImplicitHelpCommand = true; - if (typeof enableOrNameAndArgs === 'string') { - this._helpCommandName = enableOrNameAndArgs.split(' ')[0]; - this._helpCommandnameAndArgs = enableOrNameAndArgs; - } - this._helpCommandDescription = description || this._helpCommandDescription; + switch (arg[0]) { + case '<': + argDetails.required = true; + argDetails.name = arg.slice(1, -1); + break; + case '[': + argDetails.name = arg.slice(1, -1); + break; } - return this; - }; - - /** - * @return {boolean} - * @api private - */ - _hasImplicitHelpCommand() { - if (this._addImplicitHelpCommand === undefined) { - return this.commands.length && !this._actionHandler && !this._findCommand('help'); + if (argDetails.name.length > 3 && argDetails.name.slice(-3) === '...') { + argDetails.variadic = true; + argDetails.name = argDetails.name.slice(0, -3); } - return this._addImplicitHelpCommand; - }; - - /** - * Parse expected `args`. - * - * For example `["[type]"]` becomes `[{ required: false, name: 'type' }]`. - * - * @param {Array} args - * @return {Command} `this` command for chaining - * @api private - */ - - _parseExpectedArgs(args) { - if (!args.length) return; - args.forEach((arg) => { - const argDetails = { - required: false, - name: '', - variadic: false - }; + if (argDetails.name) { + self._args.push(argDetails); + } + }); + return this; +}; - switch (arg[0]) { - case '<': - argDetails.required = true; - argDetails.name = arg.slice(1, -1); - break; - case '[': - argDetails.name = arg.slice(1, -1); - break; - } +/** + * Register callback to use as replacement for calling process.exit. + * + * @param {Function} [fn] optional callback which will be passed a CommanderError, defaults to throwing + * @return {Command} for chaining + * @api public + */ - if (argDetails.name.length > 3 && argDetails.name.slice(-3) === '...') { - argDetails.variadic = true; - argDetails.name = argDetails.name.slice(0, -3); - } - if (argDetails.name) { - this._args.push(argDetails); - } - }); - this._args.forEach((arg, i) => { - if (arg.variadic && i < this._args.length - 1) { - throw new Error(`only the last argument can be variadic '${arg.name}'`); +Command.prototype.exitOverride = function(fn) { + if (fn) { + this._exitCallback = fn; + } else { + this._exitCallback = function(err) { + if (err.code !== 'commander.executeSubCommandAsync') { + throw err; + } else { + // Async callback from spawn events, not useful to throw. } - }); - return this; - }; - - /** - * Register callback to use as replacement for calling process.exit. - * - * @param {Function} [fn] optional callback which will be passed a CommanderError, defaults to throwing - * @return {Command} `this` command for chaining - */ - - exitOverride(fn) { - if (fn) { - this._exitCallback = fn; - } else { - this._exitCallback = (err) => { - if (err.code !== 'commander.executeSubCommandAsync') { - throw err; - } else { - // Async callback from spawn events, not useful to throw. - } - }; - } - return this; - }; - - /** - * Call process.exit, and _exitCallback if defined. - * - * @param {number} exitCode exit code for using with process.exit - * @param {string} code an id string representing the error - * @param {string} message human-readable description of the error - * @return never - * @api private - */ + }; + } + return this; +}; - _exit(exitCode, code, message) { - if (this._exitCallback) { - this._exitCallback(new CommanderError(exitCode, code, message)); - // Expecting this line is not reached. - } - process.exit(exitCode); - }; +/** + * Call process.exit, and _exitCallback if defined. + * + * @param {Number} exitCode exit code for using with process.exit + * @param {String} code an id string representing the error + * @param {String} message human-readable description of the error + * @return never + * @api private + */ - /** - * Register callback `fn` for the command. - * - * Examples: - * - * program - * .command('help') - * .description('display verbose help') - * .action(function() { - * // output help here - * }); - * - * @param {Function} fn - * @return {Command} `this` command for chaining - */ +Command.prototype._exit = function(exitCode, code, message) { + if (this._exitCallback) { + this._exitCallback(new CommanderError(exitCode, code, message)); + // Expecting this line is not reached. + } + process.exit(exitCode); +}; - action(fn) { - const listener = (args) => { - // The .action callback takes an extra parameter which is the command or options. - const expectedArgsCount = this._args.length; - const actionArgs = args.slice(0, expectedArgsCount); - if (this._storeOptionsAsProperties) { - actionArgs[expectedArgsCount] = this; // backwards compatible "options" - } else { - actionArgs[expectedArgsCount] = this.opts(); - } - actionArgs.push(this); +/** + * Register callback `fn` for the command. + * + * Examples: + * + * program + * .command('help') + * .description('display verbose help') + * .action(function() { + * // output help here + * }); + * + * @param {Function} fn + * @return {Command} for chaining + * @api public + */ - const actionResult = fn.apply(this, actionArgs); - // Remember result in case it is async. Assume parseAsync getting called on root. - let rootCommand = this; - while (rootCommand.parent) { - rootCommand = rootCommand.parent; - } - rootCommand._actionResults.push(actionResult); - }; - this._actionHandler = listener; - return this; - }; +Command.prototype.action = function(fn) { + var self = this; + var listener = function(args, unknown) { + // Parse any so-far unknown options + args = args || []; + unknown = unknown || []; - /** - * Factory routine to create a new unattached option. - * - * See .option() for creating an attached option, which uses this routine to - * create the option. You can override createOption to return a custom option. - * - * @param {string} flags - * @param {string} [description] - * @return {Option} new option - */ + var parsed = self.parseOptions(unknown); - createOption(flags, description) { - return new Option(flags, description); - }; + // Output help if necessary + outputHelpIfRequested(self, parsed.unknown); + self._checkForMissingMandatoryOptions(); - /** - * Add an option. - * - * @param {Option} option - * @return {Command} `this` command for chaining - */ - addOption(option) { - const oname = option.name(); - const name = option.attributeName(); - - let defaultValue = option.defaultValue; - - // preassign default value for --no-*, [optional], , or plain flag if boolean value - if (option.negate || option.optional || option.required || typeof defaultValue === 'boolean') { - // when --no-foo we make sure default is true, unless a --foo option is already defined - if (option.negate) { - const positiveLongFlag = option.long.replace(/^--no-/, '--'); - defaultValue = this._findOption(positiveLongFlag) ? this._getOptionValue(name) : true; - } - // preassign only if we have a default - if (defaultValue !== undefined) { - this._setOptionValue(name, defaultValue); - } + // If there are still any unknown options, then we simply + // die, unless someone asked for help, in which case we give it + // to them, and then we die. + if (parsed.unknown.length > 0) { + self.unknownOption(parsed.unknown[0]); } - // register the option - this.options.push(option); - - // when it's passed assign the value - // and conditionally invoke the callback - this.on('option:' + oname, (val) => { - const oldValue = this._getOptionValue(name); - - // custom processing - if (val !== null && option.parseArg) { - try { - val = option.parseArg(val, oldValue === undefined ? defaultValue : oldValue); - } catch (err) { - if (err.code === 'commander.invalidOptionArgument') { - const message = `error: option '${option.flags}' argument '${val}' is invalid. ${err.message}`; - this._displayError(err.exitCode, err.code, message); - } - throw err; - } - } else if (val !== null && option.variadic) { - val = option._concatValue(val, oldValue); - } + // Leftover arguments need to be pushed back. Fixes issue #56 + if (parsed.args.length) args = parsed.args.concat(args); - // unassigned or boolean value - if (typeof oldValue === 'boolean' || typeof oldValue === 'undefined') { - // if no value, negate false, and we have a default, then use it! - if (val == null) { - this._setOptionValue(name, option.negate - ? false - : defaultValue || true); - } else { - this._setOptionValue(name, val); + self._args.forEach(function(arg, i) { + if (arg.required && args[i] == null) { + self.missingArgument(arg.name); + } else if (arg.variadic) { + if (i !== self._args.length - 1) { + self.variadicArgNotLast(arg.name); } - } else if (val !== null) { - // reassign - this._setOptionValue(name, option.negate ? false : val); + + args[i] = args.splice(i); } }); - return this; - } + // The .action callback takes an extra parameter which is the command itself. + var expectedArgsCount = self._args.length; + var actionArgs = args.slice(0, expectedArgsCount); + if (self._passCommandToAction) { + actionArgs[expectedArgsCount] = self; + } else { + actionArgs[expectedArgsCount] = self.opts(); + } + // Add the extra arguments so available too. + if (args.length > expectedArgsCount) { + actionArgs.push(args.slice(expectedArgsCount)); + } - /** - * Internal implementation shared by .option() and .requiredOption() - * - * @api private - */ - _optionEx(config, flags, description, fn, defaultValue) { - const option = this.createOption(flags, description); - option.makeOptionMandatory(!!config.mandatory); - if (typeof fn === 'function') { - option.default(defaultValue).argParser(fn); - } else if (fn instanceof RegExp) { - // deprecated - const regex = fn; - fn = (val, def) => { - const m = regex.exec(val); + const actionResult = fn.apply(self, actionArgs); + // Remember result in case it is async. Assume parseAsync getting called on root. + let rootCommand = self; + while (rootCommand.parent) { + rootCommand = rootCommand.parent; + } + rootCommand._actionResults.push(actionResult); + }; + var parent = this.parent || this; + var name = parent === this ? '*' : this._name; + parent.on('command:' + name, listener); + if (this._alias) parent.on('command:' + this._alias, listener); + return this; +}; + +/** + * Internal implementation shared by .option() and .requiredOption() + * + * @param {Object} config + * @param {String} flags + * @param {String} description + * @param {Function|*} [fn] - custom option processing function or default vaue + * @param {*} [defaultValue] + * @return {Command} for chaining + * @api private + */ + +Command.prototype._optionEx = function(config, flags, description, fn, defaultValue) { + var self = this, + option = new Option(flags, description), + oname = option.name(), + name = option.attributeName(); + option.mandatory = !!config.mandatory; + + // default as 3rd arg + if (typeof fn !== 'function') { + if (fn instanceof RegExp) { + // This is a bit simplistic (especially no error messages), and probably better handled by caller using custom option processing. + // No longer documented in README, but still present for backwards compatibility. + var regex = fn; + fn = function(val, def) { + var m = regex.exec(val); return m ? m[0] : def; }; - option.default(defaultValue).argParser(fn); } else { - option.default(fn); + defaultValue = fn; + fn = null; } + } - return this.addOption(option); + // preassign default value for --no-*, [optional], , or plain flag if boolean value + if (option.negate || option.optional || option.required || typeof defaultValue === 'boolean') { + // when --no-foo we make sure default is true, unless a --foo option is already defined + if (option.negate) { + const positiveLongFlag = option.long.replace(/^--no-/, '--'); + defaultValue = self.optionFor(positiveLongFlag) ? self._getOptionValue(name) : true; + } + // preassign only if we have a default + if (defaultValue !== undefined) { + self._setOptionValue(name, defaultValue); + option.defaultValue = defaultValue; + } } - /** - * Define option with `flags`, `description` and optional - * coercion `fn`. - * - * The `flags` string contains the short and/or long flags, - * separated by comma, a pipe or space. The following are all valid - * all will output this way when `--help` is used. - * - * "-p, --pepper" - * "-p|--pepper" - * "-p --pepper" - * - * Examples: - * - * // simple boolean defaulting to undefined - * program.option('-p, --pepper', 'add pepper'); - * - * program.pepper - * // => undefined - * - * --pepper - * program.pepper - * // => true - * - * // simple boolean defaulting to true (unless non-negated option is also defined) - * program.option('-C, --no-cheese', 'remove cheese'); - * - * program.cheese - * // => true - * - * --no-cheese - * program.cheese - * // => false - * - * // required argument - * program.option('-C, --chdir ', 'change the working directory'); - * - * --chdir /tmp - * program.chdir - * // => "/tmp" - * - * // optional argument - * program.option('-c, --cheese [type]', 'add cheese [marble]'); - * - * @param {string} flags - * @param {string} [description] - * @param {Function|*} [fn] - custom option processing function or default value - * @param {*} [defaultValue] - * @return {Command} `this` command for chaining - */ + // register the option + this.options.push(option); - option(flags, description, fn, defaultValue) { - return this._optionEx({}, flags, description, fn, defaultValue); - }; + // when it's passed assign the value + // and conditionally invoke the callback + this.on('option:' + oname, function(val) { + // coercion + if (val !== null && fn) { + val = fn(val, self._getOptionValue(name) === undefined ? defaultValue : self._getOptionValue(name)); + } - /** - * Add a required option which must have a value after parsing. This usually means - * the option must be specified on the command line. (Otherwise the same as .option().) + // unassigned or boolean value + if (typeof self._getOptionValue(name) === 'boolean' || typeof self._getOptionValue(name) === 'undefined') { + // if no value, negate false, and we have a default, then use it! + if (val == null) { + self._setOptionValue(name, option.negate + ? false + : defaultValue || true); + } else { + self._setOptionValue(name, val); + } + } else if (val !== null) { + // reassign + self._setOptionValue(name, option.negate ? false : val); + } + }); + + return this; +}; + +/** + * Define option with `flags`, `description` and optional + * coercion `fn`. + * + * The `flags` string should contain both the short and long flags, + * separated by comma, a pipe or space. The following are all valid + * all will output this way when `--help` is used. + * + * "-p, --pepper" + * "-p|--pepper" + * "-p --pepper" + * + * Examples: + * + * // simple boolean defaulting to undefined + * program.option('-p, --pepper', 'add pepper'); + * + * program.pepper + * // => undefined + * + * --pepper + * program.pepper + * // => true + * + * // simple boolean defaulting to true (unless non-negated option is also defined) + * program.option('-C, --no-cheese', 'remove cheese'); + * + * program.cheese + * // => true + * + * --no-cheese + * program.cheese + * // => false + * + * // required argument + * program.option('-C, --chdir ', 'change the working directory'); + * + * --chdir /tmp + * program.chdir + * // => "/tmp" + * + * // optional argument + * program.option('-c, --cheese [type]', 'add cheese [marble]'); + * + * @param {String} flags + * @param {String} description + * @param {Function|*} [fn] - custom option processing function or default vaue + * @param {*} [defaultValue] + * @return {Command} for chaining + * @api public + */ + +Command.prototype.option = function(flags, description, fn, defaultValue) { + return this._optionEx({}, flags, description, fn, defaultValue); +}; + +/* + * Add a required option which must have a value after parsing. This usually means + * the option must be specified on the command line. (Otherwise the same as .option().) + * + * The `flags` string should contain both the short and long flags, separated by comma, a pipe or space. + * + * @param {String} flags + * @param {String} description + * @param {Function|*} [fn] - custom option processing function or default vaue + * @param {*} [defaultValue] + * @return {Command} for chaining + * @api public + */ + +Command.prototype.requiredOption = function(flags, description, fn, defaultValue) { + return this._optionEx({ mandatory: true }, flags, description, fn, defaultValue); +}; + +/** + * Allow unknown options on the command line. + * + * @param {Boolean} arg if `true` or omitted, no error will be thrown + * for unknown options. + * @api public + */ +Command.prototype.allowUnknownOption = function(arg) { + this._allowUnknownOption = arguments.length === 0 || arg; + return this; +}; + +/** + * Whether to store option values as properties on command object, + * or store separately (specify false). In both cases the option values can be accessed using .opts(). * - * The `flags` string contains the short and/or long flags, separated by comma, a pipe or space. + * @param {boolean} value + * @return {Command} Command for chaining + * @api public + */ + +Command.prototype.storeOptionsAsProperties = function(value) { + this._storeOptionsAsProperties = (value === undefined) || value; + if (this.options.length) { + // This is for programmer, not end user. + console.error('Commander usage error: call storeOptionsAsProperties before adding options'); + } + return this; +}; + +/** + * Whether to pass command to action handler, + * or just the options (specify false). * - * @param {string} flags - * @param {string} [description] - * @param {Function|*} [fn] - custom option processing function or default value - * @param {*} [defaultValue] - * @return {Command} `this` command for chaining + * @param {boolean} value + * @return {Command} Command for chaining + * @api public */ - requiredOption(flags, description, fn, defaultValue) { - return this._optionEx({ mandatory: true }, flags, description, fn, defaultValue); - }; +Command.prototype.passCommandToAction = function(value) { + this._passCommandToAction = (value === undefined) || value; + return this; +}; - /** - * Alter parsing of short flags with optional values. - * - * Examples: - * - * // for `.option('-f,--flag [value]'): - * .combineFlagAndOptionalValue(true) // `-f80` is treated like `--flag=80`, this is the default behaviour - * .combineFlagAndOptionalValue(false) // `-fb` is treated like `-f -b` - * - * @param {Boolean} [combine=true] - if `true` or omitted, an optional value can be specified directly after the flag. - */ - combineFlagAndOptionalValue(combine = true) { - this._combineFlagAndOptionalValue = !!combine; - return this; - }; +/** + * Store option value + * + * @param {String} key + * @param {Object} value + * @api private + */ - /** - * Allow unknown options on the command line. - * - * @param {Boolean} [allowUnknown=true] - if `true` or omitted, no error will be thrown - * for unknown options. - */ - allowUnknownOption(allowUnknown = true) { - this._allowUnknownOption = !!allowUnknown; - return this; - }; +Command.prototype._setOptionValue = function(key, value) { + if (this._storeOptionsAsProperties) { + this[key] = value; + } else { + this._optionValues[key] = value; + } +}; - /** - * Allow excess command-arguments on the command line. Pass false to make excess arguments an error. - * - * @param {Boolean} [allowExcess=true] - if `true` or omitted, no error will be thrown - * for excess arguments. - */ - allowExcessArguments(allowExcess = true) { - this._allowExcessArguments = !!allowExcess; - return this; - }; +/** + * Retrieve option value + * + * @param {String} key + * @return {Object} value + * @api private + */ - /** - * Enable positional options. Positional means global options are specified before subcommands which lets - * subcommands reuse the same option names, and also enables subcommands to turn on passThroughOptions. - * The default behaviour is non-positional and global options may appear anywhere on the command line. - * - * @param {Boolean} [positional=true] - */ - enablePositionalOptions(positional = true) { - this._enablePositionalOptions = !!positional; - return this; - }; +Command.prototype._getOptionValue = function(key) { + if (this._storeOptionsAsProperties) { + return this[key]; + } + return this._optionValues[key]; +}; - /** - * Pass through options that come after command-arguments rather than treat them as command-options, - * so actual command-options come before command-arguments. Turning this on for a subcommand requires - * positional options to have been enabled on the program (parent commands). - * The default behaviour is non-positional and options may appear before or after command-arguments. - * - * @param {Boolean} [passThrough=true] - * for unknown options. - */ - passThroughOptions(passThrough = true) { - this._passThroughOptions = !!passThrough; - if (!!this.parent && passThrough && !this.parent._enablePositionalOptions) { - throw new Error('passThroughOptions can not be used without turning on enablePositionalOptions for parent command(s)'); - } - return this; - }; +/** + * Parse `argv`, setting options and invoking commands when defined. + * + * @param {Array} argv + * @return {Command} for chaining + * @api public + */ - /** - * Whether to store option values as properties on command object, - * or store separately (specify false). In both cases the option values can be accessed using .opts(). - * - * @param {boolean} [storeAsProperties=true] - * @return {Command} `this` command for chaining - */ - - storeOptionsAsProperties(storeAsProperties = true) { - this._storeOptionsAsProperties = !!storeAsProperties; - if (this.options.length) { - throw new Error('call .storeOptionsAsProperties() before adding options'); - } - return this; - }; +Command.prototype.parse = function(argv) { + // implicit help + if (this.executables) this.addImplicitHelpCommand(); - /** - * Store option value - * - * @param {string} key - * @param {Object} value - * @api private - */ + // store raw args + this.rawArgs = argv; - _setOptionValue(key, value) { - if (this._storeOptionsAsProperties) { - this[key] = value; - } else { - this._optionValues[key] = value; - } - }; + // guess name + this._name = this._name || basename(argv[1], '.js'); - /** - * Retrieve option value - * - * @param {string} key - * @return {Object} value - * @api private - */ + // github-style sub-commands with no sub-command + if (this.executables && argv.length < 3 && !this.defaultExecutable) { + // this user needs help + argv.push(this._helpLongFlag); + } - _getOptionValue(key) { - if (this._storeOptionsAsProperties) { - return this[key]; - } - return this._optionValues[key]; - }; + // process argv + var normalized = this.normalize(argv.slice(2)); + var parsed = this.parseOptions(normalized); + var args = this.args = parsed.args; - /** - * Parse `argv`, setting options and invoking commands when defined. - * - * The default expectation is that the arguments are from node and have the application as argv[0] - * and the script being run in argv[1], with user parameters after that. - * - * Examples: - * - * program.parse(process.argv); - * program.parse(); // implicitly use process.argv and auto-detect node vs electron conventions - * program.parse(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0] - * - * @param {string[]} [argv] - optional, defaults to process.argv - * @param {Object} [parseOptions] - optionally specify style of options with from: node/user/electron - * @param {string} [parseOptions.from] - where the args are from: 'node', 'user', 'electron' - * @return {Command} `this` command for chaining - */ + var result = this.parseArgs(this.args, parsed.unknown); - parse(argv, parseOptions) { - if (argv !== undefined && !Array.isArray(argv)) { - throw new Error('first parameter to parse must be array or undefined'); - } - parseOptions = parseOptions || {}; - - // Default to using process.argv - if (argv === undefined) { - argv = process.argv; - // @ts-ignore: unknown property - if (process.versions && process.versions.electron) { - parseOptions.from = 'electron'; - } - } - this.rawArgs = argv.slice(); - - // make it a little easier for callers by supporting various argv conventions - let userArgs; - switch (parseOptions.from) { - case undefined: - case 'node': - this._scriptPath = argv[1]; - userArgs = argv.slice(2); - break; - case 'electron': - // @ts-ignore: unknown property - if (process.defaultApp) { - this._scriptPath = argv[1]; - userArgs = argv.slice(2); - } else { - userArgs = argv.slice(1); - } - break; - case 'user': - userArgs = argv.slice(0); - break; - default: - throw new Error(`unexpected parse option { from: '${parseOptions.from}' }`); - } - if (!this._scriptPath && require.main) { - this._scriptPath = require.main.filename; - } + if (args[0] === 'help' && args.length === 1) this.help(); - // Guess name, used in usage in help. - this._name = this._name || (this._scriptPath && path.basename(this._scriptPath, path.extname(this._scriptPath))); + // Note for future: we could return early if we found an action handler in parseArgs, as none of following code needed? - // Let's go! - this._parseCommand([], userArgs); + // --help + if (args[0] === 'help') { + args[0] = args[1]; + args[1] = this._helpLongFlag; + } else { + // If calling through to executable subcommand we could check for help flags before failing, + // but a somewhat unlikely case since program options not passed to executable subcommands. + // Wait for reports to see if check needed and what usage pattern is. + this._checkForMissingMandatoryOptions(); + } - return this; - }; + // executable sub-commands + // (Debugging note for future: args[0] is not right if an action has been called) + var name = result.args[0]; + var subCommand = null; - /** - * Parse `argv`, setting options and invoking commands when defined. - * - * Use parseAsync instead of parse if any of your action handlers are async. Returns a Promise. - * - * The default expectation is that the arguments are from node and have the application as argv[0] - * and the script being run in argv[1], with user parameters after that. - * - * Examples: - * - * program.parseAsync(process.argv); - * program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions - * program.parseAsync(my-args, { from: 'user' }); // just user supplied arguments, nothing special about argv[0] - * - * @param {string[]} [argv] - * @param {Object} [parseOptions] - * @param {string} parseOptions.from - where the args are from: 'node', 'user', 'electron' - * @return {Promise} - */ + // Look for subcommand + if (name) { + subCommand = this.commands.find(function(command) { + return command._name === name; + }); + } - parseAsync(argv, parseOptions) { - this.parse(argv, parseOptions); - return Promise.all(this._actionResults).then(() => this); - }; + // Look for alias + if (!subCommand && name) { + subCommand = this.commands.find(function(command) { + return command.alias() === name; + }); + if (subCommand) { + name = subCommand._name; + args[0] = name; + } + } - /** - * Execute a sub-command executable. - * - * @api private - */ + // Look for default subcommand + if (!subCommand && this.defaultExecutable) { + name = this.defaultExecutable; + args.unshift(name); + subCommand = this.commands.find(function(command) { + return command._name === name; + }); + } - _executeSubCommand(subcommand, args) { - args = args.slice(); - let launchWithNode = false; // Use node for source targets so do not need to get permissions correct, and on Windows. - const sourceExt = ['.js', '.ts', '.tsx', '.mjs', '.cjs']; + if (this._execs.has(name)) { + return this.executeSubCommand(argv, args, parsed.unknown, subCommand ? subCommand._executableFile : undefined); + } - // Not checking for help first. Unlikely to have mandatory and executable, and can't robustly test for help flags in external command. - this._checkForMissingMandatoryOptions(); + return result; +}; - // Want the entry script as the reference for command name and directory for searching for other files. - let scriptPath = this._scriptPath; - // Fallback in case not set, due to how Command created or called. - if (!scriptPath && require.main) { - scriptPath = require.main.filename; - } +/** + * Parse `argv`, setting options and invoking commands when defined. + * + * Use parseAsync instead of parse if any of your action handlers are async. Returns a Promise. + * + * @param {Array} argv + * @return {Promise} + * @api public + */ +Command.prototype.parseAsync = function(argv) { + this.parse(argv); + return Promise.all(this._actionResults); +}; - let baseDir; - try { - const resolvedLink = fs.realpathSync(scriptPath); - baseDir = path.dirname(resolvedLink); - } catch (e) { - baseDir = '.'; // dummy, probably not going to find executable! - } +/** + * Execute a sub-command executable. + * + * @param {Array} argv + * @param {Array} args + * @param {Array} unknown + * @param {String} executableFile + * @api private + */ - // name of the subcommand, like `pm-install` - let bin = path.basename(scriptPath, path.extname(scriptPath)) + '-' + subcommand._name; - if (subcommand._executableFile) { - bin = subcommand._executableFile; - } +Command.prototype.executeSubCommand = function(argv, args, unknown, executableFile) { + args = args.concat(unknown); - const localBin = path.join(baseDir, bin); - if (fs.existsSync(localBin)) { - // prefer local `./` to bin in the $PATH - bin = localBin; - } else { - // Look for source files. - sourceExt.forEach((ext) => { - if (fs.existsSync(`${localBin}${ext}`)) { - bin = `${localBin}${ext}`; - } - }); - } - launchWithNode = sourceExt.includes(path.extname(bin)); + if (!args.length) this.help(); - let proc; - if (process.platform !== 'win32') { - if (launchWithNode) { - args.unshift(bin); - // add executable arguments to spawn - args = incrementNodeInspectorPort(process.execArgv).concat(args); + var isExplicitJS = false; // Whether to use node to launch "executable" - proc = childProcess.spawn(process.argv[0], args, { stdio: 'inherit' }); - } else { - proc = childProcess.spawn(bin, args, { stdio: 'inherit' }); - } - } else { + // executable + var pm = argv[1]; + // name of the subcommand, like `pm-install` + var bin = basename(pm, path.extname(pm)) + '-' + args[0]; + if (executableFile != null) { + bin = executableFile; + // Check for same extensions as we scan for below so get consistent launch behaviour. + var executableExt = path.extname(executableFile); + isExplicitJS = executableExt === '.js' || executableExt === '.ts' || executableExt === '.mjs'; + } + + // In case of globally installed, get the base dir where executable + // subcommand file should be located at + var baseDir; + + var resolvedLink = fs.realpathSync(pm); + + baseDir = dirname(resolvedLink); + + // prefer local `./` to bin in the $PATH + var localBin = path.join(baseDir, bin); + + // whether bin file is a js script with explicit `.js` or `.ts` extension + if (exists(localBin + '.js')) { + bin = localBin + '.js'; + isExplicitJS = true; + } else if (exists(localBin + '.ts')) { + bin = localBin + '.ts'; + isExplicitJS = true; + } else if (exists(localBin + '.mjs')) { + bin = localBin + '.mjs'; + isExplicitJS = true; + } else if (exists(localBin)) { + bin = localBin; + } + + args = args.slice(1); + + var proc; + if (process.platform !== 'win32') { + if (isExplicitJS) { args.unshift(bin); // add executable arguments to spawn args = incrementNodeInspectorPort(process.execArgv).concat(args); - proc = childProcess.spawn(process.execPath, args, { stdio: 'inherit' }); + + proc = spawn(process.argv[0], args, { stdio: 'inherit' }); + } else { + proc = spawn(bin, args, { stdio: 'inherit' }); } + } else { + args.unshift(bin); + // add executable arguments to spawn + args = incrementNodeInspectorPort(process.execArgv).concat(args); + proc = spawn(process.execPath, args, { stdio: 'inherit' }); + } - const signals = ['SIGUSR1', 'SIGUSR2', 'SIGTERM', 'SIGINT', 'SIGHUP']; - signals.forEach((signal) => { - // @ts-ignore - process.on(signal, () => { - if (proc.killed === false && proc.exitCode === null) { - proc.kill(signal); - } - }); + var signals = ['SIGUSR1', 'SIGUSR2', 'SIGTERM', 'SIGINT', 'SIGHUP']; + signals.forEach(function(signal) { + process.on(signal, function() { + if (proc.killed === false && proc.exitCode === null) { + proc.kill(signal); + } }); + }); - // By default terminate process when spawned process terminates. - // Suppressing the exit if exitCallback defined is a bit messy and of limited use, but does allow process to stay running! - const exitCallback = this._exitCallback; + // By default terminate process when spawned process terminates. + // Suppressing the exit if exitCallback defined is a bit messy and of limited use, but does allow process to stay running! + const exitCallback = this._exitCallback; + if (!exitCallback) { + proc.on('close', process.exit.bind(process)); + } else { + proc.on('close', () => { + exitCallback(new CommanderError(process.exitCode || 0, 'commander.executeSubCommandAsync', '(close)')); + }); + } + proc.on('error', function(err) { + if (err.code === 'ENOENT') { + console.error('error: %s(1) does not exist, try --help', bin); + } else if (err.code === 'EACCES') { + console.error('error: %s(1) not executable. try chmod or run with root', bin); + } if (!exitCallback) { - proc.on('close', process.exit.bind(process)); + process.exit(1); } else { - proc.on('close', () => { - exitCallback(new CommanderError(process.exitCode || 0, 'commander.executeSubCommandAsync', '(close)')); - }); + const wrappedError = new CommanderError(1, 'commander.executeSubCommandAsync', '(error)'); + wrappedError.nestedError = err; + exitCallback(wrappedError); } - proc.on('error', (err) => { - // @ts-ignore - if (err.code === 'ENOENT') { - const executableMissing = `'${bin}' does not exist - - if '${subcommand._name}' is not meant to be an executable command, remove description parameter from '.command()' and use '.description()' instead - - if the default executable name is not suitable, use the executableFile option to supply a custom name`; - throw new Error(executableMissing); - // @ts-ignore - } else if (err.code === 'EACCES') { - throw new Error(`'${bin}' not executable`); - } - if (!exitCallback) { - process.exit(1); - } else { - const wrappedError = new CommanderError(1, 'commander.executeSubCommandAsync', '(error)'); - wrappedError.nestedError = err; - exitCallback(wrappedError); - } - }); + }); - // Store the reference to the child process - this.runningCommand = proc; - }; + // Store the reference to the child process + this.runningCommand = proc; +}; - /** - * @api private - */ - _dispatchSubcommand(commandName, operands, unknown) { - const subCommand = this._findCommand(commandName); - if (!subCommand) this.help({ error: true }); +/** + * Normalize `args`, splitting joined short flags. For example + * the arg "-abc" is equivalent to "-a -b -c". + * This also normalizes equal sign and splits "--abc=def" into "--abc def". + * + * @param {Array} args + * @return {Array} + * @api private + */ - if (subCommand._executableHandler) { - this._executeSubCommand(subCommand, operands.concat(unknown)); - } else { - subCommand._parseCommand(operands, unknown); +Command.prototype.normalize = function(args) { + var ret = [], + arg, + lastOpt, + index, + short, + opt; + + for (var i = 0, len = args.length; i < len; ++i) { + arg = args[i]; + if (i > 0) { + lastOpt = this.optionFor(args[i - 1]); } - }; - - /** - * Process arguments in context of this command. - * - * @api private - */ - _parseCommand(operands, unknown) { - const parsed = this.parseOptions(unknown); - operands = operands.concat(parsed.operands); - unknown = parsed.unknown; - this.args = operands.concat(unknown); - - if (operands && this._findCommand(operands[0])) { - this._dispatchSubcommand(operands[0], operands.slice(1), unknown); - } else if (this._hasImplicitHelpCommand() && operands[0] === this._helpCommandName) { - if (operands.length === 1) { - this.help(); + if (arg === '--') { + // Honor option terminator + ret = ret.concat(args.slice(i)); + break; + } else if (lastOpt && lastOpt.required) { + ret.push(arg); + } else if (arg.length > 2 && arg[0] === '-' && arg[1] !== '-') { + short = arg.slice(0, 2); + opt = this.optionFor(short); + if (opt && (opt.required || opt.optional)) { + ret.push(short); + ret.push(arg.slice(2)); } else { - this._dispatchSubcommand(operands[1], [], [this._helpLongFlag]); + arg.slice(1).split('').forEach(function(c) { + ret.push('-' + c); + }); } - } else if (this._defaultCommandName) { - outputHelpIfRequested(this, unknown); // Run the help for default command from parent rather than passing to default command - this._dispatchSubcommand(this._defaultCommandName, operands, unknown); + } else if (/^--/.test(arg) && ~(index = arg.indexOf('='))) { + ret.push(arg.slice(0, index), arg.slice(index + 1)); } else { - if (this.commands.length && this.args.length === 0 && !this._actionHandler && !this._defaultCommandName) { - // probably missing subcommand and no handler, user needs help - this.help({ error: true }); - } + ret.push(arg); + } + } - outputHelpIfRequested(this, parsed.unknown); - this._checkForMissingMandatoryOptions(); + return ret; +}; - // We do not always call this check to avoid masking a "better" error, like unknown command. - const checkForUnknownOptions = () => { - if (parsed.unknown.length > 0) { - this.unknownOption(parsed.unknown[0]); - } - }; +/** + * Parse command `args`. + * + * When listener(s) are available those + * callbacks are invoked, otherwise the "*" + * event is emitted and those actions are invoked. + * + * @param {Array} args + * @return {Command} for chaining + * @api private + */ - const commandEvent = `command:${this.name()}`; - if (this._actionHandler) { - checkForUnknownOptions(); - // Check expected arguments and collect variadic together. - const args = this.args.slice(); - this._args.forEach((arg, i) => { - if (arg.required && args[i] == null) { - this.missingArgument(arg.name); - } else if (arg.variadic) { - args[i] = args.splice(i); - args.length = Math.min(i + 1, args.length); - } - }); - if (args.length > this._args.length) { - this._excessArguments(args); - } +Command.prototype.parseArgs = function(args, unknown) { + var name; - this._actionHandler(args); - if (this.parent) this.parent.emit(commandEvent, operands, unknown); // legacy - } else if (this.parent && this.parent.listenerCount(commandEvent)) { - checkForUnknownOptions(); - this.parent.emit(commandEvent, operands, unknown); // legacy - } else if (operands.length) { - if (this._findCommand('*')) { // legacy default command - this._dispatchSubcommand('*', operands, unknown); - } else if (this.listenerCount('command:*')) { - // skip option check, emit event for possible misspelling suggestion - this.emit('command:*', operands, unknown); - } else if (this.commands.length) { - this.unknownCommand(); - } else { - checkForUnknownOptions(); - } - } else if (this.commands.length) { - // This command has subcommands and nothing hooked up at this level, so display help. - this.help({ error: true }); - } else { - checkForUnknownOptions(); - // fall through for caller to handle after calling .parse() - } + if (args.length) { + name = args[0]; + if (this.listeners('command:' + name).length) { + this.emit('command:' + args.shift(), args, unknown); + } else { + this.emit('command:*', args, unknown); } - }; - - /** - * Find matching command. - * - * @api private - */ - _findCommand(name) { - if (!name) return undefined; - return this.commands.find(cmd => cmd._name === name || cmd._aliases.includes(name)); - }; + } else { + outputHelpIfRequested(this, unknown); - /** - * Return an option matching `arg` if any. - * - * @param {string} arg - * @return {Option} - * @api private - */ + // If there were no args and we have unknown options, + // then they are extraneous and we need to error. + if (unknown.length > 0 && !this.defaultExecutable) { + this.unknownOption(unknown[0]); + } + if (this.commands.length === 0 && + this._args.filter(function(a) { return a.required; }).length === 0) { + this.emit('command:*'); + } + } - _findOption(arg) { - return this.options.find(option => option.is(arg)); - }; + return this; +}; - /** - * Display an error message if a mandatory option does not have a value. - * Lazy calling after checking for help flags from leaf subcommand. - * - * @api private - */ +/** + * Return an option matching `arg` if any. + * + * @param {String} arg + * @return {Option} + * @api private + */ - _checkForMissingMandatoryOptions() { - // Walk up hierarchy so can call in subcommand after checking for displaying help. - for (let cmd = this; cmd; cmd = cmd.parent) { - cmd.options.forEach((anOption) => { - if (anOption.mandatory && (cmd._getOptionValue(anOption.attributeName()) === undefined)) { - cmd.missingMandatoryOptionValue(anOption); - } - }); +Command.prototype.optionFor = function(arg) { + for (var i = 0, len = this.options.length; i < len; ++i) { + if (this.options[i].is(arg)) { + return this.options[i]; } - }; + } +}; - /** - * Parse options from `argv` removing known options, - * and return argv split into operands and unknown arguments. - * - * Examples: - * - * argv => operands, unknown - * --known kkk op => [op], [] - * op --known kkk => [op], [] - * sub --unknown uuu op => [sub], [--unknown uuu op] - * sub -- --unknown uuu op => [sub --unknown uuu op], [] - * - * @param {String[]} argv - * @return {{operands: String[], unknown: String[]}} - */ +/** + * Display an error message if a mandatory option does not have a value. + * + * @api private + */ - parseOptions(argv) { - const operands = []; // operands, not options or values - const unknown = []; // first unknown option and remaining unknown args - let dest = operands; - const args = argv.slice(); +Command.prototype._checkForMissingMandatoryOptions = function() { + // Walk up hierarchy so can call from action handler after checking for displaying help. + for (var cmd = this; cmd; cmd = cmd.parent) { + cmd.options.forEach((anOption) => { + if (anOption.mandatory && (cmd._getOptionValue(anOption.attributeName()) === undefined)) { + cmd.missingMandatoryOptionValue(anOption); + } + }); + } +}; + +/** + * Parse options from `argv` returning `argv` + * void of these options. + * + * @param {Array} argv + * @return {{args: Array, unknown: Array}} + * @api public + */ - function maybeOption(arg) { - return arg.length > 1 && arg[0] === '-'; - } +Command.prototype.parseOptions = function(argv) { + var args = [], + len = argv.length, + literal, + option, + arg; - // parse options - let activeVariadicOption = null; - while (args.length) { - const arg = args.shift(); + var unknownOptions = []; - // literal - if (arg === '--') { - if (dest === unknown) dest.push(arg); - dest.push(...args); - break; - } + // parse options + for (var i = 0; i < len; ++i) { + arg = argv[i]; - if (activeVariadicOption && !maybeOption(arg)) { - this.emit(`option:${activeVariadicOption.name()}`, arg); - continue; - } - activeVariadicOption = null; - - if (maybeOption(arg)) { - const option = this._findOption(arg); - // recognised option, call listener to assign value with possible custom processing - if (option) { - if (option.required) { - const value = args.shift(); - if (value === undefined) this.optionMissingArgument(option); - this.emit(`option:${option.name()}`, value); - } else if (option.optional) { - let value = null; - // historical behaviour is optional value is following arg unless an option - if (args.length > 0 && !maybeOption(args[0])) { - value = args.shift(); - } - this.emit(`option:${option.name()}`, value); - } else { // boolean flag - this.emit(`option:${option.name()}`); - } - activeVariadicOption = option.variadic ? option : null; - continue; - } - } + // literal args after -- + if (literal) { + args.push(arg); + continue; + } - // Look for combo options following single dash, eat first one if known. - if (arg.length > 2 && arg[0] === '-' && arg[1] !== '-') { - const option = this._findOption(`-${arg[1]}`); - if (option) { - if (option.required || (option.optional && this._combineFlagAndOptionalValue)) { - // option with value following in same argument - this.emit(`option:${option.name()}`, arg.slice(2)); - } else { - // boolean option, emit and put back remainder of arg for further processing - this.emit(`option:${option.name()}`); - args.unshift(`-${arg.slice(2)}`); - } - continue; - } - } + if (arg === '--') { + literal = true; + continue; + } - // Look for known long flag with value, like --foo=bar - if (/^--[^=]+=/.test(arg)) { - const index = arg.indexOf('='); - const option = this._findOption(arg.slice(0, index)); - if (option && (option.required || option.optional)) { - this.emit(`option:${option.name()}`, arg.slice(index + 1)); - continue; + // find matching Option + option = this.optionFor(arg); + + // option is defined + if (option) { + // requires arg + if (option.required) { + arg = argv[++i]; + if (arg == null) return this.optionMissingArgument(option); + this.emit('option:' + option.name(), arg); + // optional arg + } else if (option.optional) { + arg = argv[i + 1]; + if (arg == null || (arg[0] === '-' && arg !== '-')) { + arg = null; + } else { + ++i; } + this.emit('option:' + option.name(), arg); + // flag + } else { + this.emit('option:' + option.name()); } + continue; + } - // Not a recognised option by this command. - // Might be a command-argument, or subcommand option, or unknown option, or help command or option. + // looks like an option + if (arg.length > 1 && arg[0] === '-') { + unknownOptions.push(arg); - // An unknown option means further arguments also classified as unknown so can be reprocessed by subcommands. - if (maybeOption(arg)) { - dest = unknown; + // If the next argument looks like it might be + // an argument for this option, we pass it on. + // If it isn't, then it'll simply be ignored + if ((i + 1) < argv.length && (argv[i + 1][0] !== '-' || argv[i + 1] === '-')) { + unknownOptions.push(argv[++i]); } + continue; + } - // If using positionalOptions, stop processing our options at subcommand. - if ((this._enablePositionalOptions || this._passThroughOptions) && operands.length === 0 && unknown.length === 0) { - if (this._findCommand(arg)) { - operands.push(arg); - if (args.length > 0) unknown.push(...args); - break; - } else if (arg === this._helpCommandName && this._hasImplicitHelpCommand()) { - operands.push(arg); - if (args.length > 0) operands.push(...args); - break; - } else if (this._defaultCommandName) { - unknown.push(arg); - if (args.length > 0) unknown.push(...args); - break; - } - } + // arg + args.push(arg); + } - // If using passThroughOptions, stop processing options at first command-argument. - if (this._passThroughOptions) { - dest.push(arg); - if (args.length > 0) dest.push(...args); - break; - } + return { args: args, unknown: unknownOptions }; +}; - // add arg - dest.push(arg); +/** + * Return an object containing options as key-value pairs + * + * @return {Object} + * @api public + */ +Command.prototype.opts = function() { + if (this._storeOptionsAsProperties) { + // Preserve original behaviour so backwards compatible when still using properties + var result = {}, + len = this.options.length; + + for (var i = 0; i < len; i++) { + var key = this.options[i].attributeName(); + result[key] = key === this._versionOptionName ? this._version : this[key]; } + return result; + } - return { operands, unknown }; - }; + return this._optionValues; +}; - /** - * Return an object containing options as key-value pairs - * - * @return {Object} - */ - opts() { - if (this._storeOptionsAsProperties) { - // Preserve original behaviour so backwards compatible when still using properties - const result = {}; - const len = this.options.length; - - for (let i = 0; i < len; i++) { - const key = this.options[i].attributeName(); - result[key] = key === this._versionOptionName ? this._version : this[key]; - } - return result; - } +/** + * Argument `name` is missing. + * + * @param {String} name + * @api private + */ - return this._optionValues; - }; +Command.prototype.missingArgument = function(name) { + const message = `error: missing required argument '${name}'`; + console.error(message); + this._exit(1, 'commander.missingArgument', message); +}; - /** - * Internal bottleneck for handling of parsing errors. - * - * @api private - */ - _displayError(exitCode, code, message) { - this._outputConfiguration.outputError(`${message}\n`, this._outputConfiguration.writeErr); - this._exit(exitCode, code, message); +/** + * `Option` is missing an argument, but received `flag` or nothing. + * + * @param {Option} option + * @param {String} [flag] + * @api private + */ + +Command.prototype.optionMissingArgument = function(option, flag) { + let message; + if (flag) { + message = `error: option '${option.flags}' argument missing, got '${flag}'`; + } else { + message = `error: option '${option.flags}' argument missing`; } + console.error(message); + this._exit(1, 'commander.optionMissingArgument', message); +}; - /** - * Argument `name` is missing. - * - * @param {string} name - * @api private - */ +/** + * `Option` does not have a value, and is a mandatory option. + * + * @param {Option} option + * @api private + */ - missingArgument(name) { - const message = `error: missing required argument '${name}'`; - this._displayError(1, 'commander.missingArgument', message); - }; +Command.prototype.missingMandatoryOptionValue = function(option) { + const message = `error: required option '${option.flags}' not specified`; + console.error(message); + this._exit(1, 'commander.missingMandatoryOptionValue', message); +}; - /** - * `Option` is missing an argument. - * - * @param {Option} option - * @api private - */ +/** + * Unknown option `flag`. + * + * @param {String} flag + * @api private + */ - optionMissingArgument(option) { - const message = `error: option '${option.flags}' argument missing`; - this._displayError(1, 'commander.optionMissingArgument', message); - }; +Command.prototype.unknownOption = function(flag) { + if (this._allowUnknownOption) return; + const message = `error: unknown option '${flag}'`; + console.error(message); + this._exit(1, 'commander.unknownOption', message); +}; - /** - * `Option` does not have a value, and is a mandatory option. - * - * @param {Option} option - * @api private - */ +/** + * Variadic argument with `name` is not the last argument as required. + * + * @param {String} name + * @api private + */ - missingMandatoryOptionValue(option) { - const message = `error: required option '${option.flags}' not specified`; - this._displayError(1, 'commander.missingMandatoryOptionValue', message); - }; +Command.prototype.variadicArgNotLast = function(name) { + const message = `error: variadic arguments must be last '${name}'`; + console.error(message); + this._exit(1, 'commander.variadicArgNotLast', message); +}; - /** - * Unknown option `flag`. - * - * @param {string} flag - * @api private - */ +/** + * Set the program version to `str`. + * + * This method auto-registers the "-V, --version" flag + * which will print the version number when passed. + * + * You can optionally supply the flags and description to override the defaults. + * + * @param {String} str + * @param {String} [flags] + * @param {String} [description] + * @return {Command} for chaining + * @api public + */ - unknownOption(flag) { - if (this._allowUnknownOption) return; - const message = `error: unknown option '${flag}'`; - this._displayError(1, 'commander.unknownOption', message); - }; +Command.prototype.version = function(str, flags, description) { + if (arguments.length === 0) return this._version; + this._version = str; + flags = flags || '-V, --version'; + description = description || 'output the version number'; + var versionOption = new Option(flags, description); + this._versionOptionName = versionOption.long.substr(2) || 'version'; + this.options.push(versionOption); + var self = this; + this.on('option:' + this._versionOptionName, function() { + process.stdout.write(str + '\n'); + self._exit(0, 'commander.version', str); + }); + return this; +}; - /** - * Excess arguments, more than expected. - * - * @param {string[]} receivedArgs - * @api private - */ +/** + * Set the description to `str`. + * + * @param {String} str + * @param {Object} [argsDescription] + * @return {String|Command} + * @api public + */ - _excessArguments(receivedArgs) { - if (this._allowExcessArguments) return; +Command.prototype.description = function(str, argsDescription) { + if (arguments.length === 0) return this._description; + this._description = str; + this._argsDescription = argsDescription; + return this; +}; - const expected = this._args.length; - const s = (expected === 1) ? '' : 's'; - const forSubcommand = this.parent ? ` for '${this.name()}'` : ''; - const message = `error: too many arguments${forSubcommand}. Expected ${expected} argument${s} but got ${receivedArgs.length}.`; - this._displayError(1, 'commander.excessArguments', message); - }; +/** + * Set an alias for the command + * + * @param {String} alias + * @return {String|Command} + * @api public + */ - /** - * Unknown command. - * - * @api private - */ +Command.prototype.alias = function(alias) { + var command = this; + if (this.commands.length !== 0) { + command = this.commands[this.commands.length - 1]; + } - unknownCommand() { - const partCommands = [this.name()]; - for (let parentCmd = this.parent; parentCmd; parentCmd = parentCmd.parent) { - partCommands.unshift(parentCmd.name()); - } - const fullCommand = partCommands.join(' '); - const message = `error: unknown command '${this.args[0]}'.` + - (this._hasHelpOption ? ` See '${fullCommand} ${this._helpLongFlag}'.` : ''); - this._displayError(1, 'commander.unknownCommand', message); - }; + if (arguments.length === 0) return command._alias; - /** - * Set the program version to `str`. - * - * This method auto-registers the "-V, --version" flag - * which will print the version number when passed. - * - * You can optionally supply the flags and description to override the defaults. - * - * @param {string} str - * @param {string} [flags] - * @param {string} [description] - * @return {this | string} `this` command for chaining, or version string if no arguments - */ + if (alias === command._name) throw new Error('Command alias can\'t be the same as its name'); - version(str, flags, description) { - if (str === undefined) return this._version; - this._version = str; - flags = flags || '-V, --version'; - description = description || 'output the version number'; - const versionOption = this.createOption(flags, description); - this._versionOptionName = versionOption.attributeName(); - this.options.push(versionOption); - this.on('option:' + versionOption.name(), () => { - this._outputConfiguration.writeOut(`${str}\n`); - this._exit(0, 'commander.version', str); - }); - return this; - }; + command._alias = alias; + return this; +}; - /** - * Set the description to `str`. - * - * @param {string} [str] - * @param {Object} [argsDescription] - * @return {string|Command} - */ - description(str, argsDescription) { - if (str === undefined && argsDescription === undefined) return this._description; - this._description = str; - this._argsDescription = argsDescription; - return this; - }; +/** + * Set / get the command usage `str`. + * + * @param {String} [str] + * @return {String|Command} + * @api public + */ - /** - * Set an alias for the command. - * - * You may call more than once to add multiple aliases. Only the first alias is shown in the auto-generated help. - * - * @param {string} [alias] - * @return {string|Command} - */ +Command.prototype.usage = function(str) { + var args = this._args.map(function(arg) { + return humanReadableArgName(arg); + }); - alias(alias) { - if (alias === undefined) return this._aliases[0]; // just return first, for backwards compatibility + var usage = '[options]' + + (this.commands.length ? ' [command]' : '') + + (this._args.length ? ' ' + args.join(' ') : ''); - let command = this; - if (this.commands.length !== 0 && this.commands[this.commands.length - 1]._executableHandler) { - // assume adding alias for last added executable subcommand, rather than this - command = this.commands[this.commands.length - 1]; - } + if (arguments.length === 0) return this._usage || usage; + this._usage = str; - if (alias === command._name) throw new Error('Command alias can\'t be the same as its name'); + return this; +}; - command._aliases.push(alias); - return this; - }; +/** + * Get or set the name of the command + * + * @param {String} [str] + * @return {String|Command} + * @api public + */ - /** - * Set aliases for the command. - * - * Only the first alias is shown in the auto-generated help. - * - * @param {string[]} [aliases] - * @return {string[]|Command} - */ +Command.prototype.name = function(str) { + if (arguments.length === 0) return this._name; + this._name = str; + return this; +}; - aliases(aliases) { - // Getter for the array of aliases is the main reason for having aliases() in addition to alias(). - if (aliases === undefined) return this._aliases; +/** + * Return prepared commands. + * + * @return {Array} + * @api private + */ - aliases.forEach((alias) => this.alias(alias)); - return this; - }; +Command.prototype.prepareCommands = function() { + return this.commands.filter(function(cmd) { + return !cmd._noHelp; + }).map(function(cmd) { + var args = cmd._args.map(function(arg) { + return humanReadableArgName(arg); + }).join(' '); + + return [ + cmd._name + + (cmd._alias ? '|' + cmd._alias : '') + + (cmd.options.length ? ' [options]' : '') + + (args ? ' ' + args : ''), + cmd._description + ]; + }); +}; - /** - * Set / get the command usage `str`. - * - * @param {string} [str] - * @return {String|Command} - */ +/** + * Return the largest command length. + * + * @return {Number} + * @api private + */ - usage(str) { - if (str === undefined) { - if (this._usage) return this._usage; +Command.prototype.largestCommandLength = function() { + var commands = this.prepareCommands(); + return commands.reduce(function(max, command) { + return Math.max(max, command[0].length); + }, 0); +}; - const args = this._args.map((arg) => { - return humanReadableArgName(arg); - }); - return [].concat( - (this.options.length || this._hasHelpOption ? '[options]' : []), - (this.commands.length ? '[command]' : []), - (this._args.length ? args : []) - ).join(' '); - } +/** + * Return the largest option length. + * + * @return {Number} + * @api private + */ - this._usage = str; - return this; - }; +Command.prototype.largestOptionLength = function() { + var options = [].slice.call(this.options); + options.push({ + flags: this._helpFlags + }); - /** - * Get or set the name of the command - * - * @param {string} [str] - * @return {string|Command} - */ + return options.reduce(function(max, option) { + return Math.max(max, option.flags.length); + }, 0); +}; - name(str) { - if (str === undefined) return this._name; - this._name = str; - return this; - }; +/** + * Return the largest arg length. + * + * @return {Number} + * @api private + */ - /** - * Return program help documentation. - * - * @param {{ error: boolean }} [contextOptions] - pass {error:true} to wrap for stderr instead of stdout - * @return {string} - */ +Command.prototype.largestArgLength = function() { + return this._args.reduce(function(max, arg) { + return Math.max(max, arg.name.length); + }, 0); +}; - helpInformation(contextOptions) { - const helper = this.createHelp(); - if (helper.helpWidth === undefined) { - helper.helpWidth = (contextOptions && contextOptions.error) ? this._outputConfiguration.getErrHelpWidth() : this._outputConfiguration.getOutHelpWidth(); - } - return helper.formatHelp(this, helper); - }; +/** + * Return the pad width. + * + * @return {Number} + * @api private + */ - /** - * @api private - */ +Command.prototype.padWidth = function() { + var width = this.largestOptionLength(); + if (this._argsDescription && this._args.length) { + if (this.largestArgLength() > width) { + width = this.largestArgLength(); + } + } - _getHelpContext(contextOptions) { - contextOptions = contextOptions || {}; - const context = { error: !!contextOptions.error }; - let write; - if (context.error) { - write = (arg) => this._outputConfiguration.writeErr(arg); - } else { - write = (arg) => this._outputConfiguration.writeOut(arg); + if (this.commands && this.commands.length) { + if (this.largestCommandLength() > width) { + width = this.largestCommandLength(); } - context.write = contextOptions.write || write; - context.command = this; - return context; } - /** - * Output help information for this command. - * - * Outputs built-in help, and custom text added using `.addHelpText()`. - * - * @param {{ error: boolean } | Function} [contextOptions] - pass {error:true} to write to stderr instead of stdout - */ + return width; +}; - outputHelp(contextOptions) { - let deprecatedCallback; - if (typeof contextOptions === 'function') { - deprecatedCallback = contextOptions; - contextOptions = undefined; - } - const context = this._getHelpContext(contextOptions); +/** + * Return help for options. + * + * @return {String} + * @api private + */ - const groupListeners = []; - let command = this; - while (command) { - groupListeners.push(command); // ordered from current command to root - command = command.parent; - } +Command.prototype.optionHelp = function() { + var width = this.padWidth(); - groupListeners.slice().reverse().forEach(command => command.emit('beforeAllHelp', context)); - this.emit('beforeHelp', context); + var columns = process.stdout.columns || 80; + var descriptionWidth = columns - width - 4; - let helpInformation = this.helpInformation(context); - if (deprecatedCallback) { - helpInformation = deprecatedCallback(helpInformation); - if (typeof helpInformation !== 'string' && !Buffer.isBuffer(helpInformation)) { - throw new Error('outputHelp callback must return a string or a Buffer'); - } - } - context.write(helpInformation); + // Append the help information + return this.options.map(function(option) { + const fullDesc = option.description + + ((!option.negate && option.defaultValue !== undefined) ? ' (default: ' + JSON.stringify(option.defaultValue) + ')' : ''); + return pad(option.flags, width) + ' ' + optionalWrap(fullDesc, descriptionWidth, width + 2); + }).concat([pad(this._helpFlags, width) + ' ' + optionalWrap(this._helpDescription, descriptionWidth, width + 2)]) + .join('\n'); +}; - this.emit(this._helpLongFlag); // deprecated - this.emit('afterHelp', context); - groupListeners.forEach(command => command.emit('afterAllHelp', context)); - }; +/** + * Return command help documentation. + * + * @return {String} + * @api private + */ - /** - * You can pass in flags and a description to override the help - * flags and help description for your command. Pass in false to - * disable the built-in help option. - * - * @param {string | boolean} [flags] - * @param {string} [description] - * @return {Command} `this` command for chaining - */ +Command.prototype.commandHelp = function() { + if (!this.commands.length) return ''; - helpOption(flags, description) { - if (typeof flags === 'boolean') { - this._hasHelpOption = flags; - return this; - } - this._helpFlags = flags || this._helpFlags; - this._helpDescription = description || this._helpDescription; + var commands = this.prepareCommands(); + var width = this.padWidth(); - const helpFlags = _parseOptionFlags(this._helpFlags); - this._helpShortFlag = helpFlags.shortFlag; - this._helpLongFlag = helpFlags.longFlag; + var columns = process.stdout.columns || 80; + var descriptionWidth = columns - width - 4; - return this; - }; + return [ + 'Commands:', + commands.map(function(cmd) { + var desc = cmd[1] ? ' ' + cmd[1] : ''; + return (desc ? pad(cmd[0], width) : cmd[0]) + optionalWrap(desc, descriptionWidth, width + 2); + }).join('\n').replace(/^/gm, ' '), + '' + ].join('\n'); +}; - /** - * Output help information and exit. - * - * Outputs built-in help, and custom text added using `.addHelpText()`. - * - * @param {{ error: boolean }} [contextOptions] - pass {error:true} to write to stderr instead of stdout - */ +/** + * Return program help documentation. + * + * @return {String} + * @api private + */ - help(contextOptions) { - this.outputHelp(contextOptions); - let exitCode = process.exitCode || 0; - if (exitCode === 0 && contextOptions && typeof contextOptions !== 'function' && contextOptions.error) { - exitCode = 1; +Command.prototype.helpInformation = function() { + var desc = []; + if (this._description) { + desc = [ + this._description, + '' + ]; + + var argsDescription = this._argsDescription; + if (argsDescription && this._args.length) { + var width = this.padWidth(); + var columns = process.stdout.columns || 80; + var descriptionWidth = columns - width - 5; + desc.push('Arguments:'); + desc.push(''); + this._args.forEach(function(arg) { + desc.push(' ' + pad(arg.name, width) + ' ' + wrap(argsDescription[arg.name], descriptionWidth, width + 4)); + }); + desc.push(''); } - // message: do not have all displayed text available so only passing placeholder. - this._exit(exitCode, 'commander.help', '(outputHelp)'); - }; + } - /** - * Add additional text to be displayed with the built-in help. - * - * Position is 'before' or 'after' to affect just this command, - * and 'beforeAll' or 'afterAll' to affect this command and all its subcommands. - * - * @param {string} position - before or after built-in help - * @param {string | Function} text - string to add, or a function returning a string - * @return {Command} `this` command for chaining - */ - addHelpText(position, text) { - const allowedValues = ['beforeAll', 'before', 'after', 'afterAll']; - if (!allowedValues.includes(position)) { - throw new Error(`Unexpected value for position to addHelpText. -Expecting one of '${allowedValues.join("', '")}'`); - } - const helpEvent = `${position}Help`; - this.on(helpEvent, (context) => { - let helpStr; - if (typeof text === 'function') { - helpStr = text({ error: context.error, command: context.command }); - } else { - helpStr = text; - } - // Ignore falsy value when nothing to output. - if (helpStr) { - context.write(`${helpStr}\n`); - } - }); - return this; + var cmdName = this._name; + if (this._alias) { + cmdName = cmdName + '|' + this._alias; } + var parentCmdNames = ''; + for (var parentCmd = this.parent; parentCmd; parentCmd = parentCmd.parent) { + parentCmdNames = parentCmd.name() + ' ' + parentCmdNames; + } + var usage = [ + 'Usage: ' + parentCmdNames + cmdName + ' ' + this.usage(), + '' + ]; + + var cmds = []; + var commandHelp = this.commandHelp(); + if (commandHelp) cmds = [commandHelp]; + + var options = [ + 'Options:', + '' + this.optionHelp().replace(/^/gm, ' '), + '' + ]; + + return usage + .concat(desc) + .concat(options) + .concat(cmds) + .join('\n'); }; /** - * Expose the root command. + * Output help information for this command. + * + * When listener(s) are available for the helpLongFlag + * those callbacks are invoked. + * + * @api public */ -exports = module.exports = new Command(); -exports.program = exports; // More explicit access to global command. +Command.prototype.outputHelp = function(cb) { + if (!cb) { + cb = function(passthru) { + return passthru; + }; + } + const cbOutput = cb(this.helpInformation()); + if (typeof cbOutput !== 'string' && !Buffer.isBuffer(cbOutput)) { + throw new Error('outputHelp callback must return a string or a Buffer'); + } + process.stdout.write(cbOutput); + this.emit(this._helpLongFlag); +}; + +/** + * You can pass in flags and a description to override the help + * flags and help description for your command. + * + * @param {String} [flags] + * @param {String} [description] + * @return {Command} + * @api public + */ + +Command.prototype.helpOption = function(flags, description) { + this._helpFlags = flags || this._helpFlags; + this._helpDescription = description || this._helpDescription; + + var splitFlags = this._helpFlags.split(/[ ,|]+/); + + if (splitFlags.length > 1) this._helpShortFlag = splitFlags.shift(); + + this._helpLongFlag = splitFlags.shift(); + + return this; +}; /** - * Expose classes + * Output help information and exit. + * + * @param {Function} [cb] + * @api public */ -exports.Command = Command; -exports.Option = Option; -exports.CommanderError = CommanderError; -exports.InvalidOptionArgumentError = InvalidOptionArgumentError; -exports.Help = Help; +Command.prototype.help = function(cb) { + this.outputHelp(cb); + // exitCode: preserving original behaviour which was calling process.exit() + // message: do not have all displayed text available so only passing placeholder. + this._exit(process.exitCode || 0, 'commander.help', '(outputHelp)'); +}; /** * Camel-case the given `flag` * - * @param {string} flag - * @return {string} + * @param {String} flag + * @return {String} * @api private */ function camelcase(flag) { - return flag.split('-').reduce((str, word) => { + return flag.split('-').reduce(function(str, word) { return str + word[0].toUpperCase() + word.slice(1); }); } +/** + * Pad `str` to `width`. + * + * @param {String} str + * @param {Number} width + * @return {String} + * @api private + */ + +function pad(str, width) { + var len = Math.max(0, width - str.length); + return str + Array(len + 1).join(' '); +} + +/** + * Wraps the given string with line breaks at the specified width while breaking + * words and indenting every but the first line on the left. + * + * @param {String} str + * @param {Number} width + * @param {Number} indent + * @return {String} + * @api private + */ +function wrap(str, width, indent) { + var regex = new RegExp('.{1,' + (width - 1) + '}([\\s\u200B]|$)|[^\\s\u200B]+?([\\s\u200B]|$)', 'g'); + var lines = str.match(regex) || []; + return lines.map(function(line, i) { + if (line.slice(-1) === '\n') { + line = line.slice(0, line.length - 1); + } + return ((i > 0 && indent) ? Array(indent + 1).join(' ') : '') + line.trimRight(); + }).join('\n'); +} + +/** + * Optionally wrap the given str to a max width of width characters per line + * while indenting with indent spaces. Do not wrap if insufficient width or + * string is manually formatted. + * + * @param {String} str + * @param {Number} width + * @param {Number} indent + * @return {String} + * @api private + */ +function optionalWrap(str, width, indent) { + // Detect manually wrapped and indented strings by searching for line breaks + // followed by multiple spaces/tabs. + if (str.match(/[\n]\s+/)) return str; + // Do not wrap to narrow columns (or can end up with a word per line). + const minWidth = 40; + if (width < minWidth) return str; + + return wrap(str, width, indent); +} + /** * Output help information if help flags specified * * @param {Command} cmd - command to output help for - * @param {Array} args - array of options to search for help flags + * @param {Array} options - array of options to search for -h or --help * @api private */ -function outputHelpIfRequested(cmd, args) { - const helpOption = cmd._hasHelpOption && args.find(arg => arg === cmd._helpLongFlag || arg === cmd._helpShortFlag); - if (helpOption) { - cmd.outputHelp(); - // (Do not have all displayed text available so only passing placeholder.) - cmd._exit(0, 'commander.helpDisplayed', '(outputHelp)'); +function outputHelpIfRequested(cmd, options) { + options = options || []; + + for (var i = 0; i < options.length; i++) { + if (options[i] === cmd._helpLongFlag || options[i] === cmd._helpShortFlag) { + cmd.outputHelp(); + // (Do not have all displayed text available so only passing placeholder.) + cmd._exit(0, 'commander.helpDisplayed', '(outputHelp)'); + } } } @@ -2135,38 +1578,27 @@ function outputHelpIfRequested(cmd, args) { * Takes an argument and returns its human readable equivalent for help usage. * * @param {Object} arg - * @return {string} + * @return {String} * @api private */ function humanReadableArgName(arg) { - const nameOutput = arg.name + (arg.variadic === true ? '...' : ''); + var nameOutput = arg.name + (arg.variadic === true ? '...' : ''); return arg.required ? '<' + nameOutput + '>' : '[' + nameOutput + ']'; } -/** - * Parse the short and long flag out of something like '-m,--mixed ' - * - * @api private - */ - -function _parseOptionFlags(flags) { - let shortFlag; - let longFlag; - // Use original very loose parsing to maintain backwards compatibility for now, - // which allowed for example unintended `-sw, --short-word` [sic]. - const flagParts = flags.split(/[ |,]+/); - if (flagParts.length > 1 && !/^[[<]/.test(flagParts[1])) shortFlag = flagParts.shift(); - longFlag = flagParts.shift(); - // Add support for lone short flag without significantly changing parsing! - if (!shortFlag && /^-[^-]$/.test(longFlag)) { - shortFlag = longFlag; - longFlag = undefined; +// for versions before node v0.8 when there weren't `fs.existsSync` +function exists(file) { + try { + if (fs.statSync(file).isFile()) { + return true; + } + } catch (e) { + return false; } - return { shortFlag, longFlag }; } /** @@ -2183,35 +1615,35 @@ function incrementNodeInspectorPort(args) { // --inspect-brk[=[host:]port] // --inspect-port=[host:]port return args.map((arg) => { - if (!arg.startsWith('--inspect')) { - return arg; - } - let debugOption; - let debugHost = '127.0.0.1'; - let debugPort = '9229'; - let match; - if ((match = arg.match(/^(--inspect(-brk)?)$/)) !== null) { - // e.g. --inspect - debugOption = match[1]; - } else if ((match = arg.match(/^(--inspect(-brk|-port)?)=([^:]+)$/)) !== null) { - debugOption = match[1]; - if (/^\d+$/.test(match[3])) { - // e.g. --inspect=1234 - debugPort = match[3]; - } else { - // e.g. --inspect=localhost + var result = arg; + if (arg.indexOf('--inspect') === 0) { + var debugOption; + var debugHost = '127.0.0.1'; + var debugPort = '9229'; + var match; + if ((match = arg.match(/^(--inspect(-brk)?)$/)) !== null) { + // e.g. --inspect + debugOption = match[1]; + } else if ((match = arg.match(/^(--inspect(-brk|-port)?)=([^:]+)$/)) !== null) { + debugOption = match[1]; + if (/^\d+$/.test(match[3])) { + // e.g. --inspect=1234 + debugPort = match[3]; + } else { + // e.g. --inspect=localhost + debugHost = match[3]; + } + } else if ((match = arg.match(/^(--inspect(-brk|-port)?)=([^:]+):(\d+)$/)) !== null) { + // e.g. --inspect=localhost:1234 + debugOption = match[1]; debugHost = match[3]; + debugPort = match[4]; } - } else if ((match = arg.match(/^(--inspect(-brk|-port)?)=([^:]+):(\d+)$/)) !== null) { - // e.g. --inspect=localhost:1234 - debugOption = match[1]; - debugHost = match[3]; - debugPort = match[4]; - } - if (debugOption && debugPort !== '0') { - return `${debugOption}=${debugHost}:${parseInt(debugPort) + 1}`; + if (debugOption && debugPort !== '0') { + result = `${debugOption}=${debugHost}:${parseInt(debugPort) + 1}`; + } } - return arg; + return result; }); } -- cgit v1.2.3