commander 12.0.0 → 13.0.0-0

package/Readme.md

@@ -79,7 +79,8 @@ const { program } = require('commander');
 
 program
   .option('--first')
-  .option('-s, --separator <char>');
+  .option('-s, --separator <char>')
+  .argument('<string>');
 
 program.parse();
 
@@ -678,8 +679,7 @@ async function main() {
 }
 ```
 
-A command's options and arguments on the command line are validated when the command is used. Any unknown options or missing arguments will be reported as an error. You can suppress the unknown option checks with `.allowUnknownOption()`. By default, it is not an error to
-pass more arguments than declared, but you can make this an error with `.allowExcessArguments(false)`.
+A command's options and arguments on the command line are validated when the command is used. Any unknown options or missing arguments or excess arguments will be reported as an error. You can suppress the unknown option check with `.allowUnknownOption()`. You can suppress the excess arguments check with `.allowExcessArguments()`.
 
 ### Stand-alone executable (sub)commands
 
@@ -696,7 +696,7 @@ Example file: [pm](./examples/pm)
 program
   .name('pm')
   .version('0.1.0')
-  .command('install [name]', 'install one or more packages')
+  .command('install [package-names...]', 'install one or more packages')
   .command('search [query]', 'search with optional query')
   .command('update', 'update installed packages', { executableFile: 'myUpdateSubCommand' })
   .command('list', 'list packages installed', { isDefault: true });
@@ -923,23 +923,7 @@ program.helpCommand('assist [command]', 'show assistance');
 The built-in help is formatted using the Help class.
 You can configure the Help behaviour by modifying data properties and methods using `.configureHelp()`, or by subclassing using `.createHelp()` if you prefer.
 
-The data properties are:
-
-- `helpWidth`: specify the wrap width, useful for unit tests
-- `sortSubcommands`: sort the subcommands alphabetically
-- `sortOptions`: sort the options alphabetically
-- `showGlobalOptions`: show a section with the global options from the parent command(s)
-
-You can override any method on the [Help](./lib/help.js) class. There are methods getting the visible lists of arguments, options, and subcommands. There are methods for formatting the items in the lists, with each item having a _term_ and _description_. Take a look at `.formatHelp()` to see how they are used.
-
-Example file: [configure-help.js](./examples/configure-help.js)
-
-```js
-program.configureHelp({
-  sortSubcommands: true,
-  subcommandTerm: (cmd) => cmd.name() // Just show the name, instead of short usage.
-});
-```
+For more detail see (./docs/help-in-depth.md)
 
 ## Custom event listeners
 
@@ -955,22 +939,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

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;