commander 6.1.0 → 6.2.0

package/CHANGELOG.md

@@ -8,6 +8,24 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 <!-- markdownlint-disable MD024 -->
 <!-- markdownlint-disable MD004 -->
 
+## [6.2.0] (2020-10-25)
+
+### Added
+
+- added 'tsx' file extension for stand-alone executable subcommands ([#1368])
+- documented second parameter to `.description()` to describe command arguments ([#1353])
+- documentation of special cases with options taking varying numbers of option-arguments ([#1332])
+- documentation for terminology ([#1361])
+  
+### Fixed
+
+- add missing TypeScript definition for `.addHelpCommand()' ([#1375])
+- removed blank line after "Arguments:" in help, to match "Options:" and "Commands:" ([#1360])
+
+### Changed
+
+- update dependencies
+
 ## [6.1.0] (2020-08-28)
 
 ### Added
@@ -308,8 +326,16 @@ if (program.rawArgs.length < 3) ...
 [#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
+[#1332]: https://github.com/tj/commander.js/pull/1332
+[#1353]: https://github.com/tj/commander.js/pull/1353
+[#1360]: https://github.com/tj/commander.js/pull/1360
+[#1361]: https://github.com/tj/commander.js/pull/1361
+[#1368]: https://github.com/tj/commander.js/pull/1368
+[#1375]: https://github.com/tj/commander.js/pull/1375
+
 
 [Unreleased]: https://github.com/tj/commander.js/compare/master...develop
+[6.2.0]: https://github.com/tj/commander.js/compare/v6.1.0..v6.2.0
 [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

package/Readme.md

@@ -5,7 +5,7 @@
 [![NPM Downloads](https://img.shields.io/npm/dm/commander.svg?style=flat)](https://npmcharts.com/compare/commander?minimal=true)
 [![Install Size](https://packagephobia.now.sh/badge?p=commander)](https://packagephobia.now.sh/result?p=commander)
 
-The complete solution for [node.js](http://nodejs.org) command-line interfaces, inspired by Ruby's [commander](https://github.com/commander-rb/commander).
+The complete solution for [node.js](http://nodejs.org) command-line interfaces.
 
 Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
 
@@ -15,7 +15,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
   - [Options](#options)
     - [Common option types, boolean and value](#common-option-types-boolean-and-value)
     - [Default option value](#default-option-value)
-    - [Other option types, negatable boolean and flag|value](#other-option-types-negatable-boolean-and-flagvalue)
+    - [Other option types, negatable boolean and boolean|value](#other-option-types-negatable-boolean-and-booleanvalue)
     - [Custom option processing](#custom-option-processing)
     - [Required option](#required-option)
     - [Variadic option](#variadic-option)
@@ -46,6 +46,8 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
   - [Support](#support)
     - [Commander for enterprise](#commander-for-enterprise)
 
+For information about terms used in this document see: [terminology](./docs/terminology.md)
+
 ## Installation
 
 ```bash
@@ -76,18 +78,17 @@ Options are defined with the `.option()` method, also serving as documentation f
 
 The options can be accessed as properties on the Command object. Multi-word options such as "--template-engine" are camel-cased, becoming `program.templateEngine` etc. See also optional new behaviour to [avoid name clashes](#avoiding-option-name-clashes).
 
-Multiple short flags may optionally be combined in a single argument following the dash: boolean flags, the last flag may take a value, and the value.
+Multiple short flags may optionally be combined in a single argument following the dash: boolean flags, followed by a single option taking a value (possibly followed by the value).
 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.
-This is particularly useful for passing options through to another
-command, like: `do -- git --version`.
 
-Options on the command line are not positional, and can be specified before or after other command arguments.
+Options on the command line are not positional, and can be specified before or after other arguments.
 
 ### Common option types, boolean and value
 
-The two most used option types are a boolean flag, and an option which takes a value (declared using angle brackets). Both are `undefined` unless specified on command line.
+The two most used option types are a boolean option, and an option which takes its value
+from the following argument (declared with angle brackets like `--expect <value>`). Both are `undefined` unless specified on command line.  
 
 Example file: [options-common.js](./examples/options-common.js)
 
@@ -145,13 +146,13 @@ $ pizza-options --cheese stilton
 cheese: stilton
 ```
 
-### Other option types, negatable boolean and flag|value
+### Other option types, negatable boolean and boolean|value
 
-You can specify a boolean option long name with a leading `no-` to set the option value to false when used.
+You can define a boolean option long name with a leading `no-` to set the option value to false when used.
 Defined alone this also makes the option true by default.
 
 If you define `--foo` first, adding `--no-foo` does not change the default value from what it would
-otherwise be. You can specify a default boolean value for a boolean flag and it can be overridden on command line.
+otherwise be. You can specify a default boolean value for a boolean option and it can be overridden on command line.
 
 Example file: [options-negatable.js](./examples/options-negatable.js)
 
@@ -178,9 +179,10 @@ $ pizza-options --no-sauce --no-cheese
 You ordered a pizza with no sauce and no cheese
 ```
 
-You can specify an option which functions as a flag but may also take a value (declared using square brackets).
+You can specify an option which may be used as a boolean option but may optionally take an option-argument
+(declared with square brackets like `--optional [value]`).
 
-Example file: [options-flag-or-value.js](./examples/options-flag-or-value.js)
+Example file: [options-boolean-or-value.js](./examples/options-boolean-or-value.js)
 
 ```js
 program
@@ -202,14 +204,16 @@ $ pizza-options --cheese mozzarella
 add cheese type mozzarella
 ```
 
+For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).
+
 ### Custom option processing
 
-You may specify a function to do custom processing of option values. The callback function receives two parameters, the user specified value and the
-previous value for the option. It returns the new value for the option.
+You may specify a function to do custom processing of option-arguments. The callback function receives two parameters,
+the user specified option-argument and the previous value for the option. It returns the new value for the option.
 
-This allows you to coerce the option value to the desired type, or accumulate values, or do entirely custom processing.
+This allows you to coerce the option-argument to the desired type, or accumulate values, or do entirely custom processing.
 
-You can optionally specify the default/starting value for the option after the function.
+You can optionally specify the default/starting value for the option after the function parameter.
 
 Example file: [options-custom-processing.js](./examples/options-custom-processing.js)
 
@@ -282,7 +286,7 @@ error: required option '-c, --cheese <type>' not specified
 ### Variadic option
 
 You may make an option variadic by appending `...` to the value placeholder when declaring the option. On the command line you
-can then specify multiple option arguments, and the parsed option value will be an array. The extra arguments
+can then specify multiple option-arguments, and the parsed option value will be an array. The extra arguments
 are read until the first argument starting with a dash. The special argument `--` stops option processing entirely. If a value
 is specified in the same argument as the option then no further values are read.
 
@@ -311,6 +315,8 @@ Options:  { number: [ '1', '2', '3' ], letter: true }
 Remaining arguments:  [ 'operand' ]
 ```
 
+For information about possible ambiguous cases, see [options taking varying arguments](./docs/options-taking-varying-arguments.md).
+
 ### Version option
 
 The optional `version` method adds handling for displaying the command version. The default option flags are `-V` and `--version`, and when present the command prints the version number and exits.
@@ -335,7 +341,7 @@ program.version('0.0.1', '-v, --vers', 'output the current version');
 
 You can specify (sub)commands using `.command()` or `.addCommand()`. There are two ways these can be implemented: using an action handler attached to the command, or as a stand-alone executable file (described in more detail later). The subcommands may be nested ([example](./examples/nestedCommands.js)).
 
-In the first parameter to `.command()` you specify the command name and any command arguments. The arguments may be `<required>` or `[optional]`, and the last argument may also be `variadic...`.
+In the first parameter to `.command()` you specify the command name and any command-arguments. The arguments may be `<required>` or `[optional]`, and the last argument may also be `variadic...`.
 
 You can use `.addCommand()` to add an already configured subcommand to the program.
 
@@ -363,11 +369,16 @@ program
   .addCommand(build.makeBuildCommand());
 ```
 
-Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `true` for `opts.hidden` will remove the command from the generated help output. Specifying `true` for `opts.isDefault` will run the subcommand if no other subcommand is specified ([example](./examples/defaultCommand.js)).
+Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will 
+remove the command from the generated help output. Specifying `isDefault: true` will run the subcommand if no other
+subcommand is specified ([example](./examples/defaultCommand.js)).
 
 ### Specify the argument syntax
 
-You use `.arguments` to specify the arguments for the top-level command, and for subcommands they are usually included in the `.command` call. Angled brackets (e.g. `<required>`) indicate required input. Square brackets (e.g. `[optional]`) indicate optional input.
+You use `.arguments` to specify the expected command-arguments for the top-level command, and for subcommands they are usually
+included in the `.command` call. Angled brackets (e.g. `<required>`) indicate required command-arguments.
+Square brackets (e.g. `[optional]`) indicate optional command-arguments.
+You can optionally describe the arguments in the help by supplying a hash as second parameter to `.description()`.
 
 Example file: [env](./examples/env)
 
@@ -375,9 +386,13 @@ Example file: [env](./examples/env)
 program
   .version('0.1.0')
   .arguments('<cmd> [env]')
+  .description('test command', {
+    cmd: 'command to run',
+    env: 'environment to run test in'
+  })
   .action(function (cmd, env) {
-    console.log('command:', cmdValue);
-    console.log('environment:', envValue || 'no environment given');
+    console.log('command:', cmd);
+    console.log('environment:', env || 'no environment given');
   });
 
 program.parse(process.argv);

package/index.js

@@ -838,7 +838,7 @@ Read more on https://git.io/JJc0W`);
   _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', '.mjs'];
+    const sourceExt = ['.js', '.ts', '.tsx', '.mjs'];
 
     // Not checking for help first. Unlikely to have mandatory and executable, and can't robustly test for help flags in external command.
     this._checkForMissingMandatoryOptions();
@@ -1576,7 +1576,6 @@ Read more on https://git.io/JJc0W`);
         const columns = process.stdout.columns || 80;
         const descriptionWidth = columns - width - 5;
         desc.push('Arguments:');
-        desc.push('');
         this._args.forEach((arg) => {
           desc.push('  ' + pad(arg.name, width) + '  ' + wrap(argsDescription[arg.name] || '', descriptionWidth, width + 4));
         });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",
@@ -31,17 +31,20 @@
   ],
   "dependencies": {},
   "devDependencies": {
-    "@types/jest": "^26.0.5",
-    "@types/node": "^14.0.23",
-    "@typescript-eslint/eslint-plugin": "^2.34.0",
-    "eslint": "^6.8.0",
-    "eslint-config-standard-with-typescript": "^16.0.0",
-    "eslint-plugin-jest": "^23.18.0",
-    "jest": "^26.1.0",
-    "standard": "^14.3.4",
-    "typescript": "^3.9.7"
+    "@types/jest": "^26.0.15",
+    "@types/node": "^14.14.2",
+    "@typescript-eslint/eslint-plugin": "^4.5.0",
+    "eslint": "^7.11.0",
+    "eslint-config-standard-with-typescript": "^19.0.1",
+    "eslint-plugin-jest": "^24.1.0",
+    "jest": "^26.6.0",
+    "standard": "^15.0.0",
+    "typescript": "^4.0.3"
   },
   "typings": "typings/index.d.ts",
+  "jest": {
+    "collectCoverage": true
+  },
   "engines": {
     "node": ">= 6"
   }

package/typings/index.d.ts

@@ -109,6 +109,17 @@ declare namespace commander {
      */
     arguments(desc: string): 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
+     *
+     * @returns `this` command for chaining
+     */
+    addHelpCommand(enableOrNameAndArgs?: string | boolean, description?: string): this;
+
     /**
      * Register callback to use as replacement for calling process.exit.
      */
@@ -394,6 +405,6 @@ declare namespace commander {
 }
 
 // Declaring namespace AND global
-// eslint-disable-next-line no-redeclare
+// eslint-disable-next-line @typescript-eslint/no-redeclare
 declare const commander: commander.CommanderStatic;
 export = commander;