cli-kiss 0.2.4 → 0.2.6

package/src/lib/Usage.ts

@@ -18,9 +18,8 @@ import {
 export type UsageCommand = {
   /**
    * Segments of the usage line
-   * (e.g. `my-cli <POSITIONAL> subcommand <ANOTHER_POSITIONAL>`).
    */
-  segments: Array<UsageSegment>;
+  segments: Array<{ positional: string } | { subcommand: string }>;
   /**
    * Command metadata.
    */
@@ -39,25 +38,6 @@ export type UsageCommand = {
   options: Array<UsageOption>;
 };
 
-/**
- * One segment of the usage line.
- */
-export type UsageSegment = { positional: string } | { subcommand: string };
-
-/**
- * Usage metadata. Produced by {@link Operation.generateUsage}, consumed when building {@link UsageCommand}.
- */
-export type UsageOperation = {
-  /**
-   * Registered options.
-   */
-  options: Array<UsageOption>;
-  /**
-   * Declared positionals, in order.
-   */
-  positionals: Array<UsagePositional>;
-};
-
 /**
  * Positional metadata for the `Positionals:` section of help.
  */
@@ -65,16 +45,15 @@ export type UsagePositional = {
   /**
    * Help text.
    */
-  description: string | undefined;
+  description?: string | undefined;
   /**
    * Short note shown in parentheses.
    */
-  hint: string | undefined;
+  hint?: string | undefined;
   /**
    * Placeholder label shown in the usage line and the `Positionals:` section.
-   * Required: `<NAME>`, optional: `[NAME]`, variadic: `[NAME]...`.
    */
-  label: Uppercase<string>;
+  label: string;
 };
 
 /**
@@ -88,11 +67,11 @@ export type UsageSubcommand = {
   /**
    * From {@link CommandInformation.description}.
    */
-  description: string | undefined;
+  description?: string | undefined;
   /**
    * From {@link CommandInformation.hint}.
    */
-  hint: string | undefined;
+  hint?: string | undefined;
 };
 
 /**
@@ -102,27 +81,27 @@ export type UsageOption = {
   /**
    * Short-form name without `-` (e.g. `"v"`).
    */
-  short: string | undefined;
+  short?: string | undefined;
   /**
    * Long-form name without `--` (e.g. `"verbose"`).
    */
-  long: Lowercase<string>;
+  long: string;
   /**
-   * Extra annotation appended to the option label in help (e.g. `[=no]`, ` [*]`).
+   * Value placeholder in help (e.g. `"<FILE>"`).
    */
-  annotation: string | undefined;
+  label?: string | undefined;
   /**
-   * Help text.
+   * Extra annotation appended to the option label in help.
    */
-  description: string | undefined;
+  annotation?: string | undefined;
   /**
-   * Short note shown in parentheses.
+   * Help text.
    */
-  hint: string | undefined;
+  description?: string | undefined;
   /**
-   * Value placeholder in help (e.g. `"<FILE>"`). `undefined` for flags.
+   * Short note shown in parentheses.
    */
-  label: Uppercase<string> | undefined;
+  hint?: string | undefined;
 };
 
 /**
@@ -137,16 +116,16 @@ export type UsageOption = {
  * <detail lines...>
  *
  * Positionals:
- *   <LABEL>  <description> (<hint>)
+ *   <label>  <description> (<hint>)
  *
  * Subcommands:
  *   <name>  <description> (<hint>)
  *
  * Options:
- *   -s, --long <LABEL><annotation>  <description> (<hint>)
+ *   -s, --long <label><annotation>  <description> (<hint>)
  *
  * Examples:
- *   <description>
+ *   <explanation>
  *   <command line>
  *
  * ```
@@ -170,7 +149,7 @@ export type UsageOption = {
  * ```
  */
 export function usageToStyledLines(params: {
-  cliName: Lowercase<string>;
+  cliName: string;
   usage: UsageCommand;
   typoSupport: TypoSupport;
 }) {
@@ -295,9 +274,15 @@ export function usageToStyledLines(params: {
           } else {
             commandLineText.push(textConstants(`--${option.long}`));
           }
-          if (option.value !== undefined) {
+          if (option.inlined !== undefined) {
             commandLineText.push(textSubtleInfo("="));
-            commandLineText.push(textUserInput(option.value));
+            commandLineText.push(textUserInput(option.inlined));
+          }
+          if (option.separated !== undefined) {
+            for (const separatedValue of option.separated) {
+              commandLineText.push(textDelimiter(" "));
+              commandLineText.push(textUserInput(separatedValue));
+            }
           }
         }
       }
@@ -310,8 +295,8 @@ export function usageToStyledLines(params: {
 }
 
 function createInformationals(usage: {
-  description: string | undefined;
-  hint: string | undefined;
+  description?: string | undefined;
+  hint?: string | undefined;
 }): Array<TypoText> {
   const informationals = [];
   if (usage.description) {

package/tests/unit.Reader.parsings.ts

@@ -0,0 +1,50 @@
+import { expect, it } from "@jest/globals";
+import { ReaderArgs } from "../src";
+
+it("run", async function () {
+  const readerArgs1 = new ReaderArgs(["--val=1", "A", "B", "STOP", "C"]);
+  const kOptionVariadicStop = readerArgs1.registerOption({
+    longs: ["val"],
+    shorts: [],
+    parsing: {
+      consumeShortGroup: true,
+      consumeNextArg: (_inlined, separated, nextArg) =>
+        nextArg !== undefined && separated[separated.length - 1] !== "STOP",
+    },
+  });
+  expect(readerArgs1.consumePositional()).toStrictEqual("C");
+  expect(readerArgs1.consumePositional()).toStrictEqual(undefined);
+  expect(readerArgs1.getOptionValues(kOptionVariadicStop)).toStrictEqual([
+    { inlined: "1", separated: ["A", "B", "STOP"] },
+  ]);
+
+  const readerArgs2 = new ReaderArgs(["--val=1", "A", "B", "C"]);
+  const kOptionVariadicFull = readerArgs2.registerOption({
+    longs: ["val"],
+    shorts: [],
+    parsing: {
+      consumeShortGroup: true,
+      consumeNextArg: (_inlined, _separated, nextArg) => nextArg !== undefined,
+    },
+  });
+  expect(readerArgs2.consumePositional()).toStrictEqual(undefined);
+  expect(readerArgs2.getOptionValues(kOptionVariadicFull)).toStrictEqual([
+    { inlined: "1", separated: ["A", "B", "C"] },
+  ]);
+
+  const readerArgs3 = new ReaderArgs(["--val=2", "A", "B", "--val=1", "C"]);
+  const kOptionVariadicKeyed = readerArgs3.registerOption({
+    longs: ["val"],
+    shorts: [],
+    parsing: {
+      consumeShortGroup: true,
+      consumeNextArg: (inlined, separated) =>
+        separated.length < Number(inlined ?? "0"),
+    },
+  });
+  expect(readerArgs3.consumePositional()).toStrictEqual(undefined);
+  expect(readerArgs3.getOptionValues(kOptionVariadicKeyed)).toStrictEqual([
+    { inlined: "2", separated: ["A", "B"] },
+    { inlined: "1", separated: ["C"] },
+  ]);
+});

package/tests/unit.command.execute.ts

@@ -12,9 +12,9 @@ import {
   positionalRequired,
   positionalVariadics,
   ReaderArgs,
+  type,
   typeList,
   typeNumber,
-  typeString,
 } from "../src";
 
 const rootCommand = commandChained(
@@ -33,7 +33,7 @@ const rootCommand = commandChained(
           default: false,
         }),
       },
-      positionals: [positionalRequired({ label: "POS-1", type: typeNumber })],
+      positionals: [positionalRequired({ type: typeNumber() })],
     },
     async function (context, inputs) {
       return { at: "root", context, inputs };
@@ -46,15 +46,15 @@ const rootCommand = commandChained(
         options: {
           string: optionSingleValue({
             long: "string-option",
-            type: typeString,
-            default: () => undefined,
+            type: type(),
+            defaultWhenNotDefined: () => undefined,
           }),
           number: optionRepeatable({
             long: "number-option",
-            type: typeList(typeNumber),
+            type: typeList(typeNumber()),
           }),
         },
-        positionals: [positionalRequired({ type: typeNumber })],
+        positionals: [positionalRequired({ type: typeNumber() })],
       },
       async function (context, inputs) {
         return { at: "mid", context, inputs };
@@ -66,7 +66,7 @@ const rootCommand = commandChained(
         operation(
           {
             options: {},
-            positionals: [positionalRequired({ type: typeString })],
+            positionals: [positionalRequired({ type: type() })],
           },
           async function (context, inputs) {
             return { at: "sub1", context, inputs };
@@ -79,9 +79,9 @@ const rootCommand = commandChained(
           {
             options: {},
             positionals: [
-              positionalRequired({ type: typeNumber }),
-              positionalOptional({ type: typeString, default: () => "42" }),
-              positionalVariadics({ type: typeString }),
+              positionalRequired({ type: typeNumber() }),
+              positionalOptional({ type: type(), default: () => "42" }),
+              positionalVariadics({ type: type() }),
             ],
           },
           async function (context, inputs) {
@@ -96,7 +96,7 @@ const rootCommand = commandChained(
 it("run", async function () {
   expect(
     await executeInterpreted(
-      ["-fn=true", "-fp", "50", "51", "sub1", "final"],
+      ["-fn=TRUE", "-fp", "50", "51", "sub1", "final"],
       "Run Context Input",
       rootCommand,
     ),
@@ -166,8 +166,8 @@ it("run", async function () {
         "88.88",
         "a,b",
         "final",
-        "--no-flag-positive",
-        "--no-flag-negative",
+        "--flag-positive=NO",
+        "--flag-negative=false",
       ],
       "Run Context Input",
       rootCommand,

package/tests/unit.command.usage.ts

@@ -12,9 +12,10 @@ import {
   positionalRequired,
   positionalVariadics,
   ReaderArgs,
+  type,
+  typeChoice,
   typeList,
   typeNumber,
-  typeString,
   typeTuple,
   TypoSupport,
   usageToStyledLines,
@@ -34,6 +35,13 @@ const rootCommand = commandChained<any, any, any>(
   operation(
     {
       options: {
+        choiceOption: optionSingleValue({
+          long: "choice-option",
+          type: typeChoice("choice", ["unset", "empty", "choice1", "choice2"]),
+          description: "choice-option description",
+          defaultWhenNotInlined: () => "empty",
+          defaultWhenNotDefined: () => "unset",
+        }),
         booleanFlag: optionFlag({
           short: "b",
           long: "boolean-flag",
@@ -42,9 +50,8 @@ const rootCommand = commandChained<any, any, any>(
       },
       positionals: [
         positionalRequired({
-          label: "POS-1",
           description: "Required positional number 1",
-          type: typeNumber,
+          type: typeNumber("pos-1"),
         }),
       ],
     },
@@ -73,22 +80,20 @@ const rootCommand = commandChained<any, any, any>(
           stringOption: optionSingleValue({
             short: "s",
             long: "string-option",
-            type: typeString,
-            default: () => undefined,
-            label: "COOL-STUFF",
+            type: type("cool-stuff"),
+            defaultWhenNotDefined: () => undefined,
             description: "string-option description",
           }),
           complexOption: optionRepeatable({
             long: "complex-option",
-            type: typeTuple([typeNumber, typeList(typeString)]),
+            type: typeTuple([typeNumber(), typeList(type("string"))]),
             description: "complex-option description",
           }),
         },
         positionals: [
           positionalRequired({
-            label: "POS-2",
             description: "Required positional number 2",
-            type: typeNumber,
+            type: typeNumber("pos-2"),
           }),
         ],
       },
@@ -122,9 +127,8 @@ const rootCommand = commandChained<any, any, any>(
             options: {},
             positionals: [
               positionalRequired({
-                label: "POS-STRING",
                 description: "Required positional string",
-                type: typeString,
+                type: type("pos-3.1"),
               }),
             ],
           },
@@ -148,7 +152,17 @@ const rootCommand = commandChained<any, any, any>(
                 { positional: "40" },
                 { positional: "41" },
                 { subcommand: "sub2" },
-                { option: { long: "dudu", value: "hello" } },
+                { option: { long: "dudu", inlined: "hello" } },
+                { positional: "50" },
+              ],
+            },
+            {
+              explanation: "Example usage of subcommand 2",
+              commandArgs: [
+                { positional: "40" },
+                { positional: "41" },
+                { subcommand: "sub2" },
+                { option: { long: "dudu", separated: ["hello"] } },
                 { positional: "50" },
               ],
             },
@@ -159,29 +173,26 @@ const rootCommand = commandChained<any, any, any>(
             options: {
               duduValue: optionSingleValue({
                 long: "dudu",
-                type: typeString,
-                default: () => "duduDefault",
+                type: type("dudu-value"),
+                defaultWhenNotDefined: () => "duduDefault",
                 hint: "Dudu option hint",
                 description: "Dudu option description",
               }),
             },
             positionals: [
               positionalRequired({
-                label: "POS-NUMBER",
                 description: "Required positional number",
-                type: typeNumber,
+                type: typeNumber("pos-3.2"),
               }),
               positionalOptional({
-                label: "OPT-POS",
                 description: "Optional positional string",
                 hint: "Optional positional hint",
-                type: typeString,
+                type: type("pos-4"),
                 default: () => "42",
               }),
               positionalVariadics({
-                label: "VARIADIC",
                 description: "Variadic positionals strings",
-                type: typeString,
+                type: type("pos-5"),
               }),
             ],
           },
@@ -210,17 +221,18 @@ it("run", async function () {
   );
 
   const usageRoot = [
-    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<POS-1>}@darkBlue}+ {{[REST]...}@darkBlue}+",
+    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<pos-1>}@darkBlue}+ {{[REST]...}@darkBlue}+",
     "",
     "{Root command description}+",
     "{{Root command details.}-}*",
     "{{Root second line of command details.}-}*",
     "",
     "{{Positionals:}@darkGreen}+",
-    "  {{<POS-1>}@darkBlue}+  Required positional number 1",
+    "  {{<pos-1>}@darkBlue}+  Required positional number 1",
     "",
     "{{Options:}@darkGreen}+",
-    "  {{-b}@darkCyan}+, {{--boolean-flag}@darkCyan}+{{[=no]}-}*  boolean-flag description",
+    "      {{--choice-option}@darkCyan}+ {{<choice>}@darkBlue}+  choice-option description",
+    "  {{-b}@darkCyan}+, {{--boolean-flag}@darkCyan}+{{[=no]}-}*       boolean-flag description",
     "",
     "{{Examples:}@darkGreen}+",
     " {{# Example usage of the root command}-}*",
@@ -228,24 +240,25 @@ it("run", async function () {
     "",
   ];
   const usageMid = [
-    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<POS-1>}@darkBlue}+ {{<POS-2>}@darkBlue}+ {{<SUBCOMMAND>}@darkBlue}+",
+    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<pos-1>}@darkBlue}+ {{<pos-2>}@darkBlue}+ {{<subcommand>}@darkBlue}+",
     "",
     "{Mid command description}+",
     "{{Mid command details.}-}*",
     "{{Mid second line of command details.}-}*",
     "",
     "{{Positionals:}@darkGreen}+",
-    "  {{<POS-1>}@darkBlue}+  Required positional number 1",
-    "  {{<POS-2>}@darkBlue}+  Required positional number 2",
+    "  {{<pos-1>}@darkBlue}+  Required positional number 1",
+    "  {{<pos-2>}@darkBlue}+  Required positional number 2",
     "",
     "{{Subcommands:}@darkGreen}+",
     "  {{sub1}@darkCyan}+  Subcommand 1 description",
     "  {{sub2}@darkCyan}+  Subcommand 2 description {{(Subcommand 2 hint)}-}*",
     "",
     "{{Options:}@darkGreen}+",
+    "      {{--choice-option}@darkCyan}+ {{<choice>}@darkBlue}+                          choice-option description",
     "  {{-b}@darkCyan}+, {{--boolean-flag}@darkCyan}+{{[=no]}-}*                               boolean-flag description",
-    "  {{-s}@darkCyan}+, {{--string-option}@darkCyan}+ {{<COOL-STUFF>}@darkBlue}+                      string-option description",
-    "      {{--complex-option}@darkCyan}+ {{<NUMBER,STRING[,STRING]...>}@darkBlue}+{{ [*]}-}*  complex-option description",
+    "  {{-s}@darkCyan}+, {{--string-option}@darkCyan}+ {{<cool-stuff>}@darkBlue}+                      string-option description",
+    "      {{--complex-option}@darkCyan}+ {{<number,string[,string]...>}@darkBlue}+{{ [*]}-}*  complex-option description",
     "",
     "{{Examples:}@darkGreen}+",
     " {{# Example usage of the mid command}-}*",
@@ -253,21 +266,22 @@ it("run", async function () {
     "",
   ];
   const usageSub1 = [
-    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<POS-1>}@darkBlue}+ {{<POS-2>}@darkBlue}+ {{sub1}@darkCyan}+ {{<POS-STRING>}@darkBlue}+",
+    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<pos-1>}@darkBlue}+ {{<pos-2>}@darkBlue}+ {{sub1}@darkCyan}+ {{<pos-3.1>}@darkBlue}+",
     "",
     "{Subcommand 1 description}+",
     "{{Subcommand 1 details.}-}*",
     "{{Subcommand 1 second line of details.}-}*",
     "",
     "{{Positionals:}@darkGreen}+",
-    "  {{<POS-1>}@darkBlue}+       Required positional number 1",
-    "  {{<POS-2>}@darkBlue}+       Required positional number 2",
-    "  {{<POS-STRING>}@darkBlue}+  Required positional string",
+    "  {{<pos-1>}@darkBlue}+    Required positional number 1",
+    "  {{<pos-2>}@darkBlue}+    Required positional number 2",
+    "  {{<pos-3.1>}@darkBlue}+  Required positional string",
     "",
     "{{Options:}@darkGreen}+",
+    "      {{--choice-option}@darkCyan}+ {{<choice>}@darkBlue}+                          choice-option description",
     "  {{-b}@darkCyan}+, {{--boolean-flag}@darkCyan}+{{[=no]}-}*                               boolean-flag description",
-    "  {{-s}@darkCyan}+, {{--string-option}@darkCyan}+ {{<COOL-STUFF>}@darkBlue}+                      string-option description",
-    "      {{--complex-option}@darkCyan}+ {{<NUMBER,STRING[,STRING]...>}@darkBlue}+{{ [*]}-}*  complex-option description",
+    "  {{-s}@darkCyan}+, {{--string-option}@darkCyan}+ {{<cool-stuff>}@darkBlue}+                      string-option description",
+    "      {{--complex-option}@darkCyan}+ {{<number,string[,string]...>}@darkBlue}+{{ [*]}-}*  complex-option description",
     "",
     "{{Examples:}@darkGreen}+",
     " {{# Example usage of subcommand 1}-}*",
@@ -275,28 +289,31 @@ it("run", async function () {
     "",
   ];
   const usageSub2 = [
-    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<POS-1>}@darkBlue}+ {{<POS-2>}@darkBlue}+ {{sub2}@darkCyan}+ {{<POS-NUMBER>}@darkBlue}+ {{[OPT-POS]}@darkBlue}+ {{[VARIADIC]...}@darkBlue}+",
+    "{{Usage:}@darkMagenta}+ {{my-cli}@darkCyan}+ {{<pos-1>}@darkBlue}+ {{<pos-2>}@darkBlue}+ {{sub2}@darkCyan}+ {{<pos-3.2>}@darkBlue}+ {{[pos-4]}@darkBlue}+ {{[pos-5]...}@darkBlue}+",
     "",
     "{Subcommand 2 description}+ {{(Subcommand 2 hint)}-}*",
     "{{Subcommand 2 details.}-}*",
     "{{Subcommand 2 second line of details.}-}*",
     "",
     "{{Positionals:}@darkGreen}+",
-    "  {{<POS-1>}@darkBlue}+        Required positional number 1",
-    "  {{<POS-2>}@darkBlue}+        Required positional number 2",
-    "  {{<POS-NUMBER>}@darkBlue}+   Required positional number",
-    "  {{[OPT-POS]}@darkBlue}+      Optional positional string {{(Optional positional hint)}-}*",
-    "  {{[VARIADIC]...}@darkBlue}+  Variadic positionals strings",
+    "  {{<pos-1>}@darkBlue}+     Required positional number 1",
+    "  {{<pos-2>}@darkBlue}+     Required positional number 2",
+    "  {{<pos-3.2>}@darkBlue}+   Required positional number",
+    "  {{[pos-4]}@darkBlue}+     Optional positional string {{(Optional positional hint)}-}*",
+    "  {{[pos-5]...}@darkBlue}+  Variadic positionals strings",
     "",
     "{{Options:}@darkGreen}+",
+    "      {{--choice-option}@darkCyan}+ {{<choice>}@darkBlue}+                          choice-option description",
     "  {{-b}@darkCyan}+, {{--boolean-flag}@darkCyan}+{{[=no]}-}*                               boolean-flag description",
-    "  {{-s}@darkCyan}+, {{--string-option}@darkCyan}+ {{<COOL-STUFF>}@darkBlue}+                      string-option description",
-    "      {{--complex-option}@darkCyan}+ {{<NUMBER,STRING[,STRING]...>}@darkBlue}+{{ [*]}-}*  complex-option description",
-    "      {{--dudu}@darkCyan}+ {{<STRING>}@darkBlue}+                                   Dudu option description {{(Dudu option hint)}-}*",
+    "  {{-s}@darkCyan}+, {{--string-option}@darkCyan}+ {{<cool-stuff>}@darkBlue}+                      string-option description",
+    "      {{--complex-option}@darkCyan}+ {{<number,string[,string]...>}@darkBlue}+{{ [*]}-}*  complex-option description",
+    "      {{--dudu}@darkCyan}+ {{<dudu-value>}@darkBlue}+                               Dudu option description {{(Dudu option hint)}-}*",
     "",
     "{{Examples:}@darkGreen}+",
     " {{# Example usage of subcommand 2}-}*",
     " {{my-cli}@darkCyan}+ {{40}@darkBlue}+ {{41}@darkBlue}+ {{sub2}@darkCyan}+ {{--dudu}@darkCyan}+{{=}-}*{{hello}@darkBlue}+ {{50}@darkBlue}+",
+    " {{# Example usage of subcommand 2}-}*",
+    " {{my-cli}@darkCyan}+ {{40}@darkBlue}+ {{41}@darkBlue}+ {{sub2}@darkCyan}+ {{--dudu}@darkCyan}+ {{hello}@darkBlue}+ {{50}@darkBlue}+",
     "",
   ];
 
@@ -325,17 +342,6 @@ async function getUsage<Context, Result>(
 ) {
   const readerArgs = new ReaderArgs(args);
   const commandDecoder = command.consumeAndMakeDecoder(readerArgs);
-  /*
-  try {
-    const interpreter = commandDecoder.decodeAndMakeInterpreter();
-    const result = await interpreter.executeWithContext(
-      "" as unknown as Context,
-    );
-    console.log(result);
-  } catch (error) {
-    console.log(TypoSupport.tty().computeStyledErrorMessage(error));
-  }
-    */
   return usageToStyledLines({
     cliName: "my-cli",
     usage: commandDecoder.generateUsage(),