Enhance Option class to allow hiding help, specifying choices, and ch…

…ange how default value displayed in help (#1331)

* Add .addOption and use as bottleneck. Make all Option properties private.

* Desription for object is optional

* Add support for hidden options

* Try setFoo for booleans so less ambiguous what no parameter means

* Renamed method

* Restore Option property names to reduce churn

* Try more fluent names for non-property methods

* Avoid renaming existing members of Option

* Add default description for help

* Fix return JSDoc

* First cut at choices

* Throw CommanderError for easier detection

* Add catch for tidy coercion failure handing

* Add tests for Option.choices

* Rename custom option processing property

* Add run script for TypeScript checkJS

* Add tests for chaining routines

* More consistent name for custom option arg processing

* Add choices to help

* .default() now expects parameter

* Fixed return type

* Separate out argumentRejected for possible reuse

* Add back support for RegExp which accidentally dropped.

* Add test for obsolete regexp

* Add TypeScript definitions for new Option properties

* Switch from obsolete to deprecated, clearer meaning

* Fix left-over edit

* Add comment

* Simplify the comments

* Add README and example file

* Remove example covered elsewhere

* Restore example, leave change for a separate PR

* Fix example output to match changed code

* Add language to code blocks

* Rename getFullDescription, not using get much

* Add chaining test for addHelpText

* Describe as legacy rather than deprecated in comments, add @deprecated for editor feedback to discourage use

* Do not have to have both should and long flags these days

* Eliminate duplicate code using internal knowledge

* Rename parseArgWith to argParser

* Improve JSDoc for help

* Make code and declarations consistent to pass tsc checks

* Match up write signature to fix linting error

* Restore "deprecated", it is the right word

Readme.md

@@ -16,6 +16,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
     - [Common option types, boolean and value](#common-option-types-boolean-and-value)
     - [Default option value](#default-option-value)
     - [Other option types, negatable boolean and flag|value](#other-option-types-negatable-boolean-and-flagvalue)
+    - [Extra option features](#extra-option-features)
     - [Custom option processing](#custom-option-processing)
     - [Required option](#required-option)
     - [Variadic option](#variadic-option)
@@ -202,6 +203,33 @@ $ pizza-options --cheese mozzarella
 add cheese type mozzarella
 ```
 
+### Extra option features
+
+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)
+
+```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']));
+```
+
+```bash
+$ extra --help
+Usage: help [options]
+
+Options:
+  -t, --timeout <delay>  timeout in seconds (default: one minute)
+  -d, --drink <size>     drink cup size (choices: "small", "medium", "large")
+  -h, --help             display help for command
+
+$ extra --drink huge
+error: option '-d, --drink <size>' argument of 'huge' not in allowed choices: small, medium, large
+```
+
 ### Custom option processing
 
 You may specify a function to do custom processing of option values. The callback function receives two parameters, the user specified value and the

examples/options-extra.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+// This is used as an example in the README for extra option features.
+
+// const commander = require('commander'); // (normal include)
+const commander = require('../'); // include commander in git clone of commander repo
+const program = new commander.Command();
+
+program
+  .addOption(new commander.Option('-s, --secret').hideHelp())
+  .addOption(new commander.Option('-t, --timeout <delay>', 'timeout in seconds').default(60, 'one minute'))
+  .addOption(new commander.Option('-d, --drink <size>', 'drink cup size').choices(['small', 'medium', 'large']));
+
+program.parse();
+
+console.log('Options: ', program.opts());
+
+// Try the following:
+//  node options-extra.js --help
+//  node options-extra.js --drink huge