From ca17c15acc843dd8a08c36b8a334428042445922 Mon Sep 17 00:00:00 2001
From: John Gee <john@ruru.gen.nz>
Date: Sat, 22 May 2021 11:25:18 +1200
Subject: [PATCH] Add argument choices to README

---
 Readme.md                   | 24 ++++++++++++++++++------
 examples/arguments-extra.js | 23 +++++++++++++++++++++++
 2 files changed, 41 insertions(+), 6 deletions(-)
 create mode 100644 examples/arguments-extra.js

diff --git a/Readme.md b/Readme.md
index 1b43a9613..8ad95ca34 100644
--- a/Readme.md
+++ b/Readme.md
@@ -22,8 +22,9 @@ 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)
-    - [Custom argument processing](#custom-argument-processing)
+    - [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)
@@ -33,7 +34,7 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md)
     - [.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)
@@ -431,7 +432,7 @@ 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
@@ -441,7 +442,6 @@ To configure a command, you can use `.argument()` to specify each expected comma
 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: [argument.js](./examples/argument.js)
 
 ```js
@@ -477,7 +477,19 @@ program
   .arguments('<username> <password>');
 ```
 
-### Custom argument processing
+#### 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 before they are passed to the action handler.
 The callback function receives two parameters, the user specified command-argument and the previous value for the argument.
diff --git a/examples/arguments-extra.js b/examples/arguments-extra.js
new file mode 100644
index 000000000..80cebbe81
--- /dev/null
+++ b/examples/arguments-extra.js
@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+// This is used as an example in the README for extra argument features.
+
+// const commander = require('commander'); // (normal include)
+const commander = require('../'); // include commander in git clone of commander repo
+const program = new commander.Command();
+
+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'))
+  .action((drinkSize, timeout) => {
+    console.log(`Drink size: ${drinkSize}`);
+    console.log(`Timeout (s): ${timeout}`);
+  });
+
+program.parse();
+
+// Try the following:
+//  node arguments-extra.js --help
+//  node arguments-extra.js huge
+//  node arguments-extra.js small
+//  node arguments-extra.js medium 30