Merge pull request #1142 from tj/develop

Release 4.1
tj · Jan 6, 2020 · 8e1cdf5 · 8e1cdf5
2 parents b25cc3a + 1c66935
commit 8e1cdf5
Show file tree

Hide file tree

Showing 21 changed files with 1,083 additions and 407 deletions.
diff --git a/.eslintignore b/.eslintignore
@@ -0,0 +1,2 @@
+# We have not configured eslint for TypeScript so avoid bogus error messages in the test file and typings file.
+**/*.ts
diff --git a/.eslintrc.json b/.eslintrc.json
@@ -4,6 +4,7 @@
   "rules": {
     "one-var": "off",
     "semi": ["error", "always"],
-    "space-before-function-paren": ["error", "never"]
+    "space-before-function-paren": ["error", "never"],
+    "no-else-return": ["error", { "allowElseIf": false }]
   }
 }
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,11 +7,32 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 <!-- markdownlint-disable MD024 -->
 
+## [4.1.0] (2020-01-06)
+
+### Added
+
+- two routines to change how option values are handled, and eliminate name clashes with command properties ([#933] [#1102])
+  - see storeOptionsAsProperties and passCommandToAction in README
+- `.parseAsync` to use instead of `.parse` if supply async action handlers ([#806] [#1118])
+
+### Fixed
+
+- Remove trailing blanks from wrapped help text ([#1096])
+
+### Changed
+
+- update dependencies
+- extend security coverage for Commander 2.x to 2020-02-03
+- improvements to README
+- improvements to TypeScript definition documentation
+- move old versions out of main CHANGELOG
+- removed explicit use of `ts-node` in tests
+
 ## [4.0.1] (2019-11-12)
 
 ### Fixed
 
-* display help when requested, even if there are missing required options [(#1091)]
+* display help when requested, even if there are missing required options ([#1091])
 
 ## [4.0.0] (2019-11-02)
 
@@ -355,152 +376,16 @@ program
 
 * remove input methods (.prompt, .confirm, etc)
 
-## 1.3.2 / 2013-07-18
-
-* add support for sub-commands to co-exist with the original command
-
-## 1.3.1 / 2013-07-18
-
-* add quick .runningCommand hack so you can opt-out of other logic when running a sub command
-
-## 1.3.0 / 2013-07-09
-
-* add EACCES error handling
-* fix sub-command --help
-
-## 1.2.0 / 2013-06-13
-
-* allow "-" hyphen as an option argument
-* support for RegExp coercion
-
-## 1.1.1 / 2012-11-20
-
-* add more sub-command padding
-* fix .usage() when args are present. Closes #106
-
-## 1.1.0 / 2012-11-16
-
-* add git-style executable subcommand support. Closes #94
-
-## 1.0.5 / 2012-10-09
-
-* fix `--name` clobbering. Closes #92
-* fix examples/help. Closes #89
-
-## 1.0.4 / 2012-09-03
-
-* add `outputHelp()` method.
-
-## 1.0.3 / 2012-08-30
-
-* remove invalid .version() defaulting
-
-## 1.0.2 / 2012-08-24
-
-* add `--foo=bar` support [arv]
-* fix password on node 0.8.8. Make backward compatible with 0.6 [focusaurus]
-
-## 1.0.1 / 2012-08-03
-
-* fix issue #56
-* fix tty.setRawMode(mode) was moved to tty.ReadStream#setRawMode() (i.e. process.stdin.setRawMode())
-
-## 1.0.0 / 2012-07-05
-
-* add support for optional option descriptions
-* add defaulting of `.version()` to package.json's version
-
-## 0.6.1 / 2012-06-01
-
-* Added: append (yes or no) on confirmation
-* Added: allow node.js v0.7.x
-
-## 0.6.0 / 2012-04-10
-
-* Added `.prompt(obj, callback)` support. Closes #49
-* Added default support to .choose(). Closes #41
-* Fixed the choice example
-
-## 0.5.1 / 2011-12-20
-
-* Fixed `password()` for recent nodes. Closes #36
-
-## 0.5.0 / 2011-12-04
-
-* Added sub-command option support [itay]
-
-## 0.4.3 / 2011-12-04
-
-* Fixed custom help ordering. Closes #32
-
-## 0.4.2 / 2011-11-24
-
-* Added travis support
-* Fixed: line-buffered input automatically trimmed. Closes #31
-
-## 0.4.1 / 2011-11-18
-
-* Removed listening for "close" on --help
-
-## 0.4.0 / 2011-11-15
-
-* Added support for `--`. Closes #24
-
-## 0.3.3 / 2011-11-14
-
-* Fixed: wait for close event when writing help info [Jerry Hamlet]
-
-## 0.3.2 / 2011-11-01
-
-* Fixed long flag definitions with values [felixge]
-
-## 0.3.1 / 2011-10-31
-
-* Changed `--version` short flag to `-V` from `-v`
-* Changed `.version()` so it's configurable [felixge]
-
-## 0.3.0 / 2011-10-31
-
-* Added support for long flags only. Closes #18
-
-## 0.2.1 / 2011-10-24
-
-* "node": ">= 0.4.x < 0.7.0". Closes #20
-
-## 0.2.0 / 2011-09-26
-
-* Allow for defaults that are not just boolean. Default peassignment only occurs for --no-*, optional, and required arguments. [Jim Isaacs]
-
-## 0.1.0 / 2011-08-24
-
-* Added support for custom `--help` output
-
-## 0.0.5 / 2011-08-18
-
-* Changed: when the user enters nothing prompt for password again
-* Fixed issue with passwords beginning with numbers [NuckChorris]
-
-## 0.0.4 / 2011-08-15
-
-* Fixed `Commander#args`
-
-## 0.0.3 / 2011-08-15
-
-* Added default option value support
-
-## 0.0.2 / 2011-08-15
-
-* Added mask support to `Command#password(str[, mask], fn)`
-* Added `Command#password(str, fn)`
-
-## 0.0.1 / 2010-01-03
+## Older versions
 
-* Initial release
+* [1.x](./changelogs/CHANGELOG-1.md)
+* [0.x](./changelogs/CHANGELOG-0.md)
 
 [#599]: https://github.com/tj/commander.js/issues/599
 [#611]: https://github.com/tj/commander.js/issues/611
 [#697]: https://github.com/tj/commander.js/issues/697
 [#795]: https://github.com/tj/commander.js/issues/795
+[#806]: https://github.com/tj/commander.js/issues/806
 [#915]: https://github.com/tj/commander.js/issues/915
 [#938]: https://github.com/tj/commander.js/issues/938
 [#963]: https://github.com/tj/commander.js/issues/963
@@ -509,6 +394,7 @@ program
 [#987]: https://github.com/tj/commander.js/issues/987
 [#990]: https://github.com/tj/commander.js/issues/990
 [#991]: https://github.com/tj/commander.js/issues/991
+[#993]: https://github.com/tj/commander.js/issues/993
 [#999]: https://github.com/tj/commander.js/issues/999
 [#1010]: https://github.com/tj/commander.js/pull/1010
 [#1018]: https://github.com/tj/commander.js/pull/1018
@@ -526,6 +412,9 @@ program
 [#1071]: https://github.com/tj/commander.js/pull/1071
 [#1081]: https://github.com/tj/commander.js/pull/1081
 [#1091]: https://github.com/tj/commander.js/pull/1091
+[#1096]: https://github.com/tj/commander.js/pull/1096
+[#1102]: https://github.com/tj/commander.js/pull/1102
+[#1118]: https://github.com/tj/commander.js/pull/1118
 
 [Unreleased]: https://github.com/tj/commander.js/compare/master...develop
 [4.0.1]: https://github.com/tj/commander.js/compare/v4.0.0..v4.0.1

diff --git a/Readme.md b/Readme.md
@@ -11,7 +11,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
 
 - [Commander.js](#commanderjs)
   - [Installation](#installation)
-  - [Declaring _program_ variable](#declaring-program-variable)
+  - [Declaring program variable](#declaring-program-variable)
   - [Options](#options)
     - [Common option types, boolean and value](#common-option-types-boolean-and-value)
     - [Default option value](#default-option-value)
@@ -31,8 +31,9 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
     - [.help(cb)](#helpcb)
   - [Custom event listeners](#custom-event-listeners)
   - [Bits and pieces](#bits-and-pieces)
+    - [Avoiding option name clashes](#avoiding-option-name-clashes)
     - [TypeScript](#typescript)
-    - [Node options such as `--harmony`](#node-options-such-as---harmony)
+    - [Node options such as --harmony](#node-options-such-as---harmony)
     - [Node debugging](#node-debugging)
     - [Override exit handling](#override-exit-handling)
   - [Examples](#examples)
@@ -70,6 +71,8 @@ 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. Multiple short flags may be combined as a single arg, for example `-abc` is equivalent to `-a -b -c`.
 
+See also optional new behaviour to [avoid name clashes](#avoiding-option-name-clashes).
+
 ### 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.
@@ -374,6 +377,19 @@ program
 program.parse(process.argv)
 ```
 
+You may supply an `async` action handler, in which case you call `.parseAsync` rather than `.parse`.
+
+```js
+async function run() { /* code goes here */ }
+
+async function main() {
+  program
+    .command('run')
+    .action(run);
+  await program.parseAsync(process.argv);
+}
+```
+
 A command's options on the command line are validated when the command is used. Any unknown options will be reported as an error. However, if an action-based command does not define an action, then the options are not validated.
 
 Configuration options can be passed with the call to `.command()`. Specifying `true` for `opts.noHelp` will remove the command from the generated help output.
@@ -550,6 +566,43 @@ program.on('command:*', function () {
 
 ## Bits and pieces
 
+### Avoiding option name clashes
+
+The original and default behaviour is that the option values are stored
+as properties on the program, and the action handler is passed a
+command object with the options values stored as properties.
+This is very convenient to code, but the downside is possible clashes with
+existing properties of Command.
+
+There are two new routines to change the behaviour, and the default behaviour may change in the future:
+
+- `storeOptionsAsProperties`: whether to store option values as properties on command object, or store separately (specify false) and access using `.opts()`
+- `passCommandToAction`: whether to pass command to action handler,
+or just the options (specify false)
+
+```js
+// file: ./examples/storeOptionsAsProperties.action.js
+program
+  .storeOptionsAsProperties(false)
+  .passCommandToAction(false);
+
+program
+  .name('my-program-name')
+  .option('-n,--name <name>');
+
+program
+  .command('show')
+  .option('-a,--action <action>')
+  .action((options) => {
+    console.log(options.action);
+  });
+
+program.parse(process.argv);
+
+const programOptions = program.opts();
+console.log(programOptions.name);
+```
+
 ### TypeScript
 
 The Commander package includes its TypeScript Definition file, but also requires the node types which you need to install yourself. e.g.
@@ -648,7 +701,8 @@ More Demos can be found in the [examples](https://github.com/tj/commander.js/tre
 
 ## Support
 
-Commander is supported on Node 8 and above. (Commander is likely to still work on older versions of Node, but is not tested below Node 8.)
+Commander 4.x is supported on Node 8 and above, 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 main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.