From 08245cc7ac896bfbefb9ed8ec792f1c0c66cc008 Mon Sep 17 00:00:00 2001 From: John Gee Date: Tue, 25 May 2021 18:01:18 +1200 Subject: [PATCH] Refactor classes into files (#1522) * Factor out Argument class * Factor out error and option and utility * Add lib to run-scripts * Factor out Help * Factor out Command * Include lib in pack files --- index.js | 2507 +---------------------------------------------- lib/argument.js | 95 ++ lib/command.js | 1810 ++++++++++++++++++++++++++++++++++ lib/error.js | 45 + lib/help.js | 383 ++++++++ lib/option.js | 194 ++++ package.json | 5 +- 7 files changed, 2539 insertions(+), 2500 deletions(-) create mode 100644 lib/argument.js create mode 100644 lib/command.js create mode 100644 lib/error.js create mode 100644 lib/help.js create mode 100644 lib/option.js diff --git a/index.js b/index.js index 3294e9f2b..7563b1bac 100644 --- a/index.js +++ b/index.js @@ -1,2516 +1,27 @@ -/** - * Module dependencies. - */ - -const EventEmitter = require('events').EventEmitter; -const childProcess = require('child_process'); -const path = require('path'); -const fs = require('fs'); +const { Argument } = require('./lib/argument.js'); +const { Command } = require('./lib/command.js'); +const { CommanderError, InvalidArgumentError } = require('./lib/error.js'); +const { Help } = require('./lib/help.js'); +const { Option } = require('./lib/option.js'); // @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 [, helpName, helpArgs] = cmd._helpCommandnameAndArgs.match(/([^ ]+) *(.*)/); - const helpCommand = cmd.createCommand(helpName) - .helpOption(false); - helpCommand.description(cmd._helpCommandDescription); - if (helpArgs) helpCommand.arguments(helpArgs); - 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 if any have a description. - * - * @param {Command} cmd - * @returns {Argument[]} - */ - - visibleArguments(cmd) { - // Side effect! Apply the legacy descriptions before the arguments are displayed. - if (cmd._argsDescription) { - cmd._args.forEach(argument => { - argument.description = argument.description || cmd._argsDescription[argument.name()] || ''; - }); - } - - // If there are any arguments with a description then return all the arguments. - if (cmd._args.find(argument => argument.description)) { - return cmd._args; - }; - 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 argument term to show in the list of arguments. - * - * @param {Argument} argument - * @returns {string} - */ - - argumentTerm(argument) { - return argument.name(); - } - - /** - * 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, helper.argumentTerm(argument).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; - }; - - /** - * Get the argument description to show in the list of arguments. - * - * @param {Argument} argument - * @return {string} - */ - - argumentDescription(argument) { - const extraInfo = []; - if (argument.defaultValue !== undefined) { - extraInfo.push(`default: ${argument.defaultValueDescription || JSON.stringify(argument.defaultValue)}`); - } - if (extraInfo.length > 0) { - return `${argument.description} (${extraInfo.join(', ')})`; - } - return argument.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)); - } - - // Usage - let output = [`Usage: ${helper.commandUsage(cmd)}`, '']; - - // Description - const commandDescription = helper.commandDescription(cmd); - if (commandDescription.length > 0) { - output = output.concat([commandDescription, '']); - } - - // Arguments - const argumentList = helper.visibleArguments(cmd).map((argument) => { - return formatItem(helper.argumentTerm(argument), helper.argumentDescription(argument)); - }); - if (argumentList.length > 0) { - output = output.concat(['Arguments:', formatList(argumentList), '']); - } - - // 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), '']); - } - - // 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), '']); - } - - return output.join('\n'); - } - - /** - * Calculate the pad width from the maximum term length. - * - * @param {Command} cmd - * @param {Help} helper - * @returns {number} - */ - - padWidth(cmd, helper) { - return Math.max( - helper.longestOptionTermLength(cmd, helper), - helper.longestSubcommandTermLength(cmd, helper), - helper.longestArgumentTermLength(cmd, helper) - ); - }; - - /** - * 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} - * - */ - - 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'); - } -} - -class Argument { - /** - * Initialize a new command argument with the given name and description. - * The default is that the argument is required, and you can explicitly - * indicate this with <> around the name. Put [] around the name for an optional argument. - * - * @param {string} name - * @param {string} [description] - */ - - constructor(name, description) { - this.description = description || ''; - this.variadic = false; - this.parseArg = undefined; - this.defaultValue = undefined; - this.defaultValueDescription = undefined; - - switch (name[0]) { - case '<': // e.g. - this.required = true; - this._name = name.slice(1, -1); - break; - case '[': // e.g. [optional] - this.required = false; - this._name = name.slice(1, -1); - break; - default: - this.required = true; - this._name = name; - break; - } - - if (this._name.length > 3 && this._name.slice(-3) === '...') { - this.variadic = true; - this._name = this._name.slice(0, -3); - } - } - - /** - * Return argument name. - * - * @return {string} - */ - - name() { - return this._name; - }; - - /** - * Set the default value, and optionally supply the description to be displayed in the help. - * - * @param {any} value - * @param {string} [description] - * @return {Argument} - */ - - default(value, description) { - this.defaultValue = value; - this.defaultValueDescription = description; - return this; - }; - - /** - * Set the custom handler for processing CLI command arguments into argument values. - * - * @param {Function} [fn] - * @return {Argument} - */ - - argParser(fn) { - this.parseArg = fn; - return this; - }; -} - -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 InvalidArgumentError(`Allowed choices are ${values.join(', ')}.`); - } - if (this.variadic) { - return this._concatValue(arg, previous); - } - return arg; - }; - return this; - }; - - /** - * Return option name. - * - * @return {string} - */ - - name() { - if (this.long) { - return this.long.replace(/^--/, ''); - } - return this.short.replace(/^-/, ''); - }; - - /** - * 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-/, '')); - }; - - /** - * 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; - }; -} - -/** - * CommanderError class - * @class - */ -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 - * @constructor - */ - constructor(exitCode, code, message) { - super(message); - // properly capture stack trace in Node.js - Error.captureStackTrace(this, this.constructor); - this.name = this.constructor.name; - this.code = code; - this.exitCode = exitCode; - this.nestedError = undefined; - } -} - -/** - * InvalidArgumentError class - * @class - */ -class InvalidArgumentError extends CommanderError { - /** - * Constructs the InvalidArgumentError class - * @param {string} [message] explanation of why argument is invalid - * @constructor - */ - constructor(message) { - super(1, 'commander.invalidArgument', 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._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; // legacy - this._enablePositionalOptions = false; - this._passThroughOptions = false; - this._lifeCycleHooks = {}; // a hash of arrays - - // 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 [, name, args] = nameAndArgs.match(/([^ ]+) *(.*)/); - const cmd = this.createCommand(name); - - 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 - if (args) cmd.arguments(args); - this.commands.push(cmd); - 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 - */ - - configureHelp(configuration) { - if (configuration === undefined) return this._helpConfiguration; - - this._helpConfiguration = configuration; - return this; - } - - /** - * 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; - } - - /** - * 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); - - opts = opts || {}; - if (opts.isDefault) this._defaultCommandName = cmd._name; - if (opts.noHelp || opts.hidden) cmd._hidden = true; // modifying passed command due to existing implementation - - this.commands.push(cmd); - cmd.parent = this; - return this; - }; - - /** - * Factory routine to create a new unattached argument. - * - * See .argument() for creating an attached argument, which uses this routine to - * create the argument. You can override createArgument to return a custom argument. - * - * @param {string} name - * @param {string} [description] - * @return {Argument} new argument - */ - - createArgument(name, description) { - return new Argument(name, description); - }; - - /** - * Define argument syntax for command. - * - * The default is that the argument is required, and you can explicitly - * indicate this with <> around the name. Put [] around the name for an optional argument. - * - * @example - * - * program.argument(''); - * program.argument('[output-file]'); - * - * @param {string} name - * @param {string} [description] - * @param {Function|*} [fn] - custom argument processing function - * @param {*} [defaultValue] - * @return {Command} `this` command for chaining - */ - argument(name, description, fn, defaultValue) { - const argument = this.createArgument(name, description); - if (typeof fn === 'function') { - argument.default(defaultValue).argParser(fn); - } else { - argument.default(fn); - } - this.addArgument(argument); - return this; - } - - /** - * Define argument syntax for command, adding multiple at once (without descriptions). - * - * See also .argument(). - * - * @example - * - * program.arguments(' [env]'); - * - * @param {string} names - * @return {Command} `this` command for chaining - */ - - arguments(names) { - names.split(/ +/).forEach((detail) => { - this.argument(detail); - }); - return this; - }; - - /** - * Define argument syntax for command, adding a prepared argument. - * - * @param {Argument} argument - * @return {Command} `this` command for chaining - */ - addArgument(argument) { - const previousArgument = this._args.slice(-1)[0]; - if (previousArgument && previousArgument.variadic) { - throw new Error(`only the last argument can be variadic '${previousArgument.name()}'`); - } - if (argument.required && argument.defaultValue !== undefined && argument.parseArg === undefined) { - throw new Error(`a default value for a required argument is never used: '${argument.name()}'`); - } - this._args.push(argument); - return this; - } - - /** - * 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 - */ - - 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; - } - return this; - }; - - /** - * @return {boolean} - * @api private - */ - - _hasImplicitHelpCommand() { - if (this._addImplicitHelpCommand === undefined) { - return this.commands.length && !this._actionHandler && !this._findCommand('help'); - } - return this._addImplicitHelpCommand; - }; - - /** - * Add hook for life cycle event. - * - * @param {string} event - * @param {Function} listener - * @return {Command} `this` command for chaining - */ - - hook(event, listener) { - const allowedValues = ['preAction', 'postAction']; - if (!allowedValues.includes(event)) { - throw new Error(`Unexpected value for event passed to hook : '${event}'. -Expecting one of '${allowedValues.join("', '")}'`); - } - if (this._lifeCycleHooks[event]) { - this._lifeCycleHooks[event].push(listener); - } else { - this._lifeCycleHooks[event] = [listener]; - } - 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 - */ - - _exit(exitCode, code, message) { - if (this._exitCallback) { - this._exitCallback(new CommanderError(exitCode, code, message)); - // Expecting this line is not reached. - } - process.exit(exitCode); - }; - - /** - * 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 - */ - - 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); - - return fn.apply(this, actionArgs); - }; - this._actionHandler = listener; - return this; - }; - - /** - * 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 - */ - - createOption(flags, description) { - return new Option(flags, description); - }; - - /** - * 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); - } - } - - // 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.invalidArgument') { - 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); - } - - // 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); - } - } else if (val !== null) { - // reassign - this.setOptionValue(name, option.negate ? false : val); - } - }); - - return this; - } - - /** - * 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); - return m ? m[0] : def; - }; - option.default(defaultValue).argParser(fn); - } else { - option.default(fn); - } - - return this.addOption(option); - } - - /** - * 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 - */ - - option(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 contains the short and/or long flags, separated by comma, a pipe or space. - * - * @param {string} flags - * @param {string} [description] - * @param {Function|*} [fn] - custom option processing function or default value - * @param {*} [defaultValue] - * @return {Command} `this` command for chaining - */ - - requiredOption(flags, description, fn, defaultValue) { - return this._optionEx({ mandatory: true }, flags, description, fn, defaultValue); - }; - - /** - * 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; - }; - - /** - * 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; - }; - - /** - * 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; - }; - - /** - * 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; - }; - - /** - * 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; - }; - - /** - * 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; - }; - - /** - * Retrieve option value. - * - * @param {string} key - * @return {Object} value - */ - - getOptionValue(key) { - if (this._storeOptionsAsProperties) { - return this[key]; - } - return this._optionValues[key]; - }; - - /** - * Store option value. - * - * @param {string} key - * @param {Object} value - * @return {Command} `this` command for chaining - */ - - setOptionValue(key, value) { - if (this._storeOptionsAsProperties) { - this[key] = value; - } else { - this._optionValues[key] = value; - } - return this; - }; - - /** - * Get user arguments implied or explicit arguments. - * Side-effects: set _scriptPath if args included application, and use that to set implicit command name. - * - * @api private - */ - - _prepareUserArgs(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; - } - - // Guess name, used in usage in help. - this._name = this._name || (this._scriptPath && path.basename(this._scriptPath, path.extname(this._scriptPath))); - - return userArgs; - } - - /** - * 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 - */ - - parse(argv, parseOptions) { - const userArgs = this._prepareUserArgs(argv, parseOptions); - this._parseCommand([], userArgs); - - return this; - }; - - /** - * 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: - * - * await program.parseAsync(process.argv); - * await program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions - * await 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} - */ - - async parseAsync(argv, parseOptions) { - const userArgs = this._prepareUserArgs(argv, parseOptions); - await this._parseCommand([], userArgs); - - return this; - }; - - /** - * Execute a sub-command executable. - * - * @api private - */ - - _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']; - - // Not checking for help first. Unlikely to have mandatory and executable, and can't robustly test for help flags in external command. - this._checkForMissingMandatoryOptions(); - - // 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; - } - - let baseDir; - try { - const resolvedLink = fs.realpathSync(scriptPath); - baseDir = path.dirname(resolvedLink); - } catch (e) { - baseDir = '.'; // dummy, probably not going to find executable! - } - - // name of the subcommand, like `pm-install` - let bin = path.basename(scriptPath, path.extname(scriptPath)) + '-' + subcommand._name; - if (subcommand._executableFile) { - bin = subcommand._executableFile; - } - - 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)); - - let proc; - if (process.platform !== 'win32') { - if (launchWithNode) { - args.unshift(bin); - // add executable arguments to spawn - args = incrementNodeInspectorPort(process.execArgv).concat(args); - - proc = childProcess.spawn(process.argv[0], args, { stdio: 'inherit' }); - } else { - proc = childProcess.spawn(bin, args, { stdio: 'inherit' }); - } - } else { - args.unshift(bin); - // add executable arguments to spawn - args = incrementNodeInspectorPort(process.execArgv).concat(args); - proc = childProcess.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); - } - }); - }); - - // 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', (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; - }; - - /** - * @api private - */ - - _dispatchSubcommand(commandName, operands, unknown) { - const subCommand = this._findCommand(commandName); - if (!subCommand) this.help({ error: true }); - - if (subCommand._executableHandler) { - this._executeSubCommand(subCommand, operands.concat(unknown)); - } else { - return subCommand._parseCommand(operands, unknown); - } - }; - - /** - * Package arguments (this.args) for passing to action handler based - * on declared arguments (this._args). - * - * @api private - */ - - _getActionArguments() { - const myParseArg = (argument, value, previous) => { - // Extra processing for nice error message on parsing failure. - let parsedValue = value; - if (value !== null && argument.parseArg) { - try { - parsedValue = argument.parseArg(value, previous); - } catch (err) { - if (err.code === 'commander.invalidArgument') { - const message = `error: command-argument value '${value}' is invalid for argument '${argument.name()}'. ${err.message}`; - this._displayError(err.exitCode, err.code, message); - } - throw err; - } - } - return parsedValue; - }; - - const actionArgs = []; - this._args.forEach((declaredArg, index) => { - let value = declaredArg.defaultValue; - if (declaredArg.variadic) { - // Collect together remaining arguments for passing together as an array. - if (index < this.args.length) { - value = this.args.slice(index); - if (declaredArg.parseArg) { - value = value.reduce((processed, v) => { - return myParseArg(declaredArg, v, processed); - }, declaredArg.defaultValue); - } - } else if (value === undefined) { - value = []; - } - } else if (index < this.args.length) { - value = this.args[index]; - if (declaredArg.parseArg) { - value = myParseArg(declaredArg, value, declaredArg.defaultValue); - } - } - actionArgs[index] = value; - }); - return actionArgs; - } - - /** - * Once we have a promise we chain, but call synchronously until then. - * - * @param {Promise|undefined} promise - * @param {Function} fn - * @return {Promise|undefined} - */ - - _chainOrCall(promise, fn) { - // thenable - if (promise && promise.then && typeof promise.then === 'function') { - // already have a promise, chain callback - return promise.then(() => fn()); - } - // callback might return a promise - return fn(); - } - - /** - * - * @param {Promise|undefined} promise - * @param {string} event - * @return {Promise|undefined} - * @api private - */ - - _chainOrCallHooks(promise, event) { - let result = promise; - const hooks = []; - getCommandAndParents(this) - .reverse() - .filter(cmd => cmd._lifeCycleHooks[event] !== undefined) - .forEach(hookedCommand => { - hookedCommand._lifeCycleHooks[event].forEach((callback) => { - hooks.push({ hookedCommand, callback }); - }); - }); - if (event === 'postAction') { - hooks.reverse(); - } - - hooks.forEach((hookDetail) => { - result = this._chainOrCall(result, () => { - return hookDetail.callback(hookDetail.hookedCommand, this); - }); - }); - return result; - } - - /** - * Process arguments in context of this command. - * Returns action result, in case it is a promise. - * - * @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])) { - return this._dispatchSubcommand(operands[0], operands.slice(1), unknown); - } - if (this._hasImplicitHelpCommand() && operands[0] === this._helpCommandName) { - if (operands.length === 1) { - this.help(); - } - return this._dispatchSubcommand(operands[1], [], [this._helpLongFlag]); - } - if (this._defaultCommandName) { - outputHelpIfRequested(this, unknown); // Run the help for default command from parent rather than passing to default command - return this._dispatchSubcommand(this._defaultCommandName, operands, unknown); - } - if (this.commands.length && this.args.length === 0 && !this._actionHandler && !this._defaultCommandName) { - // probably missing subcommand and no handler, user needs help (and exit) - this.help({ error: true }); - } - - outputHelpIfRequested(this, parsed.unknown); - this._checkForMissingMandatoryOptions(); - - // 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]); - } - }; - const checkNumberOfArguments = () => { - // too few - this._args.forEach((arg, i) => { - if (arg.required && this.args[i] == null) { - this.missingArgument(arg.name()); - } - }); - // too many - if (this._args.length > 0 && this._args[this._args.length - 1].variadic) { - return; - } - if (this.args.length > this._args.length) { - this._excessArguments(this.args); - } - }; - - const commandEvent = `command:${this.name()}`; - if (this._actionHandler) { - checkForUnknownOptions(); - checkNumberOfArguments(); - - let actionResult; - actionResult = this._chainOrCallHooks(actionResult, 'preAction'); - actionResult = this._chainOrCall(actionResult, () => this._actionHandler(this._getActionArguments())); - if (this.parent) this.parent.emit(commandEvent, operands, unknown); // legacy - actionResult = this._chainOrCallHooks(actionResult, 'postAction'); - return actionResult; - } - if (this.parent && this.parent.listenerCount(commandEvent)) { - checkForUnknownOptions(); - checkNumberOfArguments(); - this.parent.emit(commandEvent, operands, unknown); // legacy - } else if (operands.length) { - if (this._findCommand('*')) { // legacy default command - return this._dispatchSubcommand('*', operands, unknown); - } - 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(); - checkNumberOfArguments(); - } - } else if (this.commands.length) { - // This command has subcommands and nothing hooked up at this level, so display help (and exit). - this.help({ error: true }); - } else { - checkForUnknownOptions(); - checkNumberOfArguments(); - // fall through for caller to handle after calling .parse() - } - }; - - /** - * Find matching command. - * - * @api private - */ - _findCommand(name) { - if (!name) return undefined; - return this.commands.find(cmd => cmd._name === name || cmd._aliases.includes(name)); - }; - - /** - * Return an option matching `arg` if any. - * - * @param {string} arg - * @return {Option} - * @api private - */ - - _findOption(arg) { - return this.options.find(option => option.is(arg)); - }; - - /** - * 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 - */ - - _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); - } - }); - } - }; - - /** - * 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[]}} - */ - - 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(); - - function maybeOption(arg) { - return arg.length > 1 && arg[0] === '-'; - } - - // parse options - let activeVariadicOption = null; - while (args.length) { - const arg = args.shift(); - - // literal - if (arg === '--') { - if (dest === unknown) dest.push(arg); - dest.push(...args); - break; - } - - 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; - } - } - - // 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; - } - } - - // 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; - } - } - - // Not a recognised option by this command. - // Might be a command-argument, or subcommand option, or unknown option, or help command or option. - - // An unknown option means further arguments also classified as unknown so can be reprocessed by subcommands. - if (maybeOption(arg)) { - dest = unknown; - } - - // 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; - } - } - - // If using passThroughOptions, stop processing options at first command-argument. - if (this._passThroughOptions) { - dest.push(arg); - if (args.length > 0) dest.push(...args); - break; - } - - // add arg - dest.push(arg); - } - - return { operands, unknown }; - }; - - /** - * 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; - } - - return this._optionValues; - }; - - /** - * 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); - } - - /** - * Argument `name` is missing. - * - * @param {string} name - * @api private - */ - - missingArgument(name) { - const message = `error: missing required argument '${name}'`; - this._displayError(1, 'commander.missingArgument', message); - }; - - /** - * `Option` is missing an argument. - * - * @param {Option} option - * @api private - */ - - optionMissingArgument(option) { - const message = `error: option '${option.flags}' argument missing`; - this._displayError(1, 'commander.optionMissingArgument', message); - }; - - /** - * `Option` does not have a value, and is a mandatory option. - * - * @param {Option} option - * @api private - */ - - missingMandatoryOptionValue(option) { - const message = `error: required option '${option.flags}' not specified`; - this._displayError(1, 'commander.missingMandatoryOptionValue', message); - }; - - /** - * Unknown option `flag`. - * - * @param {string} flag - * @api private - */ - - unknownOption(flag) { - if (this._allowUnknownOption) return; - const message = `error: unknown option '${flag}'`; - this._displayError(1, 'commander.unknownOption', message); - }; - - /** - * Excess arguments, more than expected. - * - * @param {string[]} receivedArgs - * @api private - */ - - _excessArguments(receivedArgs) { - if (this._allowExcessArguments) return; - - 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); - }; - - /** - * Unknown command. - * - * @api private - */ - - 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); - }; - - /** - * 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 - */ - - 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; - }; - - /** - * 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; - if (argsDescription) { - this._argsDescription = argsDescription; - } - return this; - }; - - /** - * 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} - */ - - alias(alias) { - if (alias === undefined) return this._aliases[0]; // just return first, for backwards compatibility - - 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 (alias === command._name) throw new Error('Command alias can\'t be the same as its name'); - - command._aliases.push(alias); - return this; - }; - - /** - * Set aliases for the command. - * - * Only the first alias is shown in the auto-generated help. - * - * @param {string[]} [aliases] - * @return {string[]|Command} - */ - - 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; - - aliases.forEach((alias) => this.alias(alias)); - return this; - }; - - /** - * Set / get the command usage `str`. - * - * @param {string} [str] - * @return {String|Command} - */ - - usage(str) { - if (str === undefined) { - if (this._usage) return this._usage; - - 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(' '); - } - - this._usage = str; - return this; - }; - - /** - * Get or set the name of the command - * - * @param {string} [str] - * @return {string|Command} - */ - - name(str) { - if (str === undefined) return this._name; - this._name = str; - return this; - }; - - /** - * Return program help documentation. - * - * @param {{ error: boolean }} [contextOptions] - pass {error:true} to wrap for stderr instead of stdout - * @return {string} - */ - - 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); - }; - - /** - * @api private - */ - - _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); - } - 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 - */ - - outputHelp(contextOptions) { - let deprecatedCallback; - if (typeof contextOptions === 'function') { - deprecatedCallback = contextOptions; - contextOptions = undefined; - } - const context = this._getHelpContext(contextOptions); - - const groupListeners = []; - let command = this; - while (command) { - groupListeners.push(command); // ordered from current command to root - command = command.parent; - } - - groupListeners.slice().reverse().forEach(command => command.emit('beforeAllHelp', context)); - this.emit('beforeHelp', context); - - 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); - - this.emit(this._helpLongFlag); // deprecated - this.emit('afterHelp', context); - groupListeners.forEach(command => command.emit('afterAllHelp', context)); - }; - - /** - * 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 - */ - - helpOption(flags, description) { - if (typeof flags === 'boolean') { - this._hasHelpOption = flags; - return this; - } - this._helpFlags = flags || this._helpFlags; - this._helpDescription = description || this._helpDescription; - - const helpFlags = _parseOptionFlags(this._helpFlags); - this._helpShortFlag = helpFlags.shortFlag; - this._helpLongFlag = helpFlags.longFlag; - - return this; - }; - - /** - * 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 - */ - - help(contextOptions) { - this.outputHelp(contextOptions); - let exitCode = process.exitCode || 0; - if (exitCode === 0 && contextOptions && typeof contextOptions !== 'function' && contextOptions.error) { - exitCode = 1; - } - // 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; - } -}; - /** * Expose the root command. */ exports = module.exports = new Command(); exports.program = exports; // More explicit access to global command. +// Implicit export of createArgument, createCommand, and createOption. /** * Expose classes */ -exports.Command = Command; -exports.Option = Option; exports.Argument = Argument; +exports.Command = Command; exports.CommanderError = CommanderError; +exports.Help = Help; exports.InvalidArgumentError = InvalidArgumentError; exports.InvalidOptionArgumentError = InvalidArgumentError; // Deprecated -exports.Help = Help; - -/** - * Camel-case the given `flag` - * - * @param {string} flag - * @return {string} - * @api private - */ - -function camelcase(flag) { - return flag.split('-').reduce((str, word) => { - return str + word[0].toUpperCase() + word.slice(1); - }); -} - -/** - * 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 - * @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)'); - } -} - -/** - * Takes an argument and returns its human readable equivalent for help usage. - * - * @param {Argument} arg - * @return {string} - * @api private - */ - -function humanReadableArgName(arg) { - const 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; - } - return { shortFlag, longFlag }; -} - -/** - * Scan arguments and increment port number for inspect calls (to avoid conflicts when spawning new command). - * - * @param {string[]} args - array of arguments from node.execArgv - * @returns {string[]} - * @api private - */ - -function incrementNodeInspectorPort(args) { - // Testing for these options: - // --inspect[=[host:]port] - // --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 - 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]; - } - - if (debugOption && debugPort !== '0') { - return `${debugOption}=${debugHost}:${parseInt(debugPort) + 1}`; - } - return arg; - }); -} - -/** - * @param {Command} startCommand - * @returns {Command[]} - * @api private - */ - -function getCommandAndParents(startCommand) { - const result = []; - for (let command = startCommand; command; command = command.parent) { - result.push(command); - } - return result; -} +exports.Option = Option; diff --git a/lib/argument.js b/lib/argument.js new file mode 100644 index 000000000..8f8ab419a --- /dev/null +++ b/lib/argument.js @@ -0,0 +1,95 @@ +// @ts-check + +class Argument { + /** + * Initialize a new command argument with the given name and description. + * The default is that the argument is required, and you can explicitly + * indicate this with <> around the name. Put [] around the name for an optional argument. + * + * @param {string} name + * @param {string} [description] + */ + + constructor(name, description) { + this.description = description || ''; + this.variadic = false; + this.parseArg = undefined; + this.defaultValue = undefined; + this.defaultValueDescription = undefined; + + switch (name[0]) { + case '<': // e.g. + this.required = true; + this._name = name.slice(1, -1); + break; + case '[': // e.g. [optional] + this.required = false; + this._name = name.slice(1, -1); + break; + default: + this.required = true; + this._name = name; + break; + } + + if (this._name.length > 3 && this._name.slice(-3) === '...') { + this.variadic = true; + this._name = this._name.slice(0, -3); + } + } + + /** + * Return argument name. + * + * @return {string} + */ + + name() { + return this._name; + }; + + /** + * Set the default value, and optionally supply the description to be displayed in the help. + * + * @param {any} value + * @param {string} [description] + * @return {Argument} + */ + + default(value, description) { + this.defaultValue = value; + this.defaultValueDescription = description; + return this; + }; + + /** + * Set the custom handler for processing CLI command arguments into argument values. + * + * @param {Function} [fn] + * @return {Argument} + */ + + argParser(fn) { + this.parseArg = fn; + return this; + }; +} + +/** + * Takes an argument and returns its human readable equivalent for help usage. + * + * @param {Argument} arg + * @return {string} + * @api private + */ + +function humanReadableArgName(arg) { + const nameOutput = arg.name() + (arg.variadic === true ? '...' : ''); + + return arg.required + ? '<' + nameOutput + '>' + : '[' + nameOutput + ']'; +} + +exports.Argument = Argument; +exports.humanReadableArgName = humanReadableArgName; diff --git a/lib/command.js b/lib/command.js new file mode 100644 index 000000000..175213ae1 --- /dev/null +++ b/lib/command.js @@ -0,0 +1,1810 @@ +const EventEmitter = require('events').EventEmitter; +const childProcess = require('child_process'); +const path = require('path'); +const fs = require('fs'); + +const { Argument, humanReadableArgName } = require('./argument.js'); +const { CommanderError } = require('./error.js'); +const { Help } = require('./help.js'); +const { Option, splitOptionFlags } = require('./option.js'); + +// @ts-check + +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._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; // legacy + this._enablePositionalOptions = false; + this._passThroughOptions = false; + this._lifeCycleHooks = {}; // a hash of arrays + + // 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 [, name, args] = nameAndArgs.match(/([^ ]+) *(.*)/); + const cmd = this.createCommand(name); + + 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 + if (args) cmd.arguments(args); + this.commands.push(cmd); + 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 + */ + + configureHelp(configuration) { + if (configuration === undefined) return this._helpConfiguration; + + this._helpConfiguration = configuration; + return this; + } + + /** + * 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; + } + + /** + * 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); + + opts = opts || {}; + if (opts.isDefault) this._defaultCommandName = cmd._name; + if (opts.noHelp || opts.hidden) cmd._hidden = true; // modifying passed command due to existing implementation + + this.commands.push(cmd); + cmd.parent = this; + return this; + }; + + /** + * Factory routine to create a new unattached argument. + * + * See .argument() for creating an attached argument, which uses this routine to + * create the argument. You can override createArgument to return a custom argument. + * + * @param {string} name + * @param {string} [description] + * @return {Argument} new argument + */ + + createArgument(name, description) { + return new Argument(name, description); + }; + + /** + * Define argument syntax for command. + * + * The default is that the argument is required, and you can explicitly + * indicate this with <> around the name. Put [] around the name for an optional argument. + * + * @example + * + * program.argument(''); + * program.argument('[output-file]'); + * + * @param {string} name + * @param {string} [description] + * @param {Function|*} [fn] - custom argument processing function + * @param {*} [defaultValue] + * @return {Command} `this` command for chaining + */ + argument(name, description, fn, defaultValue) { + const argument = this.createArgument(name, description); + if (typeof fn === 'function') { + argument.default(defaultValue).argParser(fn); + } else { + argument.default(fn); + } + this.addArgument(argument); + return this; + } + + /** + * Define argument syntax for command, adding multiple at once (without descriptions). + * + * See also .argument(). + * + * @example + * + * program.arguments(' [env]'); + * + * @param {string} names + * @return {Command} `this` command for chaining + */ + + arguments(names) { + names.split(/ +/).forEach((detail) => { + this.argument(detail); + }); + return this; + }; + + /** + * Define argument syntax for command, adding a prepared argument. + * + * @param {Argument} argument + * @return {Command} `this` command for chaining + */ + addArgument(argument) { + const previousArgument = this._args.slice(-1)[0]; + if (previousArgument && previousArgument.variadic) { + throw new Error(`only the last argument can be variadic '${previousArgument.name()}'`); + } + if (argument.required && argument.defaultValue !== undefined && argument.parseArg === undefined) { + throw new Error(`a default value for a required argument is never used: '${argument.name()}'`); + } + this._args.push(argument); + return this; + } + + /** + * 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 + */ + + 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; + } + return this; + }; + + /** + * @return {boolean} + * @api private + */ + + _hasImplicitHelpCommand() { + if (this._addImplicitHelpCommand === undefined) { + return this.commands.length && !this._actionHandler && !this._findCommand('help'); + } + return this._addImplicitHelpCommand; + }; + + /** + * Add hook for life cycle event. + * + * @param {string} event + * @param {Function} listener + * @return {Command} `this` command for chaining + */ + + hook(event, listener) { + const allowedValues = ['preAction', 'postAction']; + if (!allowedValues.includes(event)) { + throw new Error(`Unexpected value for event passed to hook : '${event}'. +Expecting one of '${allowedValues.join("', '")}'`); + } + if (this._lifeCycleHooks[event]) { + this._lifeCycleHooks[event].push(listener); + } else { + this._lifeCycleHooks[event] = [listener]; + } + 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 + */ + + _exit(exitCode, code, message) { + if (this._exitCallback) { + this._exitCallback(new CommanderError(exitCode, code, message)); + // Expecting this line is not reached. + } + process.exit(exitCode); + }; + + /** + * 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 + */ + + 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); + + return fn.apply(this, actionArgs); + }; + this._actionHandler = listener; + return this; + }; + + /** + * 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 + */ + + createOption(flags, description) { + return new Option(flags, description); + }; + + /** + * 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); + } + } + + // 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.invalidArgument') { + 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); + } + + // 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); + } + } else if (val !== null) { + // reassign + this.setOptionValue(name, option.negate ? false : val); + } + }); + + return this; + } + + /** + * 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); + return m ? m[0] : def; + }; + option.default(defaultValue).argParser(fn); + } else { + option.default(fn); + } + + return this.addOption(option); + } + + /** + * 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 + */ + + option(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 contains the short and/or long flags, separated by comma, a pipe or space. + * + * @param {string} flags + * @param {string} [description] + * @param {Function|*} [fn] - custom option processing function or default value + * @param {*} [defaultValue] + * @return {Command} `this` command for chaining + */ + + requiredOption(flags, description, fn, defaultValue) { + return this._optionEx({ mandatory: true }, flags, description, fn, defaultValue); + }; + + /** + * 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; + }; + + /** + * 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; + }; + + /** + * 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; + }; + + /** + * 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; + }; + + /** + * 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; + }; + + /** + * 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; + }; + + /** + * Retrieve option value. + * + * @param {string} key + * @return {Object} value + */ + + getOptionValue(key) { + if (this._storeOptionsAsProperties) { + return this[key]; + } + return this._optionValues[key]; + }; + + /** + * Store option value. + * + * @param {string} key + * @param {Object} value + * @return {Command} `this` command for chaining + */ + + setOptionValue(key, value) { + if (this._storeOptionsAsProperties) { + this[key] = value; + } else { + this._optionValues[key] = value; + } + return this; + }; + + /** + * Get user arguments implied or explicit arguments. + * Side-effects: set _scriptPath if args included application, and use that to set implicit command name. + * + * @api private + */ + + _prepareUserArgs(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; + } + + // Guess name, used in usage in help. + this._name = this._name || (this._scriptPath && path.basename(this._scriptPath, path.extname(this._scriptPath))); + + return userArgs; + } + + /** + * 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 + */ + + parse(argv, parseOptions) { + const userArgs = this._prepareUserArgs(argv, parseOptions); + this._parseCommand([], userArgs); + + return this; + }; + + /** + * 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: + * + * await program.parseAsync(process.argv); + * await program.parseAsync(); // implicitly use process.argv and auto-detect node vs electron conventions + * await 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} + */ + + async parseAsync(argv, parseOptions) { + const userArgs = this._prepareUserArgs(argv, parseOptions); + await this._parseCommand([], userArgs); + + return this; + }; + + /** + * Execute a sub-command executable. + * + * @api private + */ + + _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']; + + // Not checking for help first. Unlikely to have mandatory and executable, and can't robustly test for help flags in external command. + this._checkForMissingMandatoryOptions(); + + // 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; + } + + let baseDir; + try { + const resolvedLink = fs.realpathSync(scriptPath); + baseDir = path.dirname(resolvedLink); + } catch (e) { + baseDir = '.'; // dummy, probably not going to find executable! + } + + // name of the subcommand, like `pm-install` + let bin = path.basename(scriptPath, path.extname(scriptPath)) + '-' + subcommand._name; + if (subcommand._executableFile) { + bin = subcommand._executableFile; + } + + 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)); + + let proc; + if (process.platform !== 'win32') { + if (launchWithNode) { + args.unshift(bin); + // add executable arguments to spawn + args = incrementNodeInspectorPort(process.execArgv).concat(args); + + proc = childProcess.spawn(process.argv[0], args, { stdio: 'inherit' }); + } else { + proc = childProcess.spawn(bin, args, { stdio: 'inherit' }); + } + } else { + args.unshift(bin); + // add executable arguments to spawn + args = incrementNodeInspectorPort(process.execArgv).concat(args); + proc = childProcess.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); + } + }); + }); + + // 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', (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; + }; + + /** + * @api private + */ + + _dispatchSubcommand(commandName, operands, unknown) { + const subCommand = this._findCommand(commandName); + if (!subCommand) this.help({ error: true }); + + if (subCommand._executableHandler) { + this._executeSubCommand(subCommand, operands.concat(unknown)); + } else { + return subCommand._parseCommand(operands, unknown); + } + }; + + /** + * Package arguments (this.args) for passing to action handler based + * on declared arguments (this._args). + * + * @api private + */ + + _getActionArguments() { + const myParseArg = (argument, value, previous) => { + // Extra processing for nice error message on parsing failure. + let parsedValue = value; + if (value !== null && argument.parseArg) { + try { + parsedValue = argument.parseArg(value, previous); + } catch (err) { + if (err.code === 'commander.invalidArgument') { + const message = `error: command-argument value '${value}' is invalid for argument '${argument.name()}'. ${err.message}`; + this._displayError(err.exitCode, err.code, message); + } + throw err; + } + } + return parsedValue; + }; + + const actionArgs = []; + this._args.forEach((declaredArg, index) => { + let value = declaredArg.defaultValue; + if (declaredArg.variadic) { + // Collect together remaining arguments for passing together as an array. + if (index < this.args.length) { + value = this.args.slice(index); + if (declaredArg.parseArg) { + value = value.reduce((processed, v) => { + return myParseArg(declaredArg, v, processed); + }, declaredArg.defaultValue); + } + } else if (value === undefined) { + value = []; + } + } else if (index < this.args.length) { + value = this.args[index]; + if (declaredArg.parseArg) { + value = myParseArg(declaredArg, value, declaredArg.defaultValue); + } + } + actionArgs[index] = value; + }); + return actionArgs; + } + + /** + * Once we have a promise we chain, but call synchronously until then. + * + * @param {Promise|undefined} promise + * @param {Function} fn + * @return {Promise|undefined} + */ + + _chainOrCall(promise, fn) { + // thenable + if (promise && promise.then && typeof promise.then === 'function') { + // already have a promise, chain callback + return promise.then(() => fn()); + } + // callback might return a promise + return fn(); + } + + /** + * + * @param {Promise|undefined} promise + * @param {string} event + * @return {Promise|undefined} + * @api private + */ + + _chainOrCallHooks(promise, event) { + let result = promise; + const hooks = []; + getCommandAndParents(this) + .reverse() + .filter(cmd => cmd._lifeCycleHooks[event] !== undefined) + .forEach(hookedCommand => { + hookedCommand._lifeCycleHooks[event].forEach((callback) => { + hooks.push({ hookedCommand, callback }); + }); + }); + if (event === 'postAction') { + hooks.reverse(); + } + + hooks.forEach((hookDetail) => { + result = this._chainOrCall(result, () => { + return hookDetail.callback(hookDetail.hookedCommand, this); + }); + }); + return result; + } + + /** + * Process arguments in context of this command. + * Returns action result, in case it is a promise. + * + * @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])) { + return this._dispatchSubcommand(operands[0], operands.slice(1), unknown); + } + if (this._hasImplicitHelpCommand() && operands[0] === this._helpCommandName) { + if (operands.length === 1) { + this.help(); + } + return this._dispatchSubcommand(operands[1], [], [this._helpLongFlag]); + } + if (this._defaultCommandName) { + outputHelpIfRequested(this, unknown); // Run the help for default command from parent rather than passing to default command + return this._dispatchSubcommand(this._defaultCommandName, operands, unknown); + } + if (this.commands.length && this.args.length === 0 && !this._actionHandler && !this._defaultCommandName) { + // probably missing subcommand and no handler, user needs help (and exit) + this.help({ error: true }); + } + + outputHelpIfRequested(this, parsed.unknown); + this._checkForMissingMandatoryOptions(); + + // 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]); + } + }; + const checkNumberOfArguments = () => { + // too few + this._args.forEach((arg, i) => { + if (arg.required && this.args[i] == null) { + this.missingArgument(arg.name()); + } + }); + // too many + if (this._args.length > 0 && this._args[this._args.length - 1].variadic) { + return; + } + if (this.args.length > this._args.length) { + this._excessArguments(this.args); + } + }; + + const commandEvent = `command:${this.name()}`; + if (this._actionHandler) { + checkForUnknownOptions(); + checkNumberOfArguments(); + + let actionResult; + actionResult = this._chainOrCallHooks(actionResult, 'preAction'); + actionResult = this._chainOrCall(actionResult, () => this._actionHandler(this._getActionArguments())); + if (this.parent) this.parent.emit(commandEvent, operands, unknown); // legacy + actionResult = this._chainOrCallHooks(actionResult, 'postAction'); + return actionResult; + } + if (this.parent && this.parent.listenerCount(commandEvent)) { + checkForUnknownOptions(); + checkNumberOfArguments(); + this.parent.emit(commandEvent, operands, unknown); // legacy + } else if (operands.length) { + if (this._findCommand('*')) { // legacy default command + return this._dispatchSubcommand('*', operands, unknown); + } + 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(); + checkNumberOfArguments(); + } + } else if (this.commands.length) { + // This command has subcommands and nothing hooked up at this level, so display help (and exit). + this.help({ error: true }); + } else { + checkForUnknownOptions(); + checkNumberOfArguments(); + // fall through for caller to handle after calling .parse() + } + }; + + /** + * Find matching command. + * + * @api private + */ + _findCommand(name) { + if (!name) return undefined; + return this.commands.find(cmd => cmd._name === name || cmd._aliases.includes(name)); + }; + + /** + * Return an option matching `arg` if any. + * + * @param {string} arg + * @return {Option} + * @api private + */ + + _findOption(arg) { + return this.options.find(option => option.is(arg)); + }; + + /** + * 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 + */ + + _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); + } + }); + } + }; + + /** + * 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[]}} + */ + + 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(); + + function maybeOption(arg) { + return arg.length > 1 && arg[0] === '-'; + } + + // parse options + let activeVariadicOption = null; + while (args.length) { + const arg = args.shift(); + + // literal + if (arg === '--') { + if (dest === unknown) dest.push(arg); + dest.push(...args); + break; + } + + 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; + } + } + + // 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; + } + } + + // 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; + } + } + + // Not a recognised option by this command. + // Might be a command-argument, or subcommand option, or unknown option, or help command or option. + + // An unknown option means further arguments also classified as unknown so can be reprocessed by subcommands. + if (maybeOption(arg)) { + dest = unknown; + } + + // 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; + } + } + + // If using passThroughOptions, stop processing options at first command-argument. + if (this._passThroughOptions) { + dest.push(arg); + if (args.length > 0) dest.push(...args); + break; + } + + // add arg + dest.push(arg); + } + + return { operands, unknown }; + }; + + /** + * 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; + } + + return this._optionValues; + }; + + /** + * 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); + } + + /** + * Argument `name` is missing. + * + * @param {string} name + * @api private + */ + + missingArgument(name) { + const message = `error: missing required argument '${name}'`; + this._displayError(1, 'commander.missingArgument', message); + }; + + /** + * `Option` is missing an argument. + * + * @param {Option} option + * @api private + */ + + optionMissingArgument(option) { + const message = `error: option '${option.flags}' argument missing`; + this._displayError(1, 'commander.optionMissingArgument', message); + }; + + /** + * `Option` does not have a value, and is a mandatory option. + * + * @param {Option} option + * @api private + */ + + missingMandatoryOptionValue(option) { + const message = `error: required option '${option.flags}' not specified`; + this._displayError(1, 'commander.missingMandatoryOptionValue', message); + }; + + /** + * Unknown option `flag`. + * + * @param {string} flag + * @api private + */ + + unknownOption(flag) { + if (this._allowUnknownOption) return; + const message = `error: unknown option '${flag}'`; + this._displayError(1, 'commander.unknownOption', message); + }; + + /** + * Excess arguments, more than expected. + * + * @param {string[]} receivedArgs + * @api private + */ + + _excessArguments(receivedArgs) { + if (this._allowExcessArguments) return; + + 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); + }; + + /** + * Unknown command. + * + * @api private + */ + + 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); + }; + + /** + * 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 + */ + + 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; + }; + + /** + * 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; + if (argsDescription) { + this._argsDescription = argsDescription; + } + return this; + }; + + /** + * 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} + */ + + alias(alias) { + if (alias === undefined) return this._aliases[0]; // just return first, for backwards compatibility + + 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 (alias === command._name) throw new Error('Command alias can\'t be the same as its name'); + + command._aliases.push(alias); + return this; + }; + + /** + * Set aliases for the command. + * + * Only the first alias is shown in the auto-generated help. + * + * @param {string[]} [aliases] + * @return {string[]|Command} + */ + + 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; + + aliases.forEach((alias) => this.alias(alias)); + return this; + }; + + /** + * Set / get the command usage `str`. + * + * @param {string} [str] + * @return {String|Command} + */ + + usage(str) { + if (str === undefined) { + if (this._usage) return this._usage; + + 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(' '); + } + + this._usage = str; + return this; + }; + + /** + * Get or set the name of the command + * + * @param {string} [str] + * @return {string|Command} + */ + + name(str) { + if (str === undefined) return this._name; + this._name = str; + return this; + }; + + /** + * Return program help documentation. + * + * @param {{ error: boolean }} [contextOptions] - pass {error:true} to wrap for stderr instead of stdout + * @return {string} + */ + + 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); + }; + + /** + * @api private + */ + + _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); + } + 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 + */ + + outputHelp(contextOptions) { + let deprecatedCallback; + if (typeof contextOptions === 'function') { + deprecatedCallback = contextOptions; + contextOptions = undefined; + } + const context = this._getHelpContext(contextOptions); + + const groupListeners = []; + let command = this; + while (command) { + groupListeners.push(command); // ordered from current command to root + command = command.parent; + } + + groupListeners.slice().reverse().forEach(command => command.emit('beforeAllHelp', context)); + this.emit('beforeHelp', context); + + 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); + + this.emit(this._helpLongFlag); // deprecated + this.emit('afterHelp', context); + groupListeners.forEach(command => command.emit('afterAllHelp', context)); + }; + + /** + * 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 + */ + + helpOption(flags, description) { + if (typeof flags === 'boolean') { + this._hasHelpOption = flags; + return this; + } + this._helpFlags = flags || this._helpFlags; + this._helpDescription = description || this._helpDescription; + + const helpFlags = splitOptionFlags(this._helpFlags); + this._helpShortFlag = helpFlags.shortFlag; + this._helpLongFlag = helpFlags.longFlag; + + return this; + }; + + /** + * 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 + */ + + help(contextOptions) { + this.outputHelp(contextOptions); + let exitCode = process.exitCode || 0; + if (exitCode === 0 && contextOptions && typeof contextOptions !== 'function' && contextOptions.error) { + exitCode = 1; + } + // 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; + } +}; + +/** + * 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 + * @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)'); + } +} + +/** + * Scan arguments and increment port number for inspect calls (to avoid conflicts when spawning new command). + * + * @param {string[]} args - array of arguments from node.execArgv + * @returns {string[]} + * @api private + */ + +function incrementNodeInspectorPort(args) { + // Testing for these options: + // --inspect[=[host:]port] + // --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 + 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]; + } + + if (debugOption && debugPort !== '0') { + return `${debugOption}=${debugHost}:${parseInt(debugPort) + 1}`; + } + return arg; + }); +} + +/** + * @param {Command} startCommand + * @returns {Command[]} + * @api private + */ + +function getCommandAndParents(startCommand) { + const result = []; + for (let command = startCommand; command; command = command.parent) { + result.push(command); + } + return result; +} + +exports.Command = Command; diff --git a/lib/error.js b/lib/error.js new file mode 100644 index 000000000..e7cde9cc7 --- /dev/null +++ b/lib/error.js @@ -0,0 +1,45 @@ +// @ts-check + +/** + * CommanderError class + * @class + */ +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 + * @constructor + */ + constructor(exitCode, code, message) { + super(message); + // properly capture stack trace in Node.js + Error.captureStackTrace(this, this.constructor); + this.name = this.constructor.name; + this.code = code; + this.exitCode = exitCode; + this.nestedError = undefined; + } +} + +/** + * InvalidArgumentError class + * @class + */ +class InvalidArgumentError extends CommanderError { + /** + * Constructs the InvalidArgumentError class + * @param {string} [message] explanation of why argument is invalid + * @constructor + */ + constructor(message) { + super(1, 'commander.invalidArgument', message); + // properly capture stack trace in Node.js + Error.captureStackTrace(this, this.constructor); + this.name = this.constructor.name; + } +} + +exports.CommanderError = CommanderError; +exports.InvalidArgumentError = InvalidArgumentError; diff --git a/lib/help.js b/lib/help.js new file mode 100644 index 000000000..99d8f0ee7 --- /dev/null +++ b/lib/help.js @@ -0,0 +1,383 @@ +const { humanReadableArgName } = require('./argument.js'); + +/** + * TypeScript import types for JSDoc, used by Visual Studio Code IntelliSense and `npm run typescript-checkJS` + * https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html#import-types + * @typedef { import("./argument.js").Argument } Argument + * @typedef { import("./command.js").Command } Command + * @typedef { import("./option.js").Option } Option + */ + +// @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 [, helpName, helpArgs] = cmd._helpCommandnameAndArgs.match(/([^ ]+) *(.*)/); + const helpCommand = cmd.createCommand(helpName) + .helpOption(false); + helpCommand.description(cmd._helpCommandDescription); + if (helpArgs) helpCommand.arguments(helpArgs); + 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 if any have a description. + * + * @param {Command} cmd + * @returns {Argument[]} + */ + + visibleArguments(cmd) { + // Side effect! Apply the legacy descriptions before the arguments are displayed. + if (cmd._argsDescription) { + cmd._args.forEach(argument => { + argument.description = argument.description || cmd._argsDescription[argument.name()] || ''; + }); + } + + // If there are any arguments with a description then return all the arguments. + if (cmd._args.find(argument => argument.description)) { + return cmd._args; + }; + 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 argument term to show in the list of arguments. + * + * @param {Argument} argument + * @returns {string} + */ + + argumentTerm(argument) { + return argument.name(); + } + + /** + * 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, helper.argumentTerm(argument).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; + }; + + /** + * Get the argument description to show in the list of arguments. + * + * @param {Argument} argument + * @return {string} + */ + + argumentDescription(argument) { + const extraInfo = []; + if (argument.defaultValue !== undefined) { + extraInfo.push(`default: ${argument.defaultValueDescription || JSON.stringify(argument.defaultValue)}`); + } + if (extraInfo.length > 0) { + return `${argument.description} (${extraInfo.join(', ')})`; + } + return argument.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)); + } + + // Usage + let output = [`Usage: ${helper.commandUsage(cmd)}`, '']; + + // Description + const commandDescription = helper.commandDescription(cmd); + if (commandDescription.length > 0) { + output = output.concat([commandDescription, '']); + } + + // Arguments + const argumentList = helper.visibleArguments(cmd).map((argument) => { + return formatItem(helper.argumentTerm(argument), helper.argumentDescription(argument)); + }); + if (argumentList.length > 0) { + output = output.concat(['Arguments:', formatList(argumentList), '']); + } + + // 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), '']); + } + + // 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), '']); + } + + return output.join('\n'); + } + + /** + * Calculate the pad width from the maximum term length. + * + * @param {Command} cmd + * @param {Help} helper + * @returns {number} + */ + + padWidth(cmd, helper) { + return Math.max( + helper.longestOptionTermLength(cmd, helper), + helper.longestSubcommandTermLength(cmd, helper), + helper.longestArgumentTermLength(cmd, helper) + ); + }; + + /** + * 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} + * + */ + + 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'); + } +} + +exports.Help = Help; diff --git a/lib/option.js b/lib/option.js new file mode 100644 index 000000000..d8c3aa9c3 --- /dev/null +++ b/lib/option.js @@ -0,0 +1,194 @@ +const { InvalidArgumentError } = require('./error.js'); + +// @ts-check + +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 = splitOptionFlags(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 InvalidArgumentError(`Allowed choices are ${values.join(', ')}.`); + } + if (this.variadic) { + return this._concatValue(arg, previous); + } + return arg; + }; + return this; + }; + + /** + * Return option name. + * + * @return {string} + */ + + name() { + if (this.long) { + return this.long.replace(/^--/, ''); + } + return this.short.replace(/^-/, ''); + }; + + /** + * 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-/, '')); + }; + + /** + * 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; + }; +} + +/** + * Convert string from kebab-case to camelCase. + * + * @param {string} str + * @return {string} + * @api private + */ + +function camelcase(str) { + return str.split('-').reduce((str, word) => { + return str + word[0].toUpperCase() + word.slice(1); + }); +} + +/** + * Split the short and long flag out of something like '-m,--mixed ' + * + * @api private + */ + +function splitOptionFlags(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; + } + return { shortFlag, longFlag }; +} + +exports.Option = Option; +exports.splitOptionFlags = splitOptionFlags; diff --git a/package.json b/package.json index 42cce505d..2ba4b8071 100644 --- a/package.json +++ b/package.json @@ -19,17 +19,18 @@ "url": "https://github.com/tj/commander.js.git" }, "scripts": { - "lint": "eslint index.js esm.mjs \"tests/**/*.js\"", + "lint": "eslint index.js esm.mjs \"lib/*.js\" \"tests/**/*.js\"", "typescript-lint": "eslint typings/*.ts tests/*.ts", "test": "jest && npm run test-typings", "test-esm": "node --experimental-modules ./tests/esm-imports-test.mjs", "test-typings": "tsd", - "typescript-checkJS": "tsc --allowJS --checkJS index.js --noEmit", + "typescript-checkJS": "tsc --allowJS --checkJS index.js lib/*.js --noEmit", "test-all": "npm run test && npm run lint && npm run typescript-lint && npm run typescript-checkJS && npm run test-esm" }, "main": "./index.js", "files": [ "index.js", + "lib/*.js", "esm.mjs", "typings/index.d.ts", "package-support.json"