From f1924dde020be1d5682c691cd2479e6340024235 Mon Sep 17 00:00:00 2001
From: John Gee <john@ruru.gen.nz>
Date: Thu, 27 Jun 2019 18:27:47 +1200
Subject: [PATCH] Added documentation for #795, --no-* improvements

---
 CHANGELOG.md                  |  4 ++++
 Readme.md                     | 25 ++++++++++++++++---------
 examples/options-negatable.js | 19 ++++++++++++-------
 3 files changed, 32 insertions(+), 16 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 5eb5f7c7e..6d929c4b1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,10 @@
   * Add parent command as prefix of subcommand in help (#980)
   * Add optional custom description to `.version` (#963)
   * Add `.helpOption(flags, description)` routine to customise help flags and description (#963)
+  * Fix behavior of --no-* options (#795)
+    * can now define both `--foo` and `--no-foo`
+    * custom event listeners: `--no-foo` on cli now emits `option:no-foo` (previously `option:foo`)
+    * default value: defining `--no-foo` after defining `--foo` leaves the default value unchanged (previously set it to false)
 
 2.20.0 / 2019-04-02
 ==================
diff --git a/Readme.md b/Readme.md
index c899ce909..9ec05af3f 100644
--- a/Readme.md
+++ b/Readme.md
@@ -99,30 +99,37 @@ cheese: stilton
 
 ### Other option types, negatable boolean and flag|value
 
-You can specify a boolean option long name with a leading `no-` to make it true by default and able to be negated.
+You can specify a boolean option long name with a leading `no-` to set the option value to false when used.
+Defined alone this also makes the option true by default.
+If you define `foo` first, adding `--no-foo` does not change the default value.
 
 
 ```js
 const program = require('commander');
 
 program
-  .option('-n, --no-sauce', 'Remove sauce')
+  .option('--no-sauce', 'Remove sauce')
+  .option('--cheese <flavour>', 'cheese flavour', 'mozzarella')
+  .option('--no-cheese', 'plain with no cheese')
   .parse(process.argv);
 
-if (program.sauce) console.log('you ordered a pizza with sauce');
-else console.log('you ordered a pizza without sauce');
+const sauceStr = program.sauce ? 'sauce' : 'no sauce';
+const cheeseStr = (program.cheese === false) ? 'no cheese' : `${program.cheese} cheese`;
+console.log(`You ordered a pizza with ${sauceStr} and ${cheeseStr}`);
 ```
 
 ```bash
-$ pizza-options
-you ordered a pizza with sauce
+$ pizza-options 
+You ordered a pizza with sauce and mozzarella cheese
 $ pizza-options --sauce
 error: unknown option '--sauce'
-$ pizza-options --no-sauce
-you ordered a pizza without sauce
+$ pizza-options --cheese=blue
+You ordered a pizza with sauce and blue cheese
+$ pizza-options --no-sauce --no-cheese
+You ordered a pizza with no sauce and no cheese
 ```
-You can specify an option which functions as a flag but may also take a value (declared using square brackets).
 
+You can specify an option which functions as a flag but may also take a value (declared using square brackets).
 
 ```js
 const program = require('commander');
diff --git a/examples/options-negatable.js b/examples/options-negatable.js
index 8f42947f1..ca81c8501 100644
--- a/examples/options-negatable.js
+++ b/examples/options-negatable.js
@@ -6,19 +6,24 @@
 //
 // Example output pretending command called pizza-options (or try directly with `node options-negatable.js`)
 //
-// $ pizza-options
-// you ordered a pizza with sauce
+// $ pizza-options 
+// You ordered a pizza with sauce and mozzarella cheese
 // $ pizza-options --sauce
 // error: unknown option '--sauce'
-// $ pizza-options --no-sauce
-// you ordered a pizza without sauce
+// $ pizza-options --cheese=blue
+// You ordered a pizza with sauce and blue cheese
+// $ pizza-options --no-sauce --no-cheese
+// You ordered a pizza with no sauce and no cheese
 
 const commander = require('commander');
 const program = new commander.Command();
 
 program
-  .option('-n, --no-sauce', 'Remove sauce')
+  .option('--no-sauce', 'Remove sauce')
+  .option('--cheese <flavour>', 'cheese flavour', 'mozzarella')
+  .option('--no-cheese', 'plain with no cheese')
   .parse(process.argv);
 
-if (program.sauce) console.log('you ordered a pizza with sauce');
-else console.log('you ordered a pizza without sauce');
+const sauceStr = program.sauce ? 'sauce' : 'no sauce';
+const cheeseStr = (program.cheese === false) ? 'no cheese' : `${program.cheese} cheese`;
+console.log(`You ordered a pizza with ${sauceStr} and ${cheeseStr}`);