Merge branch 'develop' into release/9.x

Readme.md

@@ -1019,7 +1019,7 @@ 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.js, and requires at least v12.20.0.
-(For older versions of Node.js, use an older version of Commander. Commander version 2.x has the widest support.)
+(For older versions of Node.js, use an older version of Commander.)
 
 The main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.
 

Readme_zh-CN.md

@@ -22,7 +22,7 @@
     - [其他选项配置](#%E5%85%B6%E4%BB%96%E9%80%89%E9%A1%B9%E9%85%8D%E7%BD%AE)
     - [自定义选项处理](#%E8%87%AA%E5%AE%9A%E4%B9%89%E9%80%89%E9%A1%B9%E5%A4%84%E7%90%86)
   - [命令](#%e5%91%bd%e4%bb%a4)
-    - [命令参数](#%E8%AE%BE%E7%BD%AE%E5%91%BD%E4%BB%A4%E5%8F%82%E6%95%B0)
+    - [命令参数](#%E5%91%BD%E4%BB%A4%E5%8F%82%E6%95%B0)
       - [其他参数配置](#%E5%85%B6%E4%BB%96%E5%8F%82%E6%95%B0%E9%85%8D%E7%BD%AE)
       - [自定义参数处理](#%E8%87%AA%E5%AE%9A%E4%B9%89%E5%8F%82%E6%95%B0%E5%A4%84%E7%90%86)
     - [处理函数](#%E5%A4%84%E7%90%86%E5%87%BD%E6%95%B0)

examples/arguments-extra.js

@@ -17,7 +17,7 @@ program
 program.parse();
 
 // Try the following:
-//  node arguments-extra.js --help
-//  node arguments-extra.js huge
-//  node arguments-extra.js small
-//  node arguments-extra.js medium 30
+//    node arguments-extra.js --help
+//    node arguments-extra.js huge
+//    node arguments-extra.js small
+//    node arguments-extra.js medium 30

examples/configure-help.js

@@ -21,4 +21,4 @@ program
 program.parse();
 
 // Try the following:
-// node configure-help.js --help
+//    node configure-help.js --help

examples/configure-output.js

@@ -25,7 +25,7 @@ program
 program.parse();
 
 // Try the following:
-//  node configure-output.js --version
-//  node configure-output.js --unknown
-//  node configure-output.js --help
-//  node configure-output.js
+//    node configure-output.js --version
+//    node configure-output.js --unknown
+//    node configure-output.js --help
+//    node configure-output.js

examples/custom-help

@@ -18,4 +18,4 @@ Example call:
 program.parse(process.argv);
 
 // Try the following:
-//  node custom-help --help
+//    node custom-help --help

examples/custom-help-description

@@ -21,5 +21,5 @@ program
 program.parse(process.argv);
 
 // Try the following:
-// node custom-help-description -c
-// node custom-help-description child --HELP
+//    node custom-help-description -c
+//    node custom-help-description child --HELP

examples/custom-help-text.js

@@ -28,6 +28,6 @@ Examples:
 program.parse();
 
 // Try the following:
-//  node custom-help-text.js --help
-//  node custom-help-text.js extra --help
-//  node custom-help-text.js
+//    node custom-help-text.js --help
+//    node custom-help-text.js extra --help
+//    node custom-help-text.js

examples/custom-version

@@ -14,5 +14,5 @@ program
 program.parse(process.argv);
 
 // Try the following:
-// node custom-version -v
-// node custom-version --VERSION
+//    node custom-version -v
+//    node custom-version --VERSION

examples/defaultCommand.js

@@ -5,13 +5,6 @@ const commander = require('../'); // include commander in git clone of commander
 const program = new commander.Command();
 
 // Example program using the command configuration option isDefault to specify the default command.
-//
-// $ node defaultCommand.js build
-// build
-// $ node defaultCommand.js serve -p 8080
-// server on port 8080
-// $ node defaultCommand.js -p 443
-// server on port 443
 
 program
   .command('build')
@@ -36,3 +29,8 @@ program
   });
 
 program.parse(process.argv);
+
+// Try the following:
+//    node defaultCommand.js build
+//    node defaultCommand.js serve -p 8080
+//    node defaultCommand.js -p 443

examples/description

@@ -16,3 +16,9 @@ program
 program.parse(process.argv);
 
 if (!program.args.length) program.help();
+
+// Try the following on macOS or Linux:
+//    ./description -h
+//
+// Try the following:
+//    node description -h

examples/hook.js

@@ -48,9 +48,9 @@ program.command('hello')
 program.parseAsync().then(() => {});
 
 // Try the following:
-//  node hook.js hello
-//  node hook.js --profile hello
-//  node hook.js --trace hello --example
-//  node hook.js delay
-//  node hook.js --trace delay 5 --message bye
-//  node hook.js --profile delay
+//    node hook.js hello
+//    node hook.js --profile hello
+//    node hook.js --trace hello --example
+//    node hook.js delay
+//    node hook.js --trace delay 5 --message bye
+//    node hook.js --profile delay

examples/nestedCommands.js

@@ -8,13 +8,6 @@ const program = new commander.Command();
 // .command() can add a subcommand with an action handler or an executable.
 // .addCommand() adds a prepared command with an action handler.
 
-// Example output:
-//
-// $ node nestedCommands.js brew tea
-// brew tea
-// $ node nestedCommands.js heat jug
-// heat jug
-
 // Add nested commands using `.command()`.
 const brew = program.command('brew');
 brew
@@ -47,3 +40,7 @@ function makeHeatCommand() {
 program.addCommand(makeHeatCommand());
 
 program.parse(process.argv);
+
+// Try the following:
+//    node nestedCommands.js brew tea
+//    node nestedCommands.js heat jug

examples/options-env.js

@@ -22,17 +22,17 @@ program.parse();
 console.log(program.opts());
 
 // Try the following:
-// node options-env.js --help
+//    node options-env.js --help
 //
-// node options-env.js
-// PORT=9001 node options-env.js
-// PORT=9001 node options-env.js --port 123
+//    node options-env.js
+//    PORT=9001 node options-env.js
+//    PORT=9001 node options-env.js --port 123
 //
-// COLOUR= node options-env.js
-// COLOUR= node options-env.js --no-colour
-// NO_COLOUR= node options-env.js
-// NO_COLOUR= node options-env.js --colour
+//    COLOUR= node options-env.js
+//    COLOUR= node options-env.js --no-colour
+//    NO_COLOUR= node options-env.js
+//    NO_COLOUR= node options-env.js --colour
 //
-// SIZE=small node options-env.js
-// SIZE=enormous node options-env.js
-// SIZE=enormous node options-env.js --size=large
+//    SIZE=small node options-env.js
+//    SIZE=enormous node options-env.js
+//    SIZE=enormous node options-env.js --size=large

examples/options-extra.js

@@ -18,6 +18,6 @@ program.parse();
 console.log('Options: ', program.opts());
 
 // Try the following:
-// node options-extra.js --help
-// node options-extra.js --drink huge
-// PORT=80 node options-extra.js
+//    node options-extra.js --help
+//    node options-extra.js --drink huge
+//    PORT=80 node options-extra.js

examples/options-required.js

@@ -4,11 +4,6 @@
 //    Required option
 //    You may specify a required (mandatory) option using `.requiredOption`.
 //    The option must be specified on the command line, or by having a default value.
-//
-// Example output pretending command called pizza (or try directly with `node options-required.js`)
-//
-// $ pizza
-// error: required option '-c, --cheese <type>' not specified
 
 // const commander = require('commander'); // (normal include)
 const commander = require('../'); // include commander in git clone of commander repo
@@ -18,3 +13,9 @@ program
   .requiredOption('-c, --cheese <type>', 'pizza must have cheese');
 
 program.parse();
+
+console.log(`Cheese type: ${program.opts().cheese}`);
+
+// Try the following:
+//    node options-required.js
+//    node options-required.js --cheese blue

examples/options-variadic.js

@@ -16,6 +16,6 @@ console.log('Options: ', program.opts());
 console.log('Remaining arguments: ', program.args);
 
 // Try the following:
-//  node options-variadic.js -n 1 2 3 --letter a b c
-//  node options-variadic.js --letter=A -n80 operand
-//  node options-variadic.js --letter -n 1 -n 2 3 -- operand
+//    node options-variadic.js -n 1 2 3 --letter a b c
+//    node options-variadic.js --letter=A -n80 operand
+//    node options-variadic.js --letter -n 1 -n 2 3 -- operand

examples/pass-through-options.js

@@ -17,7 +17,6 @@ program
 program.parse();
 
 // Try the following:
-//
 //    node pass-through-options.js git status
 //    node pass-through-options.js git --version
 //    node pass-through-options.js --dry-run git checkout -b new-branch

examples/pizza

@@ -17,3 +17,11 @@ console.log('you ordered a pizza with:');
 if (options.peppers) console.log('  - peppers');
 const cheese = !options.cheese ? 'no' : options.cheese;
 console.log('  - %s cheese', cheese);
+
+// Try the following on macOS or Linux:
+//    ./pizza --help    
+//
+// Try the following:
+//    ./pizza --help    
+//    node pizza --peppers --cheese=blue
+//    node pizza --no-cheese

examples/pm

@@ -4,6 +4,13 @@
 const { Command } = require('../'); // include commander in git clone of commander repo
 const program = new Command();
 
+// Example of subcommands which are implemented as stand-alone executable files.
+//
+// When `.command()` is invoked with a description argument,
+// this tells Commander that you're going to use a stand-alone executable for the subcommand.
+//
+// Only `install` and `list` are implemented, see pm-install and pm-list.js
+
 program
   .name('pm')
   .version('0.0.1')
@@ -15,18 +22,12 @@ program
 
 program.parse(process.argv);
 
-// here .command() is invoked with a description,
-// and no .action(callback) calls to handle sub-commands.
-// this tells commander that you're going to use separate
-// executables for sub-commands, much like git(1) and other
-// popular tools.
-
-// here only ./pm-install(1) and ./pm-list(1) are implemented, however you
-// would define ./pm-search(1) etc.
-
+// Try the following on macOS or Linux:
+//    ./examples/pm
+//
 // Try the following:
-//   ./examples/pm
-//   ./examples/pm help install
-//   ./examples/pm install -h
-//   ./examples/pm install foo bar baz
-//   ./examples/pm install foo bar baz --force
+//    node pm
+//    node pm help install
+//    node pm install -h
+//    node pm install foo bar baz
+//    node pm install foo bar baz --force

examples/positional-options.js

@@ -20,7 +20,6 @@ program
 program.parse();
 
 // Try the following:
-//
 //    node positional-options.js upload test.js
 //    node positional-options.js -p upload test.js
 //    node positional-options.js upload -p 8080 test.js

examples/thank.js

@@ -21,6 +21,6 @@ program
 program.parse();
 
 // Try the following:
-//   node thank.js John
-//   node thank.js Doe --title Mr
-//   node thank.js --debug Doe --title Mr
+//    node thank.js John
+//    node thank.js Doe --title Mr
+//    node thank.js --debug Doe --title Mr

lib/argument.js

@@ -90,7 +90,7 @@ class Argument {
   };
 
   /**
-   * Only allow option value to be one of choices.
+   * Only allow argument value to be one of choices.
    *
    * @param {string[]} values
    * @return {Argument}
@@ -111,15 +111,15 @@ class Argument {
   };
 
   /**
-   * Make option-argument required.
+   * Make argument required.
    */
   argRequired() {
     this.required = true;
     return this;
   }
 
   /**
-   * Make option-argument optional.
+   * Make argument optional.
    */
   argOptional() {
     this.required = false;

lib/command.js

@@ -1230,7 +1230,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
       let actionResult;
       actionResult = this._chainOrCallHooks(actionResult, 'preAction');
       actionResult = this._chainOrCall(actionResult, () => this._actionHandler(this.processedArgs));
-      if (this.parent) this.parent.emit(commandEvent, operands, unknown); // legacy
+      if (this.parent) {
+        actionResult = this._chainOrCall(actionResult, () => {
+          this.parent.emit(commandEvent, operands, unknown); // legacy
+        });
+      }
       actionResult = this._chainOrCallHooks(actionResult, 'postAction');
       return actionResult;
     }

typings/index.d.ts

@@ -64,12 +64,12 @@ export class Argument {
   choices(values: string[]): this;
 
   /**
-   * Make option-argument required.
+   * Make argument required.
    */
   argRequired(): this;
 
   /**
-   * Make option-argument optional.
+   * Make argument optional.
    */
   argOptional(): this;
   }