commander 8.0.0 → 9.0.0-0

package/Readme.md

@@ -32,7 +32,8 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
     - [Custom help](#custom-help)
     - [Display help after errors](#display-help-after-errors)
     - [Display help from code](#display-help-from-code)
-    - [.usage and .name](#usage-and-name)
+    - [.name](#name)
+    - [.usage](#usage)
     - [.helpOption(flags, description)](#helpoptionflags-description)
     - [.addHelpCommand()](#addhelpcommand)
     - [More configuration](#more-configuration-2)
@@ -65,41 +66,37 @@ Commander exports a global object which is convenient for quick programs.
 This is used in the examples in this README for brevity.
 
 ```js
+// CommonJS (.cjs)
 const { program } = require('commander');
-program.version('0.0.1');
 ```
 
 For larger programs which may use commander in multiple ways, including unit testing, it is better to create a local Command object to use.
 
 ```js
+// CommonJS (.cjs)
 const { Command } = require('commander');
 const program = new Command();
-program.version('0.0.1');
 ```
 
-For named imports in ECMAScript modules, import from `commander/esm.mjs`.
-
 ```js
-// index.mjs
-import { Command } from 'commander/esm.mjs';
+// ECMAScript (.mjs)
+import { Command } from 'commander';
 const program = new Command();
 ```
 
-And in TypeScript:
-
 ```ts
-// index.ts
+// TypeScript (.ts)
 import { Command } from 'commander';
 const program = new Command();
 ```
 
-
 ## Options
 
 Options are defined with the `.option()` method, also serving as documentation for the options. Each option can have a short flag (single character) and a long name, separated by a comma or space or vertical bar ('|').
 
 The parsed options can be accessed by calling `.opts()` on a `Command` object, and are passed to the action handler.
-You can also use `.getOptionValue()` and `.setOptionValue()` to work with a single option value.
+(You can also use `.getOptionValue()` and `.setOptionValue()` to work with a single option value,
+and `.getOptionValueSource()` and `.setOptionValueWithSource()` when it matters where the option value came from.)
 
 Multi-word options such as "--template-engine" are camel-cased, becoming `program.opts().templateEngine` etc.
 
@@ -113,7 +110,7 @@ By default options on the command line are not positional, and can be specified
 ### Common option types, boolean and value
 
 The two most used option types are a boolean option, and an option which takes its value
-from the following argument (declared with angle brackets like `--expect <value>`). Both are `undefined` unless specified on command line.  
+from the following argument (declared with angle brackets like `--expect <value>`). Both are `undefined` unless specified on command line.
 
 Example file: [options-common.js](./examples/options-common.js)
 
@@ -149,7 +146,7 @@ pizza details:
 
 ### Default option value
 
-You can specify a default value for an option which takes a value.
+You can specify a default value for an option.
 
 Example file: [options-defaults.js](./examples/options-defaults.js)
 
@@ -175,7 +172,7 @@ You can define a boolean option long name with a leading `no-` to set the option
 Defined alone this also makes the option true by default.
 
 If you define `--foo` first, adding `--no-foo` does not change the default value from what it would
-otherwise be. You can specify a default boolean value for a boolean option and it can be overridden on command line.
+otherwise be.
 
 Example file: [options-negatable.js](./examples/options-negatable.js)
 
@@ -308,13 +305,15 @@ program.version('0.0.1', '-v, --vers', 'output the current version');
 You can add most options using the `.option()` method, but there are some additional features available
 by constructing an `Option` explicitly for less common cases.
 
-Example file: [options-extra.js](./examples/options-extra.js)
+Example files: [options-extra.js](./examples/options-extra.js), [options-env.js](./examples/options-env.js)
 
 ```js
 program
   .addOption(new Option('-s, --secret').hideHelp())
   .addOption(new Option('-t, --timeout <delay>', 'timeout in seconds').default(60, 'one minute'))
-  .addOption(new Option('-d, --drink <size>', 'drink size').choices(['small', 'medium', 'large']));
+  .addOption(new Option('-d, --drink <size>', 'drink size').choices(['small', 'medium', 'large']))
+  .addOption(new Option('-p, --port <number>', 'port number').env('PORT'))
+  .addOption(new Option('--donate [amount]', 'optional donation in dollars').preset('20').argParser(parseFloat));
 ```
 
 ```bash
@@ -324,10 +323,15 @@ Usage: help [options]
 Options:
   -t, --timeout <delay>  timeout in seconds (default: one minute)
   -d, --drink <size>     drink cup size (choices: "small", "medium", "large")
+  -p, --port <number>    port number (env: PORT)
+  --donate [amount]      optional donation in dollars (preset: 20)
   -h, --help             display help for command
 
 $ extra --drink huge
 error: option '-d, --drink <size>' argument 'huge' is invalid. Allowed choices are small, medium, large.
+
+$ PORT=80 extra --donate
+Options:  { timeout: 60, donate: 20, port: '80' }
 ```
 
 ### Custom option processing
@@ -426,7 +430,7 @@ program
   .addCommand(build.makeBuildCommand());
 ```
 
-Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will 
+Configuration options can be passed with the call to `.command()` and `.addCommand()`. Specifying `hidden: true` will
 remove the command from the generated help output. Specifying `isDefault: true` will run the subcommand if no other
 subcommand is specified ([example](./examples/defaultCommand.js)).
 
@@ -436,7 +440,7 @@ For subcommands, you can specify the argument syntax in the call to `.command()`
 is the only method usable for subcommands implemented using a stand-alone executable, but for other subcommands
 you can instead use the following method.
 
-To configure a command, you can use `.argument()` to specify each expected command-argument. 
+To configure a command, you can use `.argument()` to specify each expected command-argument.
 You supply the argument name and an optional description. The argument may be `<required>` or `[optional]`.
 You can specify a default value for an optional command-argument.
 
@@ -513,7 +517,7 @@ program
 ### Action handler
 
 The action handler gets passed a parameter for each command-argument you declared, and two additional parameters
-which are the parsed options and the command object itself. 
+which are the parsed options and the command object itself.
 
 Example file: [thank.js](./examples/thank.js)
 
@@ -550,8 +554,9 @@ pass more arguments than declared, but you can make this an error with `.allowEx
 ### Stand-alone executable (sub)commands
 
 When `.command()` is invoked with a description argument, this tells Commander that you're going to use stand-alone executables for subcommands.
-Commander will search the executables in the directory of the entry script (like `./examples/pm`) with the name `program-subcommand`, like `pm-install`, `pm-search`.
-You can specify a custom name with the `executableFile` configuration option.
+Commander will search the files in the directory of the entry script for a file with the name combination `command-subcommand`, like `pm-install` or `pm-search` in the example below. The search includes trying common file extensions, like `.js`.
+You may specify a custom name (and path) with the `executableFile` configuration option.
+You may specify a custom search directory for subcommands with `.executableDir()`.
 
 You handle the options for an executable (sub)command in the executable, and don't declare them at the top-level.
 
@@ -559,6 +564,7 @@ Example file: [pm](./examples/pm)
 
 ```js
 program
+  .name('pm')
   .version('0.1.0')
   .command('install [name]', 'install one or more packages')
   .command('search [query]', 'search with optional query')
@@ -630,7 +636,7 @@ shell spawn --help
 
 ### Custom help
 
-You can add extra text to be displayed along with the built-in help. 
+You can add extra text to be displayed along with the built-in help.
 
 Example file: [custom-help](./examples/custom-help)
 
@@ -664,7 +670,7 @@ The positions in order displayed are:
 - `after`: display extra information after built-in help
 - `afterAll`: add to the program for a global footer (epilog)
 
-The positions "beforeAll" and "afterAll" apply to the command and all its subcommands. 
+The positions "beforeAll" and "afterAll" apply to the command and all its subcommands.
 
 The second parameter can be a string, or a function returning a string. The function is passed a context object for your convenience. The properties are:
 
@@ -673,7 +679,7 @@ The second parameter can be a string, or a function returning a string. The func
 
 ### Display help after errors
 
-The default behaviour for usage errors is to just display a short error message. 
+The default behaviour for usage errors is to just display a short error message.
 You can change the behaviour to show the full help or a custom help message after an error.
 
 ```js
@@ -688,6 +694,18 @@ error: unknown option '--unknown'
 (add --help for additional information)
 ```
 
+You can also show suggestions after an error for an unknown command or option.
+
+```js
+program.showSuggestionAfterError();
+```
+
+```sh
+$ pizza --hepl
+error: unknown option '--hepl'
+(Did you mean --help?)
+```
+
 ### Display help from code
 
 `.help()`: display help information and exit immediately. You can optionally pass `{ error: true }` to display on stderr and exit with an error status.
@@ -696,10 +714,25 @@ error: unknown option '--unknown'
 
 `.helpInformation()`: get the built-in command help information as a string for processing or displaying yourself.
 
-### .usage and .name
+### .name
 
-These allow you to customise the usage description in the first line of the help. The name is otherwise
-deduced from the (full) program arguments. Given:
+The command name appears in the help, and is also used for locating stand-alone executable subcommands.
+
+You may specify the program name using `.name()` or in the Command constructor. For the program, Commander will
+fallback to using the script name from the full arguments passed into `.parse()`. However, the script name varies
+depending on how your program is launched so you may wish to specify it explicitly.
+
+```js
+program.name('pizza');
+const pm = new Command('pm');
+```
+
+Subcommands get a name when specified using `.command()`. If you create the subcommand yourself to use with `.addCommand()`,
+then set the name using `.name()` or in the Command constructor.
+
+### .usage
+
+This allows you to customise the usage description in the first line of the help. Given:
 
 ```js
 program
@@ -715,7 +748,7 @@ Usage: my-command [global options] command
 
 ### .helpOption(flags, description)
 
-By default every command has a help option. Override the default help flags and description. Pass false to disable the built-in help option.
+By default every command has a help option. You may change the default help flags and description. Pass false to disable the built-in help option.
 
 ```js
 program
@@ -747,7 +780,7 @@ There are methods getting the visible lists of arguments, options, and subcomman
 
 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.
@@ -762,13 +795,6 @@ You can execute custom actions by listening to command and option events.
 program.on('option:verbose', function () {
   process.env.VERBOSE = this.opts().verbose;
 });
-
-program.on('command:*', function (operands) {
-  console.error(`error: unknown command '${operands[0]}'`);
-  const availableCommands = program.commands.map(cmd => cmd.name());
-  mySuggestBestMatch(operands[0], availableCommands);
-  process.exitCode = 1;
-});
 ```
 
 ## Bits and pieces
@@ -809,7 +835,7 @@ program subcommand -b
 
 By default options are recognised before and after command-arguments. To only process options that come
 before the command-arguments, use `.passThroughOptions()`. This lets you pass the  arguments and following options through to another program
-without needing to use `--` to end the option processing. 
+without needing to use `--` to end the option processing.
 To use pass through options in a subcommand, the program needs to enable positional options.
 
 Example file: [pass-through-options.js](./examples/pass-through-options.js)
@@ -826,7 +852,7 @@ By default the option processing shows an error for an unknown option. To have a
 By default the argument processing does not display an error for more command-arguments than expected.
 To display an error for excess arguments, use`.allowExcessArguments(false)`.
 
-### Legacy options as properties 
+### Legacy options as properties
 
 Before Commander 7, the option values were stored as properties on the command.
 This was convenient to code but the downside was possible clashes with
@@ -903,7 +929,6 @@ You can modify this behaviour for custom applications. In addition, you can modi
 
 Example file: [configure-output.js](./examples/configure-output.js)
 
-
 ```js
 function errorColor(str) {
   // Add ANSI escape codes to display text in red.
@@ -960,6 +985,7 @@ const { Command } = require('commander');
 const program = new Command();
 
 program
+  .name('deploy')
   .version('0.0.1')
   .option('-c, --config <path>', 'set config path', './deploy.conf');
 
@@ -986,7 +1012,7 @@ Examples:
   $ deploy exec sequential
   $ deploy exec async`
   );
-  
+
 program.parse(process.argv);
 ```
 
@@ -994,8 +1020,8 @@ 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, and requires at least node v12.
-(For older versions of node, use an older version of Commander. Commander version 2.x has the widest 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.)
 
 The main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.
 

package/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}
@@ -109,6 +109,22 @@ class Argument {
     };
     return this;
   };
+
+  /**
+   * Make argument required.
+   */
+  argRequired() {
+    this.required = true;
+    return this;
+  }
+
+  /**
+   * Make argument optional.
+   */
+  argOptional() {
+    this.required = false;
+    return this;
+  }
 }
 
 /**