Merge branch 'develop' into release/5.x

With 4.1 release

CHANGELOG.md

@@ -7,12 +7,13 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 <!-- markdownlint-disable MD024 -->
 
-## [4.1.0] (date goes here)
+## [4.1.0] (2020-01-06)
 
 ### Added
 
-- two routines to change how option values are handled, and avoid name clashes with command properties ([#1102])
+- 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
 
@@ -25,6 +26,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - 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)
 
@@ -383,6 +385,7 @@ program
 [#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
@@ -391,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
@@ -410,8 +414,10 @@ program
 [#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.1.0]: https://github.com/tj/commander.js/compare/v4.0.1..v4.1.0
 [4.0.1]: https://github.com/tj/commander.js/compare/v4.0.0..v4.0.1
 [4.0.0]: https://github.com/tj/commander.js/compare/v3.0.2..v4.0.0
 [4.0.0-1]: https://github.com/tj/commander.js/compare/v4.0.0-0..v4.0.0-1

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)
@@ -33,7 +33,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
   - [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)
@@ -377,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.

Readme_zh-CN.md

@@ -33,7 +33,7 @@
   - [零碎知识](#%e9%9b%b6%e7%a2%8e%e7%9f%a5%e8%af%86)
     - [避免选项命名冲突](#避免选项命名冲突)
     - [TypeScript](#typescript)
-    - [Node 选项例如 `--harmony`](#node-%e9%80%89%e9%a1%b9%e4%be%8b%e5%a6%82---harmony)
+    - [Node 选项例如 --harmony](#node-%e9%80%89%e9%a1%b9%e4%be%8b%e5%a6%82---harmony)
     - [Node 调试](#node-%e8%b0%83%e8%af%95)
     - [重载退出(exit)处理](#%e9%87%8d%e8%bd%bd%e9%80%80%e5%87%baexit%e5%a4%84%e7%90%86)
   - [例子](#%e4%be%8b%e5%ad%90)
@@ -372,6 +372,20 @@ program
 program.parse(process.argv)
 ```
 
+你可以自行实现一个`async`操作处理程序，同时调用`.parseAsync`代替`.parse`。
+
+```js
+async function run() { /* 在这里编写代码 */ }
+
+async function main() {
+  program
+    .command('run')
+    .action(run);
+  await program.parseAsync(process.argv);
+}
+```
+
+
 当一个命令在命令行上被使用时，它的选项必须是合法的。使用任何未知的选项会报错。然而如果一个基于操作的命令没有定义任何操作，那么这些选项是不合法的。
 
 定义配置选项可以随着调用 `.command()` 传递。

examples/custom-help

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
-/**
- * Module dependencies.
- */
-
-var program = require('../');
+// const program = require('commander'); // (normal include)
+const program = require('../'); // include commander in git clone of commander repo
 
 program
   .version('0.0.1')

examples/custom-help-description

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
-/**
- * Module dependencies.
- */
-
-var program = require('../');
+// const program = require('commander'); // (normal include)
+const program = require('../'); // include commander in git clone of commander repo
 
 program
   .helpOption('-c, --HELP', 'custom help message')

examples/custom-version

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
-/**
- * Module dependencies.
- */
-
-var program = require('../');
+// const program = require('commander'); // (normal include)
+const program = require('../'); // include commander in git clone of commander repo
 
 program
   .version('0.0.1', '-v, --VERSION', 'new version message')

examples/defaults

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
-/**
- * Module dependencies.
- */
-
-var program = require('../');
+// const program = require('commander'); // (normal include)
+const program = require('../'); // include commander in git clone of commander repo
 
 function list(val) {
   return val.split(',').map(Number);

examples/deploy

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
-/**
- * Module dependencies.
- */
-
-var program = require('../');
+// const program = require('commander'); // (normal include)
+const program = require('../'); // include commander in git clone of commander repo
 
 program
   .version('0.0.1')

examples/description

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
-/**
- * Module dependencies.
- */
-
-var program = require('../');
+// const program = require('commander'); // (normal include)
+const program = require('../'); // include commander in git clone of commander repo
 
 program
   .version('0.0.1')

examples/env

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
-var program = require('../');
+// const program = require('commander'); // (normal include)
+const program = require('../'); // include commander in git clone of commander repo
 
 let cmdValue;
 let envValue;

examples/express

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
-/**
- * Module dependencies.
- */
-
-var program = require('../');
+// const program = require('commander'); // (normal include)
+const program = require('../'); // include commander in git clone of commander repo
 
 program
   .version('0.0.1')

examples/help

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
-/**
- * Module dependencies.
- */
-
-var program = require('../');
+// const program = require('commander'); // (normal include)
+const program = require('../'); // include commander in git clone of commander repo
 
 program
   .version('0.0.1')

examples/options-common.js

@@ -20,7 +20,8 @@
 // pizza details:
 // - cheese
 
-const commander = require('../');
+// const commander = require('commander'); // (normal include)
+const commander = require('../'); // include commander in git clone of commander repo
 const program = new commander.Command();
 
 program

examples/options-custom-processing.js

@@ -17,7 +17,8 @@
 // $ custom --list x,y,z
 // [ 'x', 'y', 'z' ]
 
-const commander = require('../');
+// const commander = require('commander'); // (normal include)
+const commander = require('../'); // include commander in git clone of commander repo
 const program = new commander.Command();
 
 function myParseInt(value, dummyPrevious) {

examples/options-defaults.js

@@ -11,7 +11,8 @@
 // $ pizza-options --cheese stilton
 // cheese: stilton
 
-const commander = require('../');
+// const commander = require('commander'); // (normal include)
+const commander = require('../'); // include commander in git clone of commander repo
 const program = new commander.Command();
 
 program

examples/options-flag-or-value.js

@@ -13,7 +13,8 @@
 // $ pizza-options --cheese mozzarella
 // add cheese type mozzarella
 
-const commander = require('../');
+// const commander = require('commander'); // (normal include)
+const commander = require('../'); // include commander in git clone of commander repo
 const program = new commander.Command();
 
 program

examples/options-negatable.js

@@ -15,7 +15,8 @@
 // $ pizza-options --no-sauce --no-cheese
 // You ordered a pizza with no sauce and no cheese
 
-const commander = require('../');
+// const commander = require('commander'); // (normal include)
+const commander = require('../'); // include commander in git clone of commander repo
 const program = new commander.Command();
 
 program

examples/options-required.js

@@ -10,7 +10,8 @@
 // $ pizza
 // error: required option '-c, --cheese <type>' not specified
 
-const commander = require('..'); // For running direct from git clone of commander repo
+// const commander = require('commander'); // (normal include)
+const commander = require('../'); // include commander in git clone of commander repo
 const program = new commander.Command();
 
 program

examples/pizza

@@ -1,10 +1,7 @@
 #!/usr/bin/env node
 
-/**
- * Module dependencies.
- */
-
-var program = require('../');
+// const program = require('commander'); // (normal include)
+const program = require('../'); // include commander in git clone of commander repo
 
 program
   .version('0.0.1')

examples/pm

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
-var program = require('..');
+// const program = require('commander'); // (normal include)
+const program = require('../'); // include commander in git clone of commander repo
 
 program
   .version('0.0.1')

examples/pm-install

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
-var program = require('..');
+// const program = require('commander'); // (normal include)
+const program = require('../'); // include commander in git clone of commander repo
 
 program
   .option('-f, --force', 'force installation')

examples/storeOptionsAsProperties-action.js

@@ -16,7 +16,8 @@
 // jump
 // foo
 
-const commander = require('../');
+// const commander = require('commander'); // (normal include)
+const commander = require('../'); // include commander in git clone of commander repo
 const program = new commander.Command();
 
 program

examples/storeOptionsAsProperties-opts.js

@@ -14,7 +14,8 @@
 // jump
 // foo
 
-const commander = require('../');
+// const commander = require('commander'); // (normal include)
+const commander = require('../'); // include commander in git clone of commander repo
 const program = new commander.Command();
 
 program

examples/storeOptionsAsProperties-problem.js

@@ -16,7 +16,8 @@
 // jump
 // foo
 
-const commander = require('../');
+// const commander = require('commander'); // (normal include)
+const commander = require('../'); // include commander in git clone of commander repo
 const program = new commander.Command();
 
 program