commander - npm Package Compare versions

Comparing version 9.2.0 to 9.3.0

lib/help.js

@@ -218,3 +218,4 @@ const { humanReadableArgName } = require('./argument.js');
   /**
-   * Get the command description to show in the list of subcommands.
+   * Get the subcommand summary to show in the list of subcommands.
+   * (Fallback to description for backwards compatiblity.)
    *
@@ -227,3 +228,3 @@ * @param {Command} cmd
     // @ts-ignore: overloaded return type
-    return cmd.description();
+    return cmd.summary() || cmd.description();
   }
@@ -230,0 +231,0 @@

lib/option.js

@@ -37,2 +37,3 @@ const { InvalidArgumentError } = require('./error.js');
     this.conflictsWith = [];
+    this.implied = undefined;
   }
@@ -89,2 +90,20 @@
   /**
+   * Specify implied option values for when this option is set and the implied options are not.
+   *
+   * The custom processing (parseArg) is not called on the implied values.
+   *
+   * @example
+   * program
+   *   .addOption(new Option('--log', 'write logging information to file'))
+   *   .addOption(new Option('--trace', 'log extra details').implies({ log: 'trace.txt' }));
+   *
+   * @param {Object} impliedOptionValues
+   * @return {Option}
+   */
+  implies(impliedOptionValues) {
+    this.implied = Object.assign(this.implied || {}, impliedOptionValues);
+    return this;
+  }
+
+  /**
    * Set environment variable to check for option value.
@@ -223,2 +242,49 @@ * Priority order of option values is default < env < cli
 /**
+ * This class is to make it easier to work with dual options, without changing the existing
+ * implementation. We support separate dual options for separate positive and negative options,
+ * like `--build` and `--no-build`, which share a single option value. This works nicely for some
+ * use cases, but is tricky for others where we want separate behaviours despite
+ * the single shared option value.
+ */
+class DualOptions {
+  /**
+   * @param {Option[]} options
+   */
+  constructor(options) {
+    this.positiveOptions = new Map();
+    this.negativeOptions = new Map();
+    this.dualOptions = new Set();
+    options.forEach(option => {
+      if (option.negate) {
+        this.negativeOptions.set(option.attributeName(), option);
+      } else {
+        this.positiveOptions.set(option.attributeName(), option);
+      }
+    });
+    this.negativeOptions.forEach((value, key) => {
+      if (this.positiveOptions.has(key)) {
+        this.dualOptions.add(key);
+      }
+    });
+  }
+
+  /**
+   * Did the value come from the option, and not from possible matching dual option?
+   *
+   * @param {any} value
+   * @param {Option} option
+   * @returns {boolean}
+   */
+  valueFromOption(value, option) {
+    const optionKey = option.attributeName();
+    if (!this.dualOptions.has(optionKey)) return true;
+
+    // Use the value to deduce if (probably) came from the option.
+    const preset = this.negativeOptions.get(optionKey).presetArg;
+    const negativeValue = (preset !== undefined) ? preset : false;
+    return option.negate === (negativeValue === value);
+  }
+}
+
+/**
  * Convert string from kebab-case to camelCase.
@@ -261,1 +327,2 @@ *
 exports.splitOptionFlags = splitOptionFlags;
+exports.DualOptions = DualOptions;

package.json

 {
   "name": "commander",
-  "version": "9.2.0",
+  "version": "9.3.0",
   "description": "the complete solution for node.js command-line programs",
@@ -5,0 +5,0 @@ "keywords": [

Readme.md

@@ -38,2 +38,3 @@ # Commander.js
     - [.usage](#usage)
+    - [.description and .summary](#description-and-summary)
     - [.helpOption(flags, description)](#helpoptionflags-description)
@@ -61,3 +62,3 @@ - [.addHelpCommand()](#addhelpcommand)
 
-```bash
+```sh
 npm install commander
@@ -91,3 +92,3 @@ ```
 
-```sh
+```console
 $ node split.js -s / --fits a/b/c
@@ -126,3 +127,3 @@ error: unknown option '--fits'
 
-```sh
+```console
 $ node string-util.js help split
@@ -187,3 +188,3 @@ Usage: string-util split [options] <string>
 
-```bash
+```sh
 serve -p 80
@@ -227,3 +228,3 @@ serve -p80
 
-```bash
+```console
 $ pizza-options -p
@@ -264,3 +265,3 @@ error: option '-p, --pizza-type <type>' argument missing
 
-```bash
+```console
 $ pizza-options
@@ -295,3 +296,3 @@ cheese: blue
 
-```bash
+```console
 $ pizza-options
@@ -324,3 +325,3 @@ You ordered a pizza with sauce and mozzarella cheese
 
-```bash
+```console
 $ pizza-options
@@ -352,3 +353,3 @@ no cheese
 
-```bash
+```console
 $ pizza
@@ -378,3 +379,3 @@ error: required option '-c, --cheese <type>' not specified
 
-```bash
+```console
 $ collect -n 1 2 3 --letter a b c
@@ -401,3 +402,3 @@ Options:  { number: [ '1', '2', '3' ], letter: [ 'a', 'b', 'c' ] }
 
-```bash
+```console
 $ ./examples/pizza -V
@@ -419,3 +420,3 @@ 0.0.1
 
-Example files: [options-extra.js](./examples/options-extra.js), [options-env.js](./examples/options-env.js), [options-conflicts.js](./examples/options-conflicts.js)
+Example files: [options-extra.js](./examples/options-extra.js), [options-env.js](./examples/options-env.js), [options-conflicts.js](./examples/options-conflicts.js), [options-implies.js](./examples/options-implies.js)
 
@@ -429,6 +430,7 @@ ```js
   .addOption(new Option('--donate [amount]', 'optional donation in dollars').preset('20').argParser(parseFloat))
-  .addOption(new Option('--disable-server', 'disables the server').conflicts('port'));
+  .addOption(new Option('--disable-server', 'disables the server').conflicts('port'))
+  .addOption(new Option('--free-drink', 'small drink included free ').implies({ drink: 'small' }));
 ```
 
-```bash
+```console
 $ extra --help
@@ -441,4 +443,5 @@ Usage: help [options]
   -p, --port <number>    port number (env: PORT)
-  --donate [amount]      optional donation in dollars (preset: 20)
+  --donate [amount]      optional donation in dollars (preset: "20")
   --disable-server       disables the server
+  --free-drink           small drink included free
   -h, --help             display help for command
@@ -449,4 +452,4 @@
 
-$ PORT=80 extra --donate
-Options:  { timeout: 60, donate: 20, port: '80' }
+$ PORT=80 extra --donate --free-drink
+Options:  { timeout: 60, donate: 20, port: '80', freeDrink: true, drink: 'small' }
 
@@ -508,3 +511,3 @@ $ extra --disable-server --port 8000
 
-```bash
+```console
 $ custom -f 1e2
@@ -748,3 +751,3 @@ float: 100
 
-```bash
+```console
 $ node ./examples/pizza --help
@@ -765,3 +768,3 @@ Usage: pizza [options]
 
-```bash
+```sh
 shell help
@@ -828,3 +831,3 @@ shell --help
 
-```sh
+```console
 $ pizza --unknown
@@ -835,9 +838,10 @@ error: unknown option '--unknown'
 
-You can also show suggestions after an error for an unknown command or option.
+The default behaviour is to suggest correct spelling after an error for an unknown command or option. You
+can disable this.
 
 ```js
-program.showSuggestionAfterError();
+program.showSuggestionAfterError(false);
 ```
 
-```sh
+```console
 $ pizza --hepl
@@ -888,2 +892,16 @@ error: unknown option '--hepl'
 
+### .description and .summary
+
+The description appears in the help for the command. You can optionally supply a shorter
+summary to use when listed as a subcommand of the program.
+
+```js
+program
+  .command("duplicate")
+  .summary("make a copy")
+  .description(`Make a copy of the current project.
+This may require additional disk space.
+  `);
+```
+
 ### .helpOption(flags, description)
@@ -1016,3 +1034,3 @@
 
-```bash
+```sh
 node -r ts-node/register pm.ts
@@ -1019,0 +1037,0 @@ ```

typings/index.d.ts

@@ -134,2 +134,14 @@ // Type definitions for commander
   /**
+   * Specify implied option values for when this option is set and the implied options are not.
+   *
+   * The custom processing (parseArg) is not called on the implied values.
+   *
+   * @example
+   * program
+   *   .addOption(new Option('--log', 'write logging information to file'))
+   *   .addOption(new Option('--trace', 'log extra details').implies({ log: 'trace.txt' }));
+   */
+  implies(optionValues: OptionValues): this;
+
+  /**
    * Set environment variable to check for option value.
@@ -194,3 +206,3 @@ * Priority order of option values is default < env < cli
   subcommandTerm(cmd: Command): string;
-  /** Get the command description to show in the list of subcommands. */
+  /** Get the command summary to show in the list of subcommands. */
   subcommandDescription(cmd: Command): string;
@@ -528,6 +540,6 @@ /** Get the option term to show in the list of options. */
    */
-  option(flags: string, description?: string, defaultValue?: string | boolean): this;
+  option(flags: string, description?: string, defaultValue?: string | boolean | string[]): this;
   option<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
   /** @deprecated since v7, instead use choices or a custom function */
-  option(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean): this;
+  option(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean | string[]): this;
 
@@ -540,6 +552,6 @@ /**
    */
-  requiredOption(flags: string, description?: string, defaultValue?: string | boolean): this;
+  requiredOption(flags: string, description?: string, defaultValue?: string | boolean | string[]): this;
   requiredOption<T>(flags: string, description: string, fn: (value: string, previous: T) => T, defaultValue?: T): this;
   /** @deprecated since v7, instead use choices or a custom function */
-  requiredOption(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean): this;
+  requiredOption(flags: string, description: string, regexp: RegExp, defaultValue?: string | boolean | string[]): this;
 
@@ -714,2 +726,14 @@ /**
   /**
+   * Set the summary. Used when listed as subcommand of parent.
+   *
+   * @returns `this` command for chaining
+   */
+
+  summary(str: string): this;
+  /**
+   * Get the summary.
+   */
+  summary(): string;
+
+  /**
    * Set an alias for the command.
@@ -716,0 +740,0 @@ *

No alert changes

Improved metrics

Total package byte prevSize

168750

increased by3.01%

Lines of code

3631

increased by3.42%

Number of lines in readme file

1115

increased by1.64%

No dependency changes