commander 7.0.0-2 → 7.0.0

package/CHANGELOG.md

@@ -8,25 +8,51 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD004 -->
 
-## [7.0.0-2] (2020-12-14)
+## [7.0.0] (2021-01-15)
+
+### Added
+
+- `.enablePositionalOptions()` to let program and subcommand reuse same option ([#1427])
+- `.passThroughOptions()` to pass options through to other programs without needing `--` ([#1427])
+- `.allowExcessArguments(false)` to show an error message if there are too many command-arguments on command line for the action handler ([#1409])
+- `.configureOutput()` to modify use of stdout and stderr or customise display of errors ([#1387])
+- use `.addHelpText()` to add text before or after the built-in help, for just current command or also for all subcommands ([#1296])
+- enhance Option class ([#1331])
+  - allow hiding options from help
+  - allow restricting option arguments to a list of choices
+  - allow setting how default value is shown in help
+- `.createOption()` to support subclassing of automatically created options (like `.createCommand()`) ([#1380])
+- refactor the code generating the help into a separate public Help class ([#1365])
+  - support sorting subcommands and options in help
+  - support specifying wrap width (columns)
+  - allow subclassing Help class
+  - allow configuring Help class without subclassing
 
 ### Changed
 
-- *Breaking:* options are stored safely by default, not as properties on the command
+- *Breaking:* options are stored safely by default, not as properties on the command ([#1409])
     - this especially affects accessing options on program, use `program.opts()`
     - revert behaviour with `.storeOptionsAsProperties()`
-- *Breaking:* action handlers are passed options and command separately
-
-### Added
+- *Breaking:* action handlers are passed options and command separately ([#1409])
+- deprecated callback parameter to `.help()` and `.outputHelp()` (removed from README) ([#1296])
+- *Breaking:* errors now displayed using `process.stderr.write()` instead of `console.error()`
+- deprecate `.on('--help')` (removed from README) ([#1296])
+- initialise the command description to empty string (previously undefined) ([#1365])
+- document and annotate deprecated routines ([#1349])
 
-- *Breaking:* error message if there are too many command-arguments on command line for the action handler
-    - if should be allowed then declare extra arguments, or use `.allowExcessArguments()`
+### Fixed
 
+- wrapping bugs in help ([#1365])
+  - first line of command description was wrapping two characters early
+  - pad width calculation was not including help option and help command
+  - pad width calculation was including hidden options and commands
+- improve backwards compatibility for custom command event listeners ([#1403])
+  
 ### Deleted
 
-- *Breaking:* `.passCommandToAction()`
+- *Breaking:* `.passCommandToAction()` ([#1409])
     - no longer needed as action handler is passed options and command
-- *Breaking:* "extra arguments" parameter to action handler
+- *Breaking:* "extra arguments" parameter to action handler ([#1409])
     - if being used to detect excess arguments, there is now an error displayed by default
 
 ### Migration Tips
@@ -96,75 +122,18 @@ program
    });
 ```
 
-**excess command-arguments**
-
-There is now an error if there are too many command-arguments on the command line (only checked if there is an action handler).
-If the extra arguments are supported by your command then you can either declare the expected arguments, or allow excess arguments.
-
-```js
-// Old code before Commander 7
-program
-  .action(() => {});
-program.parse(['a', 'b', 'c'], { from: 'user' }); // now causes an error
-```
-
-```js
-// New code, declare arguments
-program
-  .arguments('[args...]')
-  .action(() => {});
-```
+## [7.0.0-2] (2020-12-14)
 
-```js
-// New code, allow excess arguments
-program
-  .allowExcessArguments()
-  .action(() => {});
-```
+(Released in 7.0.0)
 
 ## [7.0.0-1] (2020-11-21)
 
-### Added
-
-- `.createOption()` to support subclassing of automatically created options (like `.createCommand()`) ([#1380])
-- `.configureOutput()` to modify use of stdout and stderr or customise display of errors ([#1387])
-
-### Breaking changes relative to 7.0.0-0
-
-- rework new `Help.wrap()` for simpler usage pattern (#1395)
-- rename new "columns" properties (#1396)
-  - `Help.columns` -> `helpWidth`
-  - `getOutColumns()` -> `getOutHelpWidth()`
-  - `getErrColumns()` -> `getErrHelpWidth()`
+(Released in 7.0.0)
 
 ## [7.0.0-0] (2020-10-25)
 
-### Added
-
-- use `.addHelpText()` to add text before or after the built-in help, for just current command or also for all subcommands ([#1296])
-- enhance Option class ([#1331])
-  - allow hiding options from help
-  - allow restricting option arguments to a list of choices
-  - allow setting how default value is shown in help
-- refactor the code generating the help into a separate public Help class ([#1365])
-  - support sorting subcommands and options in help
-  - support specifying wrap width (columns)
-  - allow subclassing Help class
-  - allow configuring Help class without subclassing
- 
-### Fixed
-
-- wrapping bugs in help ([#1365])
-  - first line of command description was wrapping two characters early
-  - pad width calculation was not including help option and help command
-  - pad width calculation was including hidden options and commands
-  
-### Changed
+(Released in 7.0.0)
 
-- document and annotate deprecated routines ([#1349])
-- deprecated callback parameter to `.help()` and `.outputHelp()` (removed from README) ([#1296])
-- deprecate `.on('--help')` (removed from README) ([#1296])
-- initialise the command description to empty string (previously undefined) ([#1365])
 ## [6.2.1] (2020-12-13)
 
 ### Fixed
@@ -404,9 +373,13 @@ to expand `-fb` to `-f -b` rather than `-f b`.
 [#1380]: https://github.com/tj/commander.js/pull/1380
 [#1387]: https://github.com/tj/commander.js/pull/1387
 [#1390]: https://github.com/tj/commander.js/pull/1390
+[#1403]: https://github.com/tj/commander.js/pull/1403
+[#1409]: https://github.com/tj/commander.js/pull/1409
+[#1427]: https://github.com/tj/commander.js/pull/1427
 
 [Unreleased]: https://github.com/tj/commander.js/compare/master...develop
-[7.0.0-1]: https://github.com/tj/commander.js/compare/v7.0.0-1...v7.0.0-2
+[7.0.0]: https://github.com/tj/commander.js/compare/v6.2.1...v7.0.0
+[7.0.0-2]: https://github.com/tj/commander.js/compare/v7.0.0-1...v7.0.0-2
 [7.0.0-1]: https://github.com/tj/commander.js/compare/v7.0.0-0...v7.0.0-1
 [7.0.0-0]: https://github.com/tj/commander.js/compare/v6.2.0...v7.0.0-0
 [6.2.1]: https://github.com/tj/commander.js/compare/v6.2.0..v6.2.1

package/Readme.md

@@ -35,6 +35,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
   - [Custom event listeners](#custom-event-listeners)
   - [Bits and pieces](#bits-and-pieces)
     - [.parse() and .parseAsync()](#parse-and-parseasync)
+    - [Parsing Configuration](#parsing-configuration)
     - [Legacy options as properties](#legacy-options-as-properties)
     - [TypeScript](#typescript)
     - [createCommand()](#createcommand)
@@ -84,7 +85,7 @@ For example `-a -b -p 80` may be written as `-ab -p80` or even `-abp80`.
 
 You can use `--` to indicate the end of the options, and any remaining arguments will be used without being interpreted.
 
-Options on the command line are not positional, and can be specified before or after other arguments.
+By default options on the command line are not positional, and can be specified before or after other arguments.
 
 ### Common option types, boolean and value
 
@@ -482,7 +483,8 @@ async function main() {
 }
 ```
 
-A command's options and arguments on the command line are validated when the command is used. Any unknown options or unexpected command-arguments will be reported as an error, or you can suppress these checks with `.allowUnknownOption()` and `.allowExcessArguments()`.
+A command's options and arguments on the command line are validated when the command is used. Any unknown options or missing arguments will be reported as an error. You can suppress the unknown option checks with `.allowUnknownOption()`. By default it is not an error to
+pass more arguments than declared, but you can make this an error with `.allowExcessArguments(false)`.
 
 ### Stand-alone executable (sub)commands
 
@@ -684,6 +686,41 @@ program.parse(); // Implicit, and auto-detect electron
 program.parse(['-f', 'filename'], { from: 'user' });
 ```
 
+### Parsing Configuration
+
+If the default parsing does not suit your needs, there are some behaviours to support other usage patterns.
+
+By default program options are recognised before and after subcommands. To only look for program options before subcommands, use `.enablePositionalOptions()`. This lets you use
+an option for a different purpose in subcommands.
+
+Example file: [positional-options.js](./examples/positional-options.js)
+
+With positional options, the `-b` is a program option in the first line and a subcommand option in the second:
+
+```sh
+program -b subcommand
+program subcommand -b
+```
+
+By default options are recognised before and after command-arguments. To only process options that come
+before the command-arguments, use `.passThroughOptions()`. This lets you pass the  arguments and following options through to another program
+without needing to use `--` to end the option processing. 
+To use pass through options in a subcommand, the program needs to enable positional options.
+
+Example file: [pass-through-options.js](./examples/pass-through-options.js)
+
+With pass through options, the `--port=80` is a program option in the line and passed through as a command-argument in the second:
+
+```sh
+program --port=80 arg
+program arg --port=80
+```
+
+By default the option processing shows an error for an unknown option. To have an unknown option treated as an ordinary command-argument and continue looking for options, use `.allowUnknownOption()`. This lets you mix known and unknown options.
+
+By default the argument processing does not display an error for more command-arguments than expected.
+To display an error for excess arguments, use`.allowExcessArguments(false)`.
+
 ### Legacy options as properties 
 
 Before Commander 7, the option values were stored as properties on the command.
@@ -722,7 +759,7 @@ const program = createCommand();
 
 `createCommand` is also a method of the Command object, and creates a new command rather than a subcommand. This gets used internally
 when creating subcommands using `.command()`, and you may override it to
-customise the new subcommand (examples using [subclass](./examples/custom-command-class.js) and [function](./examples/custom-command-function.js)).
+customise the new subcommand (example file [custom-command-class.js](./examples/custom-command-class.js)).
 
 ### Import into ECMAScript Module
 
@@ -865,8 +902,8 @@ More samples can be found in the [examples](https://github.com/tj/commander.js/t
 
 ## Support
 
-The current version of Commander is fully supported on Long Term Support versions of Node, and is likely to work with Node 6 but not tested.
-(For versions of Node below Node 6, use Commander 3.x or 2.x.)
+The current version of Commander is fully supported on Long Term Support versions of node, and requires at least node v10.
+(For older versions of node, use an older version of Commander. Commander version 2.x has the widest support.)
 
 The main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.
 

package/index.js

@@ -3,7 +3,7 @@
  */
 
 const EventEmitter = require('events').EventEmitter;
-const spawn = require('child_process').spawn;
+const childProcess = require('child_process');
 const path = require('path');
 const fs = require('fs');
 
@@ -311,22 +311,22 @@ class Help {
 
   /**
    * Wrap the given string to width characters per line, with lines after the first indented.
-   * Do not wrap if insufficient room for wrapping, or string is manually formatted.
+   * 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) {
+  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;
-    const minColumnWidth = 40;
     if (columnWidth < minColumnWidth) return str;
 
     const leadingStr = str.substr(0, indent);
@@ -535,7 +535,7 @@ class Command extends EventEmitter {
     this.options = [];
     this.parent = null;
     this._allowUnknownOption = false;
-    this._allowExcessArguments = false;
+    this._allowExcessArguments = true;
     this._args = [];
     this.rawArgs = null;
     this._scriptPath = null;
@@ -552,6 +552,8 @@ class Command extends EventEmitter {
     this._combineFlagAndOptionalValue = true;
     this._description = '';
     this._argsDescription = undefined;
+    this._enablePositionalOptions = false;
+    this._passThroughOptions = false;
 
     // see .configureOutput() for docs
     this._outputConfiguration = {
@@ -633,6 +635,8 @@ class Command extends EventEmitter {
     cmd._exitCallback = this._exitCallback;
     cmd._storeOptionsAsProperties = this._storeOptionsAsProperties;
     cmd._combineFlagAndOptionalValue = this._combineFlagAndOptionalValue;
+    cmd._allowExcessArguments = this._allowExcessArguments;
+    cmd._enablePositionalOptions = this._enablePositionalOptions;
 
     cmd._executableFile = opts.executableFile || null; // Custom name for executable file, set missing to null to match constructor
     this.commands.push(cmd);
@@ -1123,7 +1127,7 @@ class Command extends EventEmitter {
   };
 
   /**
-   * Allow excess arguments on the command line.
+   * 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.
@@ -1133,6 +1137,35 @@ class Command extends EventEmitter {
     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 enablePositionOptions 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().
@@ -1335,15 +1368,15 @@ class Command extends EventEmitter {
         // add executable arguments to spawn
         args = incrementNodeInspectorPort(process.execArgv).concat(args);
 
-        proc = spawn(process.argv[0], args, { stdio: 'inherit' });
+        proc = childProcess.spawn(process.argv[0], args, { stdio: 'inherit' });
       } else {
-        proc = spawn(bin, args, { stdio: 'inherit' });
+        proc = childProcess.spawn(bin, args, { stdio: 'inherit' });
       }
     } else {
       args.unshift(bin);
       // add executable arguments to spawn
       args = incrementNodeInspectorPort(process.execArgv).concat(args);
-      proc = spawn(process.execPath, args, { stdio: 'inherit' });
+      proc = childProcess.spawn(process.execPath, args, { stdio: 'inherit' });
     }
 
     const signals = ['SIGUSR1', 'SIGUSR2', 'SIGTERM', 'SIGINT', 'SIGHUP'];
@@ -1609,11 +1642,38 @@ class Command extends EventEmitter {
         }
       }
 
-      // looks like an option but unknown, unknowns from here
-      if (arg.length > 1 && arg[0] === '-') {
+      // 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);
     }
@@ -1665,20 +1725,14 @@ class Command extends EventEmitter {
   };
 
   /**
-   * `Option` is missing an argument, but received `flag` or nothing.
+   * `Option` is missing an argument.
    *
    * @param {Option} option
-   * @param {string} [flag]
    * @api private
    */
 
-  optionMissingArgument(option, flag) {
-    let message;
-    if (flag) {
-      message = `error: option '${option.flags}' argument missing, got '${flag}'`;
-    } else {
-      message = `error: option '${option.flags}' argument missing`;
-    }
+  optionMissingArgument(option) {
+    const message = `error: option '${option.flags}' argument missing`;
     this._displayError(1, 'commander.optionMissingArgument', message);
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "7.0.0-2",
+  "version": "7.0.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -33,17 +33,13 @@
   ],
   "dependencies": {},
   "devDependencies": {
-    "@types/jest": "^26.0.16",
-    "@types/node": "^14.14.10",
-    "@typescript-eslint/eslint-plugin": "^4.9.0",
-    "eslint": "^7.15.0",
+    "@types/jest": "^26.0.20",
+    "@types/node": "^14.14.20",
+    "@typescript-eslint/eslint-plugin": "^4.12.0",
+    "@typescript-eslint/parser": "^4.12.0",
+    "eslint": "^7.17.0",
     "eslint-config-standard": "^16.0.2",
-    "eslint-config-standard-with-typescript": "^19.0.1",
-    "eslint-plugin-import": "^2.22.1",
     "eslint-plugin-jest": "^24.1.3",
-    "eslint-plugin-node": "^11.1.0",
-    "eslint-plugin-promise": "^4.2.1",
-    "eslint-plugin-standard": "^4.1.0",
     "jest": "^26.6.3",
     "standard": "^16.0.3",
     "typescript": "^4.1.2"

package/typings/index.d.ts

@@ -3,6 +3,7 @@
 
 // Using method rather than property for method-signature-style, to document method overloads separately. Allow either.
 /* eslint-disable @typescript-eslint/method-signature-style */
+/* eslint-disable @typescript-eslint/no-explicit-any */
 
 declare namespace commander {
 
@@ -14,6 +15,7 @@ declare namespace commander {
   }
   type CommanderErrorConstructor = new (exitCode: number, code: string, message: string) => CommanderError;
 
+  // eslint-disable-next-line @typescript-eslint/no-empty-interface
   interface InvalidOptionArgumentError extends CommanderError {
   }
   type InvalidOptionArgumentErrorConstructor = new (message: string) => InvalidOptionArgumentError;
@@ -117,9 +119,9 @@ declare namespace commander {
 
     /**
      * Wrap the given string to width characters per line, with lines after the first indented.
-     * Do not wrap if insufficient room for wrapping, or string is manually formatted.
+     * Do not wrap if insufficient room for wrapping (minColumnWidth), or string is manually formatted.
      */
-    wrap(str: string, width: number, indent: number): string;
+    wrap(str: string, width: number, indent: number, minColumnWidth?: number): string;
 
     /** Generate the built-in help text. */
     formatHelp(cmd: Command, helper: Help): string;
@@ -148,6 +150,10 @@ declare namespace commander {
 
   type AddHelpTextPosition = 'beforeAll' | 'before' | 'after' | 'afterAll';
 
+  interface OptionValues {
+    [key: string]: any;
+  }
+
   interface Command {
     args: string[];
 
@@ -372,6 +378,8 @@ declare namespace commander {
      *
      * @returns `this` command for chaining
      */
+    storeOptionsAsProperties(): this & OptionValues;
+    storeOptionsAsProperties(storeAsProperties: true): this & OptionValues;
     storeOptionsAsProperties(storeAsProperties?: boolean): this;
 
     /**
@@ -394,12 +402,33 @@ declare namespace commander {
     allowUnknownOption(allowUnknown?: boolean): this;
 
     /**
-     * Allow excess arguments on the command line.
+     * Allow excess command-arguments on the command line. Pass false to make excess arguments an error.
      *
      * @returns `this` command for chaining
      */
     allowExcessArguments(allowExcess?: boolean): 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.
+     *
+     * @returns `this` command for chaining
+     */
+    enablePositionalOptions(positional?: boolean): 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.
+     *
+     * @returns `this` command for chaining
+     */
+    passThroughOptions(passThrough?: boolean): this;
+
     /**
      * Parse `argv`, setting options and invoking commands when defined.
      *
@@ -450,7 +479,7 @@ declare namespace commander {
     /**
      * Return an object containing options as key-value pairs
      */
-    opts(): { [key: string]: any };
+    opts(): OptionValues;
 
     /**
      * Set the description.