commander 13.0.0 → 13.1.0

package/Readme.md

@@ -175,7 +175,15 @@ const program = new Command();
 
 ## Options
 
-Options are defined with the `.option()` method, also serving as documentation for the options. Each option can have a short flag (single character) and a long name, separated by a comma or space or vertical bar ('|').
+Options are defined with the `.option()` method, also serving as documentation for the options. Each option can have a short flag (single character) and a long name, separated by a comma or space or vertical bar ('|'). To allow a wider range of short-ish flags than just
+single characters, you may also have two long options. Examples:
+
+```js
+program
+  .option('-p, --port <number>', 'server port number')
+  .option('--trace', 'add extra debugging output')
+  .option('--ws, --workspace <name>', 'use a custom workspace')
+```
 
 The parsed options can be accessed by calling `.opts()` on a `Command` object, and are passed to the action handler.
 

package/lib/command.js

@@ -756,7 +756,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
    * @example
    * program
    *     .option('-p, --pepper', 'add pepper')
-   *     .option('-p, --pizza-type <TYPE>', 'type of pizza') // required option-argument
+   *     .option('--pt, --pizza-type <TYPE>', 'type of pizza') // required option-argument
    *     .option('-c, --cheese [CHEESE]', 'add extra cheese', 'mozzarella') // optional option-argument with default
    *     .option('-t, --tip <VALUE>', 'add tip to purchase cost', parseFloat) // custom parse function
    *

package/lib/option.js

@@ -18,7 +18,7 @@ class Option {
     this.variadic = /\w\.\.\.[>\]]$/.test(flags); // The option can take multiple values.
     this.mandatory = false; // The option must have a value after parsing, which usually means it must be specified on command line.
     const optionFlags = splitOptionFlags(flags);
-    this.short = optionFlags.shortFlag;
+    this.short = optionFlags.shortFlag; // May be a short flag, undefined, or even a long flag (if option has two long flags).
     this.long = optionFlags.longFlag;
     this.negate = false;
     if (this.long) {
@@ -321,25 +321,44 @@ function splitOptionFlags(flags) {
   const longFlagExp = /^--[^-]/;
 
   const flagParts = flags.split(/[ |,]+/).concat('guard');
+  // Normal is short and/or long.
   if (shortFlagExp.test(flagParts[0])) shortFlag = flagParts.shift();
   if (longFlagExp.test(flagParts[0])) longFlag = flagParts.shift();
+  // Long then short. Rarely used but fine.
+  if (!shortFlag && shortFlagExp.test(flagParts[0]))
+    shortFlag = flagParts.shift();
+  // Allow two long flags, like '--ws, --workspace'
+  // This is the supported way to have a shortish option flag.
+  if (!shortFlag && longFlagExp.test(flagParts[0])) {
+    shortFlag = longFlag;
+    longFlag = flagParts.shift();
+  }
 
-  // Check for some unsupported flags that people try.
-  if (/^-[^-][^-]/.test(flagParts[0]))
-    throw new Error(
-      `invalid Option flags, short option is dash and single character: '${flags}'`,
-    );
-  if (shortFlag && shortFlagExp.test(flagParts[0]))
-    throw new Error(
-      `invalid Option flags, more than one short flag: '${flags}'`,
-    );
-  if (longFlag && longFlagExp.test(flagParts[0]))
+  // Check for unprocessed flag. Fail noisily rather than silently ignore.
+  if (flagParts[0].startsWith('-')) {
+    const unsupportedFlag = flagParts[0];
+    const baseError = `option creation failed due to '${unsupportedFlag}' in option flags '${flags}'`;
+    if (/^-[^-][^-]/.test(unsupportedFlag))
+      throw new Error(
+        `${baseError}
+- a short flag is a single dash and a single character
+  - either use a single dash and a single character (for a short flag)
+  - or use a double dash for a long option (and can have two, like '--ws, --workspace')`,
+      );
+    if (shortFlagExp.test(unsupportedFlag))
+      throw new Error(`${baseError}
+- too many short flags`);
+    if (longFlagExp.test(unsupportedFlag))
+      throw new Error(`${baseError}
+- too many long flags`);
+
+    throw new Error(`${baseError}
+- unrecognised flag format`);
+  }
+  if (shortFlag === undefined && longFlag === undefined)
     throw new Error(
-      `invalid Option flags, more than one long flag: '${flags}'`,
+      `option creation failed due to no flags found in '${flags}'.`,
     );
-  // Generic error if failed to find a flag or an unexpected flag left over.
-  if (!(shortFlag || longFlag) || flagParts[0].startsWith('-'))
-    throw new Error(`invalid Option flags: '${flags}'`);
 
   return { shortFlag, longFlag };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commander",
-  "version": "13.0.0",
+  "version": "13.1.0",
   "description": "the complete solution for node.js command-line programs",
   "keywords": [
     "commander",

package/typings/index.d.ts

@@ -617,7 +617,7 @@ export class Command {
    * ```js
    * program
    *     .option('-p, --pepper', 'add pepper')
-   *     .option('-p, --pizza-type <TYPE>', 'type of pizza') // required option-argument
+   *     .option('--pt, --pizza-type <TYPE>', 'type of pizza') // required option-argument
    *     .option('-c, --cheese [CHEESE]', 'add extra cheese', 'mozzarella') // optional option-argument with default
    *     .option('-t, --tip <VALUE>', 'add tip to purchase cost', parseFloat) // custom parse function
    * ```