commander 7.2.0 → 8.0.0

package/Readme.md

@@ -22,16 +22,20 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
     - [More configuration](#more-configuration)
     - [Custom option processing](#custom-option-processing)
   - [Commands](#commands)
-    - [Specify the argument syntax](#specify-the-argument-syntax)
+    - [Command-arguments](#command-arguments)
+      - [More configuration](#more-configuration-1)
+      - [Custom argument processing](#custom-argument-processing)
     - [Action handler](#action-handler)
     - [Stand-alone executable (sub)commands](#stand-alone-executable-subcommands)
+    - [Life cycle hooks](#life-cycle-hooks)
   - [Automated help](#automated-help)
     - [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)
     - [.helpOption(flags, description)](#helpoptionflags-description)
     - [.addHelpCommand()](#addhelpcommand)
-    - [More configuration](#more-configuration-1)
+    - [More configuration](#more-configuration-2)
   - [Custom event listeners](#custom-event-listeners)
   - [Bits and pieces](#bits-and-pieces)
     - [.parse() and .parseAsync()](#parse-and-parseasync)
@@ -94,7 +98,10 @@ const program = new Command();
 
 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. Multi-word options such as "--template-engine" are camel-cased, becoming `program.opts().templateEngine` etc.
+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.
+
+Multi-word options such as "--template-engine" are camel-cased, becoming `program.opts().templateEngine` etc.
 
 Multiple short flags may optionally be combined in a single argument following the dash: boolean flags, followed by a single option taking a value (possibly followed by the value).
 For example `-a -b -p 80` may be written as `-ab -p80` or even `-abp80`.
@@ -126,12 +133,9 @@ if (options.pizzaType) console.log(`- ${options.pizzaType}`);
 ```
 
 ```bash
-$ pizza-options -d
-{ debug: true, small: undefined, pizzaType: undefined }
-pizza details:
 $ pizza-options -p
 error: option '-p, --pizza-type <type>' argument missing
-$ pizza-options -ds -p vegetarian
+$ pizza-options -d -s -p vegetarian
 { debug: true, small: true, pizzaType: 'vegetarian' }
 pizza details:
 - small pizza size
@@ -342,7 +346,7 @@ function myParseInt(value, dummyPrevious) {
   // parseInt takes a string and a radix
   const parsedValue = parseInt(value, 10);
   if (isNaN(parsedValue)) {
-    throw new commander.InvalidOptionArgumentError('Not a number.');
+    throw new commander.InvalidArgumentError('Not a number.');
   }
   return parsedValue;
 }
@@ -394,7 +398,7 @@ $ custom --list x,y,z
 
 You can specify (sub)commands using `.command()` or `.addCommand()`. There are two ways these can be implemented: using an action handler attached to the command, or as a stand-alone executable file (described in more detail later). The subcommands may be nested ([example](./examples/nestedCommands.js)).
 
-In the first parameter to `.command()` you specify the command name and any command-arguments. The arguments may be `<required>` or `[optional]`, and the last argument may also be `variadic...`.
+In the first parameter to `.command()` you specify the command name. You may append the command-arguments after the command name, or specify them separately using `.argument()`. The arguments may be `<required>` or `[optional]`, and the last argument may also be `variadic...`.
 
 You can use `.addCommand()` to add an already configured subcommand to the program.
 
@@ -410,7 +414,7 @@ program
     console.log('clone command called');
   });
 
-// Command implemented using stand-alone executable file (description is second parameter to `.command`)
+// Command implemented using stand-alone executable file, indicated by adding description as second parameter to `.command`.
 // Returns `this` for adding more commands.
 program
   .command('start <service>', 'start named service')
@@ -426,36 +430,37 @@ Configuration options can be passed with the call to `.command()` and `.addComma
 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)).
 
-### Specify the argument syntax
+### Command-arguments
+
+For subcommands, you can specify the argument syntax in the call to `.command()` (as shown above). This
+is the only method usable for subcommands implemented using a stand-alone executable, but for other subcommands
+you can instead use the following method.
 
-You use `.arguments` to specify the expected command-arguments for the top-level command, and for subcommands they are usually
-included in the `.command` call. Angled brackets (e.g. `<required>`) indicate required command-arguments.
-Square brackets (e.g. `[optional]`) indicate optional command-arguments.
-You can optionally describe the arguments in the help by supplying a hash as second parameter to `.description()`.
+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.
 
-Example file: [arguments.js](./examples/arguments.js)
+Example file: [argument.js](./examples/argument.js)
 
 ```js
 program
   .version('0.1.0')
-  .arguments('<username> [password]')
-  .description('test command', {
-    username: 'user to login',
-    password: 'password for user, if required'
-  })
+  .argument('<username>', 'user to login')
+  .argument('[password]', 'password for user, if required', 'no password given')
   .action((username, password) => {
     console.log('username:', username);
-    console.log('environment:', password || 'no password given');
+    console.log('password:', password);
   });
 ```
 
  The last argument of a command can be variadic, and only the last argument.  To make an argument variadic you
- append `...` to the argument name. For example:
+ append `...` to the argument name. A variadic argument is passed to the action handler as an array. For example:
 
 ```js
 program
   .version('0.1.0')
-  .command('rmdir <dirs...>')
+  .command('rmdir')
+  .argument('<dirs...>')
   .action(function (dirs) {
     dirs.forEach((dir) => {
       console.log('rmdir %s', dir);
@@ -463,7 +468,47 @@ program
   });
 ```
 
-The variadic argument is passed to the action handler as an array.
+There is a convenience method to add multiple arguments at once, but without descriptions:
+
+```js
+program
+  .arguments('<username> <password>');
+```
+
+#### More configuration
+
+There are some additional features available by constructing an `Argument` explicitly for less common cases.
+
+Example file: [arguments-extra.js](./examples/arguments-extra.js)
+
+```js
+program
+  .addArgument(new commander.Argument('<drink-size>', 'drink cup size').choices(['small', 'medium', 'large']))
+  .addArgument(new commander.Argument('[timeout]', 'timeout in seconds').default(60, 'one minute'))
+```
+
+#### Custom argument processing
+
+You may specify a function to do custom processing of command-arguments (like for option-arguments).
+The callback function receives two parameters, the user specified command-argument and the previous value for the argument.
+It returns the new value for the argument.
+
+The processed argument values are passed to the action handler, and saved as `.processedArgs`.
+
+You can optionally specify the default/starting value for the argument after the function parameter.
+
+Example file: [arguments-custom-processing.js](./examples/arguments-custom-processing.js)
+
+```js
+program
+  .command('add')
+  .argument('<first>', 'integer argument', myParseInt)
+  .argument('[second]', 'integer argument', myParseInt, 1000)
+  .action((first, second) => {
+    console.log(`${first} + ${second} = ${first + second}`);
+  })
+;
+```
 
 ### Action handler
 
@@ -474,7 +519,7 @@ Example file: [thank.js](./examples/thank.js)
 
 ```js
 program
-  .arguments('<name>')
+  .argument('<name>')
   .option('-t, --title <honorific>', 'title to use before name')
   .option('-d, --debug', 'display some debugging')
   .action((name, options, command) => {
@@ -525,6 +570,33 @@ program.parse(process.argv);
 
 If the program is designed to be installed globally, make sure the executables have proper modes, like `755`.
 
+### Life cycle hooks
+
+You can add callback hooks to a command for life cycle events.
+
+Example file: [hook.js](./examples/hook.js)
+
+```js
+program
+  .option('-t, --trace', 'display trace statements for commands')
+  .hook('preAction', (thisCommand, actionCommand) => {
+    if (thisCommand.opts().trace) {
+      console.log(`About to call action handler for subcommand: ${actionCommand.name()}`);
+      console.log('arguments: %O', actionCommand.args);
+      console.log('options: %o', actionCommand.opts());
+    }
+  });
+```
+
+The callback hook can be `async`, in which case you call `.parseAsync` rather than `.parse`. You can add multiple hooks per event.
+
+The supported events are:
+
+- `preAction`: called before action handler for this command and its subcommands
+- `postAction`: called after action handler for this command and its subcommands
+
+The hook is passed the command it was added to, and the command running the action handler.
+
 ## Automated help
 
 The help information is auto-generated based on the information commander already knows about your program. The default
@@ -599,6 +671,23 @@ The second parameter can be a string, or a function returning a string. The func
 - error: a boolean for whether the help is being displayed due to a usage error
 - command: the Command which is displaying the help
 
+### Display help after errors
+
+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
+program.showHelpAfterError();
+// or
+program.showHelpAfterError('(add --help for additional information)');
+```
+
+```sh
+$ pizza --unknown
+error: unknown option '--unknown'
+(add --help for additional information)
+```
+
 ### 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.
@@ -905,7 +994,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, and requires at least node v10.
+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 main forum for free and community support is the project [Issues](https://github.com/tj/commander.js/issues) on GitHub.

package/esm.mjs

@@ -1,4 +1,15 @@
 import commander from './index.js';
 
 // wrapper to provide named exports for ESM.
-export const { program, Option, Command, CommanderError, InvalidOptionArgumentError, Help, createCommand } = commander;
+export const {
+  program,
+  createCommand,
+  createArgument,
+  createOption,
+  CommanderError,
+  InvalidArgumentError,
+  Command,
+  Argument,
+  Option,
+  Help
+} = commander;