cli-kiss 0.2.3 → 0.2.5

package/src/lib/Usage.ts

@@ -1,4 +1,4 @@
-import { CommandUsage } from "./Command";
+import { CommandInformation } from "./Command";
 import {
   TypoGrid,
   TypoString,
@@ -13,7 +13,99 @@ import {
 } from "./Typo";
 
 /**
- * Converts a {@link CommandUsage} model into an array of styled lines ready to be
+ * Usage model. Produced by {@link CommandDecoder.generateUsage}, consumed by {@link usageToStyledLines}.
+ */
+export type UsageCommand = {
+  /**
+   * Segments of the usage line
+   */
+  segments: Array<{ positional: string } | { subcommand: string }>;
+  /**
+   * Command metadata.
+   */
+  information: CommandInformation;
+  /**
+   * Positionals in declaration order.
+   */
+  positionals: Array<UsagePositional>;
+  /**
+   * Subcommands, populated when none was selected.
+   */
+  subcommands: Array<UsageSubcommand>;
+  /**
+   * Options in registration order.
+   */
+  options: Array<UsageOption>;
+};
+
+/**
+ * Positional metadata for the `Positionals:` section of help.
+ */
+export type UsagePositional = {
+  /**
+   * Help text.
+   */
+  description?: string | undefined;
+  /**
+   * Short note shown in parentheses.
+   */
+  hint?: string | undefined;
+  /**
+   * Placeholder label shown in the usage line and the `Positionals:` section.
+   */
+  label: string;
+};
+
+/**
+ * Entry in the `Subcommands:` section.
+ */
+export type UsageSubcommand = {
+  /**
+   * Token the user types (e.g. `"deploy"`).
+   */
+  name: string;
+  /**
+   * From {@link CommandInformation.description}.
+   */
+  description?: string | undefined;
+  /**
+   * From {@link CommandInformation.hint}.
+   */
+  hint?: string | undefined;
+};
+
+/**
+ * Option metadata for the `Options:` section of help.
+ */
+export type UsageOption = {
+  /**
+   * Short-form name without `-` (e.g. `"v"`).
+   */
+  short?: string | undefined;
+  /**
+   * Long-form name without `--` (e.g. `"verbose"`).
+   */
+  long: string;
+  /**
+   * Value placeholder in help (e.g. `"<FILE>"`).
+   */
+  label?: string | undefined;
+  /**
+   * Extra annotation appended to the option label in help.
+   */
+  annotation?: string | undefined;
+  /**
+   * Help text.
+   */
+  description?: string | undefined;
+  /**
+   * Short note shown in parentheses.
+   */
+  hint?: string | undefined;
+};
+
+/**
+ * Converts a {@link UsageCommand} model into an array of styled lines ready to be
  * joined with `"\n"` and printed to the terminal.
  *
  * The output format is:
@@ -30,7 +122,7 @@ import {
  *   <name>  <description> (<hint>)
  *
  * Options:
- *   -s, --long <LABEL>  <description> (<hint>)
+ *   -s, --long <LABEL><annotation>  <description> (<hint>)
  *
  * Examples:
  *   <description>
@@ -39,102 +131,94 @@ import {
  * ```
  * Sections that have no entries are omitted. The trailing empty line is always included.
  *
- * Column alignment within each section is handled by {@link TypoGrid}: the widest entry
- * in each column sets the width for the entire section.
+ * Column alignment per section via {@link TypoGrid}.
  *
  * @param params.cliName - Program name for the usage line.
- * @param params.commandUsage - From {@link CommandDecoder.generateUsage}.
+ * @param params.usage - From {@link CommandDecoder.generateUsage}.
  * @param params.typoSupport - Rendering mode.
- * @returns One string per output line; trailing empty string for the blank line at the end.
+ * @returns Styled lines; includes a trailing empty string.
  *
  * @example
  * ```ts
  * const lines = usageToStyledLines({
  *   cliName: "my-cli",
- *   commandUsage: commandDecoder.generateUsage(),
+ *   usage: commandDecoder.generateUsage(),
  *   typoSupport: TypoSupport.tty(),
  * });
  * process.stdout.write(lines.join("\n"));
  * ```
  */
 export function usageToStyledLines(params: {
-  cliName: Lowercase<string>;
-  commandUsage: CommandUsage;
+  cliName: string;
+  usage: UsageCommand;
   typoSupport: TypoSupport;
 }) {
-  const { cliName, commandUsage, typoSupport } = params;
+  const { cliName, usage, typoSupport } = params;
 
   const lines = new Array<string>();
 
-  const segments = [
-    textUsageHero("Usage:").computeStyledString(typoSupport),
-    textConstants(cliName).computeStyledString(typoSupport),
-  ].concat(
-    commandUsage.segments.map((segment) => {
-      if ("positional" in segment) {
-        return textUserInput(segment.positional).computeStyledString(
-          typoSupport,
-        );
-      }
-      if ("command" in segment) {
-        return textConstants(segment.command).computeStyledString(typoSupport);
-      }
-      throw new Error(`Unknown segment: ${JSON.stringify(segment)}`);
-    }),
-  );
-  lines.push(segments.join(" "));
+  const segmentsText = new TypoText();
+  segmentsText.push(textUsageHero("Usage:"));
+  segmentsText.push(textDelimiter(" "));
+  segmentsText.push(textConstants(cliName));
+  for (const segment of usage.segments) {
+    segmentsText.push(textDelimiter(" "));
+    if ("positional" in segment) {
+      segmentsText.push(textUserInput(segment.positional));
+    }
+    if ("subcommand" in segment) {
+      segmentsText.push(textConstants(segment.subcommand));
+    }
+  }
+  lines.push(segmentsText.computeStyledString(typoSupport));
 
   lines.push("");
   const introText = new TypoText();
-  introText.pushString(textUsageText(commandUsage.information.description));
-  if (commandUsage.information.hint) {
-    introText.pushString(textDelimiter(" "));
-    introText.pushString(textSubtleInfo(`(${commandUsage.information.hint})`));
+  introText.push(textUsageText(usage.information.description));
+  if (usage.information.hint) {
+    introText.push(textDelimiter(" "));
+    introText.push(textSubtleInfo(`(${usage.information.hint})`));
   }
   lines.push(introText.computeStyledString(typoSupport));
-  for (const detail of commandUsage.information.details ?? []) {
+  for (const detail of usage.information.details ?? []) {
     const detailText = new TypoText();
-    detailText.pushString(textSubtleInfo(detail));
+    detailText.push(textSubtleInfo(detail));
     lines.push(detailText.computeStyledString(typoSupport));
   }
 
-  if (commandUsage.positionals.length > 0) {
+  if (usage.positionals.length > 0) {
     lines.push("");
     lines.push(textBlockTitle("Positionals:").computeStyledString(typoSupport));
     const typoGrid = new TypoGrid();
-    for (const positionalUsage of commandUsage.positionals) {
+    for (const positionalUsage of usage.positionals) {
       const typoGridRow = new Array<TypoText>();
       typoGridRow.push(new TypoText(textDelimiter("  ")));
       typoGridRow.push(new TypoText(textUserInput(positionalUsage.label)));
       typoGridRow.push(...createInformationals(positionalUsage));
       typoGrid.pushRow(typoGridRow);
     }
-    lines.push(
-      ...typoGrid.computeStyledGrid(typoSupport).map((row) => row.join("")),
-    );
+    lines.push(...typoGrid.computeStyledLines(typoSupport));
   }
 
-  if (commandUsage.subcommands.length > 0) {
+  if (usage.subcommands.length > 0) {
     lines.push("");
     lines.push(textBlockTitle("Subcommands:").computeStyledString(typoSupport));
     const typoGrid = new TypoGrid();
-    for (const subcommandUsage of commandUsage.subcommands) {
+    for (const subcommandUsage of usage.subcommands) {
       const typoGridRow = new Array<TypoText>();
       typoGridRow.push(new TypoText(textDelimiter("  ")));
       typoGridRow.push(new TypoText(textConstants(subcommandUsage.name)));
       typoGridRow.push(...createInformationals(subcommandUsage));
       typoGrid.pushRow(typoGridRow);
     }
-    lines.push(
-      ...typoGrid.computeStyledGrid(typoSupport).map((row) => row.join("")),
-    );
+    lines.push(...typoGrid.computeStyledLines(typoSupport));
   }
 
-  if (commandUsage.options.length > 0) {
+  if (usage.options.length > 0) {
     lines.push("");
     lines.push(textBlockTitle("Options:").computeStyledString(typoSupport));
     const typoGrid = new TypoGrid();
-    for (const optionUsage of commandUsage.options) {
+    for (const optionUsage of usage.options) {
       const typoGridRow = new Array<TypoText>();
       typoGridRow.push(new TypoText(textDelimiter("  ")));
       if (optionUsage.short) {
@@ -147,61 +231,58 @@ export function usageToStyledLines(params: {
       } else {
         typoGridRow.push(new TypoText());
       }
+      const longOptionText = new TypoText(
+        textConstants(`--${optionUsage.long}`),
+      );
       if (optionUsage.label) {
-        typoGridRow.push(
-          new TypoText(
-            textConstants(`--${optionUsage.long}`),
-            textDelimiter(" "),
-            textUserInput(optionUsage.label),
-          ),
-        );
-      } else {
-        typoGridRow.push(
-          new TypoText(
-            textConstants(`--${optionUsage.long}`),
-            textSubtleInfo("[=no]"),
-          ),
-        );
+        longOptionText.push(textDelimiter(" "));
+        longOptionText.push(textUserInput(optionUsage.label));
       }
+      if (optionUsage.annotation) {
+        longOptionText.push(textSubtleInfo(optionUsage.annotation));
+      }
+      typoGridRow.push(longOptionText);
       typoGridRow.push(...createInformationals(optionUsage));
       typoGrid.pushRow(typoGridRow);
     }
-    lines.push(
-      ...typoGrid.computeStyledGrid(typoSupport).map((row) => row.join("")),
-    );
+    lines.push(...typoGrid.computeStyledLines(typoSupport));
   }
 
-  if (commandUsage.information.examples) {
+  if (usage.information.examples) {
     lines.push("");
     lines.push(textBlockTitle("Examples:").computeStyledString(typoSupport));
-    for (const example of commandUsage.information.examples) {
+    for (const example of usage.information.examples) {
       const exampleExplanationText = new TypoText();
-      exampleExplanationText.pushString(textDelimiter(" "));
-      exampleExplanationText.pushString(
-        textSubtleInfo(`# ${example.explanation}`),
-      );
+      exampleExplanationText.push(textDelimiter(" "));
+      exampleExplanationText.push(textSubtleInfo(`# ${example.explanation}`));
       lines.push(exampleExplanationText.computeStyledString(typoSupport));
       const commandLineText = new TypoText();
-      commandLineText.pushString(textDelimiter(" "));
-      commandLineText.pushString(textConstants(cliName));
+      commandLineText.push(textDelimiter(" "));
+      commandLineText.push(textConstants(cliName));
       for (const commandArg of example.commandArgs) {
-        commandLineText.pushString(textDelimiter(" "));
+        commandLineText.push(textDelimiter(" "));
         if (typeof commandArg === "string") {
-          commandLineText.pushString(commandArg);
+          commandLineText.push(commandArg);
         } else if ("positional" in commandArg) {
-          commandLineText.pushString(textUserInput(commandArg.positional));
+          commandLineText.push(textUserInput(commandArg.positional));
         } else if ("subcommand" in commandArg) {
-          commandLineText.pushString(textConstants(commandArg.subcommand));
+          commandLineText.push(textConstants(commandArg.subcommand));
         } else if ("option" in commandArg) {
           const option = commandArg.option;
           if ("short" in option) {
-            commandLineText.pushString(textConstants(`-${option.short}`));
+            commandLineText.push(textConstants(`-${option.short}`));
           } else {
-            commandLineText.pushString(textConstants(`--${option.long}`));
+            commandLineText.push(textConstants(`--${option.long}`));
+          }
+          if (option.inlined !== undefined) {
+            commandLineText.push(textSubtleInfo("="));
+            commandLineText.push(textUserInput(option.inlined));
           }
-          if (option.value !== undefined) {
-            commandLineText.pushString(textSubtleInfo("="));
-            commandLineText.pushString(textUserInput(option.value));
+          if (option.separated !== undefined) {
+            for (const separatedValue of option.separated) {
+              commandLineText.push(textDelimiter(" "));
+              commandLineText.push(textUserInput(separatedValue));
+            }
           }
         }
       }
@@ -214,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.aliases.ts

@@ -1,7 +1,7 @@
 import { expect, it } from "@jest/globals";
-import { ReaderArgs } from "../src";
+import { ReaderArgs, ReaderOptionParsing } from "../src";
 
-it("run", async () => {
+it("run", async function () {
   const readerArgs = new ReaderArgs([
     "--option=1.1",
     "--option-alias1=1.2",
@@ -10,7 +10,7 @@ it("run", async () => {
     "-pts=1.4",
     "-o",
     "1.5",
-    "--flag-alias",
+    "--flag1-alias",
     "-fa2=woops",
     "-fa2o=1.6",
   ]);
@@ -18,29 +18,45 @@ it("run", async () => {
   const kOption = readerArgs.registerOption({
     longs: ["option", "option-alias1", "option-alias2"],
     shorts: ["pts", "o"],
-    valued: true,
+    parsing: optionValueFixedUniqueParsing,
   });
   const kFlag1 = readerArgs.registerOption({
-    longs: ["flag1", "flag-alias"],
+    longs: ["flag1", "flag1-alias"],
     shorts: [],
-    valued: false,
+    parsing: optionFlagParsing,
   });
   const kFlag2 = readerArgs.registerOption({
     longs: ["flag2"],
     shorts: ["fa2"],
-    valued: false,
+    parsing: optionFlagParsing,
   });
 
   expect(readerArgs.consumePositional()).toStrictEqual(undefined);
 
   expect(readerArgs.getOptionValues(kOption)).toStrictEqual([
-    "1.1",
-    "1.2",
-    "1.3",
-    "1.4",
-    "1.5",
-    "1.6",
+    { inlined: "1.1", separated: [] },
+    { inlined: "1.2", separated: [] },
+    { inlined: null, separated: ["1.3"] },
+    { inlined: "1.4", separated: [] },
+    { inlined: null, separated: ["1.5"] },
+    { inlined: "1.6", separated: [] },
+  ]);
+  expect(readerArgs.getOptionValues(kFlag1)).toStrictEqual([
+    { inlined: null, separated: [] },
+  ]);
+  expect(readerArgs.getOptionValues(kFlag2)).toStrictEqual([
+    { inlined: "woops", separated: [] },
+    { inlined: null, separated: [] },
   ]);
-  expect(readerArgs.getOptionValues(kFlag1)).toStrictEqual(["true"]);
-  expect(readerArgs.getOptionValues(kFlag2)).toStrictEqual(["woops", "true"]);
 });
+
+const optionFlagParsing: ReaderOptionParsing = {
+  consumeShortGroup: false,
+  consumeNextArg: () => false,
+};
+
+const optionValueFixedUniqueParsing: ReaderOptionParsing = {
+  consumeShortGroup: true,
+  consumeNextArg: (inlined, separated) =>
+    inlined === null && separated.length === 0,
+};

package/tests/unit.Reader.commons.ts

@@ -1,9 +1,10 @@
 import { expect, it } from "@jest/globals";
-import { ReaderArgs } from "../src";
+import { ReaderArgs, ReaderOptionParsing } from "../src";
 
-it("run", async () => {
+it("run", async function () {
   const stream = new ReaderArgs([
     "positional-0",
+    "--no-flag-no",
     "--flag-normal",
     "--flag-positive=true",
     "--flag-negative=false",
@@ -12,7 +13,8 @@ it("run", async () => {
     "1.1",
     "--option-split",
     "1.2",
-    "--option-join=2",
+    "--option-join=2.1",
+    "--option-join=2.2",
     "-ab",
     "3.1",
     "-cd=4.1",
@@ -34,76 +36,81 @@ it("run", async () => {
 
   expect(stream.consumePositional()).toStrictEqual("positional-0");
 
+  const kFlagUnset = stream.registerOption({
+    longs: ["flag-unset"],
+    shorts: [],
+    parsing: optionFlagParsing,
+  });
+  const kFlagNo = stream.registerOption({
+    longs: ["no-flag-no"],
+    shorts: [],
+    parsing: optionFlagParsing,
+  });
   const kFlagNormal = stream.registerOption({
     longs: ["flag-normal"],
     shorts: [],
-    valued: false,
+    parsing: optionFlagParsing,
   });
   const kFlagPositive = stream.registerOption({
     longs: ["flag-positive"],
     shorts: [],
-    valued: false,
+    parsing: optionFlagParsing,
   });
   const kFlagNegative = stream.registerOption({
     longs: ["flag-negative"],
     shorts: [],
-    valued: false,
-  });
-  const kFlagUnset = stream.registerOption({
-    longs: ["flag-unset"],
-    shorts: [],
-    valued: false,
+    parsing: optionFlagParsing,
   });
 
   expect(stream.consumePositional()).toStrictEqual("positional-1");
 
+  const kOptionUnset = stream.registerOption({
+    longs: ["option-unset"],
+    shorts: [],
+    parsing: optionValueFixedUniqueParsing,
+  });
   const kOptionSplit = stream.registerOption({
     longs: ["option-split"],
     shorts: [],
-    valued: true,
+    parsing: optionValueFixedUniqueParsing,
   });
   const kOptionJoin = stream.registerOption({
     longs: ["option-join"],
     shorts: [],
-    valued: true,
-  });
-  const kOptionUnset = stream.registerOption({
-    longs: ["option-unset"],
-    shorts: [],
-    valued: true,
+    parsing: optionValueFixedUniqueParsing,
   });
 
   const kA = stream.registerOption({
     longs: [],
     shorts: ["a"],
-    valued: false,
+    parsing: optionFlagParsing,
   });
   const kB = stream.registerOption({
     longs: [],
     shorts: ["b"],
-    valued: true,
+    parsing: optionValueFixedUniqueParsing,
   });
 
   const kC = stream.registerOption({
     longs: [],
     shorts: ["c"],
-    valued: false,
+    parsing: optionFlagParsing,
   });
   const kD = stream.registerOption({
     longs: [],
     shorts: ["d"],
-    valued: true,
+    parsing: optionValueFixedUniqueParsing,
   });
 
   const kE = stream.registerOption({
     longs: [],
     shorts: ["e"],
-    valued: false,
+    parsing: optionFlagParsing,
   });
   const kF = stream.registerOption({
     longs: [],
     shorts: ["f"],
-    valued: true,
+    parsing: optionValueFixedUniqueParsing,
   });
 
   expect(stream.consumePositional()).toStrictEqual("positional-2");
@@ -111,23 +118,23 @@ it("run", async () => {
   const kG = stream.registerOption({
     longs: [],
     shorts: ["g"],
-    valued: false,
+    parsing: optionFlagParsing,
   });
   const kH = stream.registerOption({
     longs: [],
     shorts: ["h"],
-    valued: false,
+    parsing: optionFlagParsing,
   });
 
   const kI = stream.registerOption({
     longs: [],
     shorts: ["i"],
-    valued: false,
+    parsing: optionFlagParsing,
   });
   const kJ = stream.registerOption({
     longs: [],
     shorts: ["j"],
-    valued: false,
+    parsing: optionFlagParsing,
   });
 
   expect(stream.consumePositional()).toStrictEqual("positional-3");
@@ -138,27 +145,76 @@ it("run", async () => {
   expect(stream.consumePositional()).toStrictEqual("positional-4");
   expect(stream.consumePositional()).toStrictEqual(undefined);
 
-  expect(stream.getOptionValues(kFlagNormal)).toStrictEqual(["true"]);
-  expect(stream.getOptionValues(kFlagPositive)).toStrictEqual(["true"]);
-  expect(stream.getOptionValues(kFlagNegative)).toStrictEqual(["false"]);
   expect(stream.getOptionValues(kFlagUnset)).toStrictEqual([]);
+  expect(stream.getOptionValues(kFlagNo)).toStrictEqual([
+    { inlined: null, separated: [] },
+  ]);
+  expect(stream.getOptionValues(kFlagNormal)).toStrictEqual([
+    { inlined: null, separated: [] },
+  ]);
+  expect(stream.getOptionValues(kFlagPositive)).toStrictEqual([
+    { inlined: "true", separated: [] },
+  ]);
+  expect(stream.getOptionValues(kFlagNegative)).toStrictEqual([
+    { inlined: "false", separated: [] },
+  ]);
 
   expect(stream.getOptionValues(kOptionUnset)).toStrictEqual([]);
-  expect(stream.getOptionValues(kOptionSplit)).toStrictEqual(["1.1", "1.2"]);
-  expect(stream.getOptionValues(kOptionJoin)).toStrictEqual(["2"]);
+  expect(stream.getOptionValues(kOptionSplit)).toStrictEqual([
+    { inlined: null, separated: ["1.1"] },
+    { inlined: null, separated: ["1.2"] },
+  ]);
+  expect(stream.getOptionValues(kOptionJoin)).toStrictEqual([
+    { inlined: "2.1", separated: [] },
+    { inlined: "2.2", separated: [] },
+  ]);
 
-  expect(stream.getOptionValues(kA)).toStrictEqual(["true"]);
-  expect(stream.getOptionValues(kB)).toStrictEqual(["3.1", "3.2"]);
+  expect(stream.getOptionValues(kA)).toStrictEqual([
+    { inlined: null, separated: [] },
+  ]);
+  expect(stream.getOptionValues(kB)).toStrictEqual([
+    { inlined: null, separated: ["3.1"] },
+    { inlined: null, separated: ["3.2"] },
+  ]);
 
-  expect(stream.getOptionValues(kC)).toStrictEqual(["true"]);
-  expect(stream.getOptionValues(kD)).toStrictEqual(["4.1", "4.2"]);
+  expect(stream.getOptionValues(kC)).toStrictEqual([
+    { inlined: null, separated: [] },
+  ]);
+  expect(stream.getOptionValues(kD)).toStrictEqual([
+    { inlined: "4.1", separated: [] },
+    { inlined: "4.2", separated: [] },
+  ]);
 
-  expect(stream.getOptionValues(kE)).toStrictEqual(["true"]);
-  expect(stream.getOptionValues(kF)).toStrictEqual(["5.1", "5.2"]);
+  expect(stream.getOptionValues(kE)).toStrictEqual([
+    { inlined: null, separated: [] },
+  ]);
+  expect(stream.getOptionValues(kF)).toStrictEqual([
+    { inlined: "5.1", separated: [] },
+    { inlined: "5.2", separated: [] },
+  ]);
 
-  expect(stream.getOptionValues(kG)).toStrictEqual(["true"]);
-  expect(stream.getOptionValues(kH)).toStrictEqual(["FALSE"]);
+  expect(stream.getOptionValues(kG)).toStrictEqual([
+    { inlined: null, separated: [] },
+  ]);
+  expect(stream.getOptionValues(kH)).toStrictEqual([
+    { inlined: "FALSE", separated: [] },
+  ]);
 
-  expect(stream.getOptionValues(kI)).toStrictEqual(["true"]);
-  expect(stream.getOptionValues(kJ)).toStrictEqual(["TRUE"]);
+  expect(stream.getOptionValues(kI)).toStrictEqual([
+    { inlined: null, separated: [] },
+  ]);
+  expect(stream.getOptionValues(kJ)).toStrictEqual([
+    { inlined: "TRUE", separated: [] },
+  ]);
 });
+
+const optionFlagParsing: ReaderOptionParsing = {
+  consumeShortGroup: false,
+  consumeNextArg: () => false,
+};
+
+const optionValueFixedUniqueParsing: ReaderOptionParsing = {
+  consumeShortGroup: true,
+  consumeNextArg: (inlined, separated) =>
+    inlined === null && separated.length === 0,
+};