commander 12.0.0-1 → 12.1.0

package/Readme.md

@@ -955,22 +955,24 @@ program.on('option:verbose', function () {
 
 ### .parse() and .parseAsync()
 
-The first argument to `.parse` is the array of strings to parse. You may omit the parameter to implicitly use `process.argv`.
+Call with no parameters to parse `process.argv`. Detects Electron and special node options like `node --eval`. Easy mode!
 
-If the arguments follow different conventions than node you can pass a `from` option in the second parameter:
+Or call with an array of strings to parse, and optionally where the user arguments start by specifying where the arguments are `from`:
 
-- 'node': default, `argv[0]` is the application and `argv[1]` is the script being run, with user parameters after that
-- 'electron': `argv[1]` varies depending on whether the electron application is packaged
-- 'user': all of the arguments from the user
+- `'node'`: default, `argv[0]` is the application and `argv[1]` is the script being run, with user arguments after that
+- `'electron'`: `argv[0]` is the application and `argv[1]` varies depending on whether the electron application is packaged
+- `'user'`: just user arguments
 
 For example:
 
 ```js
-program.parse(process.argv); // Explicit, node conventions
-program.parse(); // Implicit, and auto-detect electron
-program.parse(['-f', 'filename'], { from: 'user' });
+program.parse(); // parse process.argv and auto-detect electron and special node flags
+program.parse(process.argv); // assume argv[0] is app and argv[1] is script
+program.parse(['--port', '80'], { from: 'user' }); // just user supplied arguments, nothing special about argv[0]
 ```
 
+Use parseAsync instead of parse if any of your action handlers are async.
+
 If you want to parse multiple times, create a new program each time. Calling parse does not clear out any previous state.
 
 ### Parsing Configuration
@@ -1098,8 +1100,9 @@ program.error('Custom processing has failed', { exitCode: 2, code: 'my.custom.er
 By default, Commander calls `process.exit` when it detects errors, or after displaying the help or version. You can override
 this behaviour and optionally supply a callback. The default override throws a `CommanderError`.
 
-The override callback is passed a `CommanderError` with properties `exitCode` number, `code` string, and `message`. The default override behaviour is to throw the error, except for async handling of executable subcommand completion which carries on. The normal display of error messages or version or help
-is not affected by the override which is called after the display.
+The override callback is passed a `CommanderError` with properties `exitCode` number, `code` string, and `message`.
+Commander expects the callback to terminate the normal program flow, and will call `process.exit` if the callback returns.
+The normal display of error messages or version or help is not affected by the override which is called after the display.
 
 ```js
 program.exitOverride();

package/esm.mjs

@@ -12,5 +12,5 @@ export const {
   Command,
   Argument,
   Option,
-  Help
+  Help,
 } = commander;

package/lib/argument.js

@@ -50,7 +50,7 @@ class Argument {
   }
 
   /**
-   * @package internal use only
+   * @package
    */
 
   _concatValue(value, previous) {
@@ -98,7 +98,9 @@ class Argument {
     this.argChoices = values.slice();
     this.parseArg = (arg, previous) => {
       if (!this.argChoices.includes(arg)) {
-        throw new InvalidArgumentError(`Allowed choices are ${this.argChoices.join(', ')}.`);
+        throw new InvalidArgumentError(
+          `Allowed choices are ${this.argChoices.join(', ')}.`,
+        );
       }
       if (this.variadic) {
         return this._concatValue(arg, previous);
@@ -110,6 +112,8 @@ class Argument {
 
   /**
    * Make argument required.
+   *
+   * @returns {Argument}
    */
   argRequired() {
     this.required = true;
@@ -118,6 +122,8 @@ class Argument {
 
   /**
    * Make argument optional.
+   *
+   * @returns {Argument}
    */
   argOptional() {
     this.required = false;
@@ -136,9 +142,7 @@ class Argument {
 function humanReadableArgName(arg) {
   const nameOutput = arg.name() + (arg.variadic === true ? '...' : '');
 
-  return arg.required
-    ? '<' + nameOutput + '>'
-    : '[' + nameOutput + ']';
+  return arg.required ? '<' + nameOutput + '>' : '[' + nameOutput + ']';
 }
 
 exports.Argument = Argument;