Add extended conflicts example (#1700)

* Add extended conflicts example

* Trim trailing whitespace

Readme.md

@@ -389,7 +389,7 @@ 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 files: [options-extra.js](./examples/options-extra.js), [options-env.js](./examples/options-env.js)
+Example files: [options-extra.js](./examples/options-extra.js), [options-env.js](./examples/options-env.js), [options-conflicts.js](./examples/options-conflicts.js)
 
 ```js
 program
@@ -398,7 +398,7 @@ program
   .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))
-  .addOption(new Option('--disable-server', 'disables the server').conflicts(['port'])); // or `.conflicts('port')` for a single conflict
+  .addOption(new Option('--disable-server', 'disables the server').conflicts('port'));
 ```
 
 ```bash

examples/options-conflicts.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+// const { Command, Option } = require('commander'); // (normal include)
+const { Command, Option } = require('../'); // include commander in git clone of commander repo
+const program = new Command();
+
+// You can use .conflicts() with a single string, which is the camel-case name of the conflicting option.
+program
+  .command('pay')
+  .addOption(new Option('--cash').conflicts('creditCard'))
+  .addOption(new Option('--credit-card'))
+  .action((options) => {
+    if (options.cash) {
+      console.log('Paying by cash')
+    } else if (options.creditCard) {
+      console.log('Paying by credit card')
+    } else {
+      console.log('Payment method unknown')
+    }
+  });
+
+  // The default value for an option does not cause a conflict.
+  // A value specified using an environment variable is checked for conflicts.
+program
+  .command('source')
+  .addOption(new Option('-p, --port <number>', 'port number for server')
+    .default(80)
+    .env('PORT')
+  ).addOption(new Option('--interactive', 'prompt for user input instead of listening to a port')
+    .conflicts('port')
+  ).action((options) => {
+    if (options.interactive) {
+      console.log('What do you want to do today?')
+    } else {
+      console.log(`Running server on port: ${options.port}`);
+    }
+  });
+
+// You can use .conflicts() with an array of option names.
+// A negated option is not separate from the positive option for conflicts (they have same option name).
+program
+  .command('paint')
+  .addOption(new Option('--summer', 'use a mixture of summer colors').conflicts(['autumn', 'colour']))
+  .addOption(new Option('--autumn', 'use a mixture of autumn colors').conflicts(['summer', 'colour']))
+  .addOption(new Option('--colour <shade>', 'use a single solid colour'))
+  .addOption(new Option('--no-colour', 'leave surface natural'))
+  .action((options) => {
+    let colour = 'not specified';
+    if (options.colour === false) {
+      colour = 'natural';
+    } else if (options.colour) {
+      colour = options.colour;
+    } else if (options.summer) {
+      colour = 'summer';
+    } else if (options.autumn) {
+      colour = 'autumn';
+    }
+    console.log(`Painting colour is ${colour}`);
+    });
+
+program.parse();
+
+// Try the following:
+//    node options-conflicts.js pay --cash --credit-card
+//
+//    node options-conflicts.js source
+//    node options-conflicts.js source --interactive
+//    node options-conflicts.js source --port 8080 --interactive
+//    PORT=8080 node options-conflicts.js source --interactive
+//
+//    node options-conflicts.js paint --colour=red --summer
+//    node options-conflicts.js paint --no-colour --autumn

examples/options-extra.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 
 // This is used as an example in the README for extra option features.
-// See also options-env.js for more extensive env examples.
+// See also options-env.js for more extensive env examples,
+// and options-conflicts.js for more details about .conflicts().
 
 // const { Command, Option } = require('commander'); // (normal include)
 const { Command, Option } = require('../'); // include commander in git clone of commander repo
@@ -13,7 +14,7 @@ program
   .addOption(new Option('-d, --drink <size>', 'drink cup 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))
-  .addOption(new Option('--disable-server', 'disables the server').conflicts(['port'])); // or `.conflicts('port')` for a single conflict
+  .addOption(new Option('--disable-server', 'disables the server').conflicts('port'));
 
 program.parse();
 

lib/option.js

@@ -68,7 +68,12 @@ class Option {
   }
 
   /**
-   * Set options name(s) that conflict with this option.
+   * Add option name(s) that conflict with this option.
+   * An error will be displayed if conflicting options are found during parsing.
+   *
+   * @example
+   * new Option('--rgb').conflicts('cmyk');
+   * new Option('--js').conflicts(['ts', 'jsx']);
    *
    * @param {string | string[]} names
    * @return {Option}

typings/index.d.ts

@@ -119,7 +119,14 @@ export class Option {
   preset(arg: unknown): this;
 
   /**
-   * Set options name(s) that conflict with this option.
+   * Add option name(s) that conflict with this option.
+   * An error will be displayed if conflicting options are found during parsing.
+   *
+   * @example
+   * ```ts
+   * new Option('--rgb').conflicts('cmyk');
+   * new Option('--js').conflicts(['ts', 'jsx']);
+   * ```
    */
   conflicts(names: string | string[]): this;