commander 6.0.0 → 6.1.0

package/CHANGELOG.md

@@ -8,13 +8,31 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD004 -->
 
+## [6.1.0] (2020-08-28)
+
+### Added
+
+- include URL to relevant section of README for error for potential conflict between Command properties and option values ([#1306])
+- `.combineFlagAndOptionalValue(false)` to ease upgrade path from older versions of Commander ([#1326])
+- allow disabling the built-in help option using `.helpOption(false)` ([#1325])
+- allow just some arguments in `argumentDescription` to `.description()` ([#1323])
+
+### Changed
+
+- tidy async test and remove lint override ([#1312])
+
+### Fixed
+
+- executable subcommand launching when script path not known ([#1322])
+
 ## [6.0.0] (2020-07-21)
 
 ### Added
 
 - add support for variadic options ([#1250])
 - allow options to be added with just a short flag ([#1256])
-- throw an error if there might be a clash between option name and a Command property, with advice on how to resolve ([#1275])
+  - *Breaking* the option property has same case as flag. e.g. flag `-n` accessed as `opts().n` (previously uppercase)
+- *Breaking* throw an error if there might be a clash between option name and a Command property, with advice on how to resolve ([#1275])
 
 ### Fixed
 
@@ -113,6 +131,9 @@ If you use `program.args` or more complicated tests to detect a missing subcomma
 
 If you use `.command('*')` to add a default command, you may be be able to switch to `isDefault:true` with a named command.
 
+If you want to continue combining short options with optional values as though they were boolean flags, set `combineFlagAndOptionalValue(false)`
+to expand `-fb` to `-f -b` rather than `-f b`.
+
 ## [5.0.0-4] (2020-03-03)
 
 (Released in 5.0.0)
@@ -281,8 +302,15 @@ if (program.rawArgs.length < 3) ...
 [#1256]: https://github.com/tj/commander.js/pull/1256
 [#1275]: https://github.com/tj/commander.js/pull/1275
 [#1301]: https://github.com/tj/commander.js/issues/1301
+[#1306]: https://github.com/tj/commander.js/pull/1306
+[#1312]: https://github.com/tj/commander.js/pull/1312
+[#1322]: https://github.com/tj/commander.js/pull/1322
+[#1323]: https://github.com/tj/commander.js/pull/1323
+[#1325]: https://github.com/tj/commander.js/pull/1325
+[#1326]: https://github.com/tj/commander.js/pull/1326
 
 [Unreleased]: https://github.com/tj/commander.js/compare/master...develop
+[6.1.0]: https://github.com/tj/commander.js/compare/v6.0.0..v6.1.0
 [6.0.0]: https://github.com/tj/commander.js/compare/v5.1.0..v6.0.0
 [6.0.0-0]: https://github.com/tj/commander.js/compare/v5.1.0..v6.0.0-0
 [5.1.0]: https://github.com/tj/commander.js/compare/v5.0.0..v5.1.0

package/Readme.md

@@ -376,18 +376,11 @@ program
   .version('0.1.0')
   .arguments('<cmd> [env]')
   .action(function (cmd, env) {
-    cmdValue = cmd;
-    envValue = env;
+    console.log('command:', cmdValue);
+    console.log('environment:', envValue || 'no environment given');
   });
 
 program.parse(process.argv);
-
-if (typeof cmdValue === 'undefined') {
-  console.error('no command given!');
-  process.exit(1);
-}
-console.log('command:', cmdValue);
-console.log('environment:', envValue || "no environment given");
 ```
 
  The last argument of a command can be variadic, and only the last argument.  To make an argument variadic you
@@ -566,7 +559,7 @@ from `--help` listeners.)
 
 ### .helpOption(flags, description)
 
-Override the default help flags and description.
+Override the default help flags and description. Pass false to disable the built-in help option.
 
 ```js
 program

package/index.js

@@ -127,8 +127,10 @@ class Command extends EventEmitter {
     this._defaultCommandName = null;
     this._exitCallback = null;
     this._aliases = [];
+    this._combineFlagAndOptionalValue = true;
 
     this._hidden = false;
+    this._hasHelpOption = true;
     this._helpFlags = '-h, --help';
     this._helpDescription = 'display help for command';
     this._helpShortFlag = '-h';
@@ -184,6 +186,7 @@ class Command extends EventEmitter {
     if (opts.isDefault) this._defaultCommandName = cmd._name;
 
     cmd._hidden = !!(opts.noHelp || opts.hidden);
+    cmd._hasHelpOption = this._hasHelpOption;
     cmd._helpFlags = this._helpFlags;
     cmd._helpDescription = this._helpDescription;
     cmd._helpShortFlag = this._helpShortFlag;
@@ -194,6 +197,7 @@ class Command extends EventEmitter {
     cmd._exitCallback = this._exitCallback;
     cmd._storeOptionsAsProperties = this._storeOptionsAsProperties;
     cmd._passCommandToAction = this._passCommandToAction;
+    cmd._combineFlagAndOptionalValue = this._combineFlagAndOptionalValue;
 
     cmd._executableFile = opts.executableFile || null; // Custom name for executable file, set missing to null to match constructor
     this.commands.push(cmd);
@@ -468,7 +472,9 @@ class Command extends EventEmitter {
       throw new Error(`option '${option.name()}' clashes with existing property '${option.attributeName()}' on Command
 - call storeOptionsAsProperties(false) to store option values safely,
 - or call storeOptionsAsProperties(true) to suppress this check,
-- or change option name`);
+- or change option name
+
+Read more on https://git.io/JJc0W`);
     }
   };
 
@@ -634,6 +640,23 @@ class Command extends EventEmitter {
     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} [arg] - if `true` or omitted, an optional value can be specified directly after the flag.
+   * @api public
+   */
+  combineFlagAndOptionalValue(arg) {
+    this._combineFlagAndOptionalValue = (arg === undefined) || arg;
+    return this;
+  };
+
   /**
    * Allow unknown options on the command line.
    *
@@ -821,7 +844,11 @@ class Command extends EventEmitter {
     this._checkForMissingMandatoryOptions();
 
     // Want the entry script as the reference for command name and directory for searching for other files.
-    const scriptPath = this._scriptPath;
+    let scriptPath = this._scriptPath;
+    // Fallback in case not set, due to how Command created or called.
+    if (!scriptPath && process.mainModule) {
+      scriptPath = process.mainModule.filename;
+    }
 
     let baseDir;
     try {
@@ -1103,7 +1130,7 @@ class Command extends EventEmitter {
       if (arg.length > 2 && arg[0] === '-' && arg[1] !== '-') {
         const option = this._findOption(`-${arg[1]}`);
         if (option) {
-          if (option.required || option.optional) {
+          if (option.required || (option.optional && this._combineFlagAndOptionalValue)) {
             // option with value following in same argument
             this.emit(`option:${option.name()}`, arg.slice(2));
           } else {
@@ -1230,7 +1257,8 @@ class Command extends EventEmitter {
       partCommands.unshift(parentCmd.name());
     }
     const fullCommand = partCommands.join(' ');
-    const message = `error: unknown command '${this.args[0]}'. See '${fullCommand} ${this._helpLongFlag}'.`;
+    const message = `error: unknown command '${this.args[0]}'.` +
+      (this._hasHelpOption ? ` See '${fullCommand} ${this._helpLongFlag}'.` : '');
     console.error(message);
     this._exit(1, 'commander.unknownCommand', message);
   };
@@ -1339,9 +1367,11 @@ class Command extends EventEmitter {
       const args = this._args.map((arg) => {
         return humanReadableArgName(arg);
       });
-      return '[options]' +
-        (this.commands.length ? ' [command]' : '') +
-        (this._args.length ? ' ' + args.join(' ') : '');
+      return [].concat(
+        (this.options.length || this._hasHelpOption ? '[options]' : []),
+        (this.commands.length ? '[command]' : []),
+        (this._args.length ? args : [])
+      ).join(' ');
     }
 
     this._usage = str;
@@ -1484,8 +1514,8 @@ class Command extends EventEmitter {
     });
 
     // Implicit help
-    const showShortHelpFlag = this._helpShortFlag && !this._findOption(this._helpShortFlag);
-    const showLongHelpFlag = !this._findOption(this._helpLongFlag);
+    const showShortHelpFlag = this._hasHelpOption && this._helpShortFlag && !this._findOption(this._helpShortFlag);
+    const showLongHelpFlag = this._hasHelpOption && !this._findOption(this._helpLongFlag);
     if (showShortHelpFlag || showLongHelpFlag) {
       let helpFlags = this._helpFlags;
       if (!showShortHelpFlag) {
@@ -1548,7 +1578,7 @@ class Command extends EventEmitter {
         desc.push('Arguments:');
         desc.push('');
         this._args.forEach((arg) => {
-          desc.push('  ' + pad(arg.name, width) + '  ' + wrap(argsDescription[arg.name], descriptionWidth, width + 4));
+          desc.push('  ' + pad(arg.name, width) + '  ' + wrap(argsDescription[arg.name] || '', descriptionWidth, width + 4));
         });
         desc.push('');
       }
@@ -1571,11 +1601,14 @@ class Command extends EventEmitter {
     const commandHelp = this.commandHelp();
     if (commandHelp) cmds = [commandHelp];
 
-    const options = [
-      'Options:',
-      '' + this.optionHelp().replace(/^/gm, '  '),
-      ''
-    ];
+    let options = [];
+    if (this._hasHelpOption || this.options.length > 0) {
+      options = [
+        'Options:',
+        '' + this.optionHelp().replace(/^/gm, '  '),
+        ''
+      ];
+    }
 
     return usage
       .concat(desc)
@@ -1609,15 +1642,20 @@ class Command extends EventEmitter {
 
   /**
    * You can pass in flags and a description to override the help
-   * flags and help description for your command.
+   * flags and help description for your command. Pass in false to
+   * disable the built-in help option.
    *
-   * @param {string} [flags]
+   * @param {string | boolean} [flags]
    * @param {string} [description]
    * @return {Command} `this` command for chaining
    * @api public
    */
 
   helpOption(flags, description) {
+    if (typeof flags === 'boolean') {
+      this._hasHelpOption = flags;
+      return this;
+    }
     this._helpFlags = flags || this._helpFlags;
     this._helpDescription = description || this._helpDescription;
 
@@ -1750,7 +1788,7 @@ function optionalWrap(str, width, indent) {
  */
 
 function outputHelpIfRequested(cmd, args) {
-  const helpOption = args.find(arg => arg === cmd._helpLongFlag || arg === cmd._helpShortFlag);
+  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.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",

package/typings/index.d.ts

@@ -201,6 +201,18 @@ declare namespace commander {
      */
     passCommandToAction(value?: boolean): this;
 
+    /**
+     * Alter parsing of short flags with optional values.
+     *
+     * @example
+     *    // 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`
+     *
+     * @returns `this` command for chaining
+     */
+    combineFlagAndOptionalValue(arg?: boolean): this;
+
     /**
      * Allow unknown options on the command line.
      *
@@ -335,9 +347,10 @@ declare namespace commander {
 
     /**
      * You can pass in flags and a description to override the help
-     * flags and help description for your command.
+     * flags and help description for your command. Pass in false
+     * to disable the built-in help option.
      */
-    helpOption(flags?: string, description?: string): this;
+    helpOption(flags?: string | boolean, description?: string): this;
 
     /**
      * Output help information and exit.