cli-kiss 0.2.2 → 0.2.4

package/src/lib/Usage.ts

@@ -1,4 +1,4 @@
-import { CommandUsage } from "./Command";
+import { CommandInformation } from "./Command";
 import {
   TypoGrid,
   TypoString,
@@ -13,12 +13,125 @@ 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
+   * (e.g. `my-cli <POSITIONAL> subcommand <ANOTHER_POSITIONAL>`).
+   */
+  segments: Array<UsageSegment>;
+  /**
+   * 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>;
+};
+
+/**
+ * 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.
+ */
+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.
+   * Required: `<NAME>`, optional: `[NAME]`, variadic: `[NAME]...`.
+   */
+  label: Uppercase<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: Lowercase<string>;
+  /**
+   * Extra annotation appended to the option label in help (e.g. `[=no]`, ` [*]`).
+   */
+  annotation: string | undefined;
+  /**
+   * Help text.
+   */
+  description: string | undefined;
+  /**
+   * Short note shown in parentheses.
+   */
+  hint: string | undefined;
+  /**
+   * Value placeholder in help (e.g. `"<FILE>"`). `undefined` for flags.
+   */
+  label: Uppercase<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:
  * ```
- * Usage: <cliName> [breadcrumbs...]
+ * Usage: <cliName> [segments...]
  *
  * <description> (<hint>)
  * <detail lines...>
@@ -30,25 +143,27 @@ import {
  *   <name>  <description> (<hint>)
  *
  * Options:
- *   -s, --long <LABEL>  <description> (<hint>)
+ *   -s, --long <LABEL><annotation>  <description> (<hint>)
+ *
+ * Examples:
+ *   <description>
+ *   <command line>
  *
  * ```
  * 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 - The CLI program name shown at the start of the usage line.
- * @param params.commandUsage - The usage model produced by {@link CommandFactory.generateUsage}.
- * @param params.typoSupport - Controls color/styling of the output.
- * @returns An ordered array of strings, one per output line (including a trailing
- *   empty string for the blank line at the end).
+ * @param params.cliName - Program name for the usage line.
+ * @param params.usage - From {@link CommandDecoder.generateUsage}.
+ * @param params.typoSupport - Rendering mode.
+ * @returns Styled lines; includes a trailing empty string.
  *
  * @example
  * ```ts
  * const lines = usageToStyledLines({
  *   cliName: "my-cli",
- *   commandUsage: commandFactory.generateUsage(),
+ *   usage: commandDecoder.generateUsage(),
  *   typoSupport: TypoSupport.tty(),
  * });
  * process.stdout.write(lines.join("\n"));
@@ -56,85 +171,75 @@ import {
  */
 export function usageToStyledLines(params: {
   cliName: Lowercase<string>;
-  commandUsage: CommandUsage;
+  usage: UsageCommand;
   typoSupport: TypoSupport;
 }) {
-  const { cliName, commandUsage, typoSupport } = params;
+  const { cliName, usage, typoSupport } = params;
 
   const lines = new Array<string>();
 
-  const breadcrumbs = [
-    textUsageHero("Usage:").computeStyledString(typoSupport),
-    textConstants(cliName).computeStyledString(typoSupport),
-  ].concat(
-    commandUsage.breadcrumbs.map((breadcrumb) => {
-      if ("positional" in breadcrumb) {
-        return textUserInput(breadcrumb.positional).computeStyledString(
-          typoSupport,
-        );
-      }
-      if ("command" in breadcrumb) {
-        return textConstants(breadcrumb.command).computeStyledString(
-          typoSupport,
-        );
-      }
-      throw new Error(`Unknown breadcrumb: ${JSON.stringify(breadcrumb)}`);
-    }),
-  );
-  lines.push(breadcrumbs.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,28 +252,57 @@ 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 (usage.information.examples) {
+    lines.push("");
+    lines.push(textBlockTitle("Examples:").computeStyledString(typoSupport));
+    for (const example of usage.information.examples) {
+      const exampleExplanationText = new TypoText();
+      exampleExplanationText.push(textDelimiter(" "));
+      exampleExplanationText.push(textSubtleInfo(`# ${example.explanation}`));
+      lines.push(exampleExplanationText.computeStyledString(typoSupport));
+      const commandLineText = new TypoText();
+      commandLineText.push(textDelimiter(" "));
+      commandLineText.push(textConstants(cliName));
+      for (const commandArg of example.commandArgs) {
+        commandLineText.push(textDelimiter(" "));
+        if (typeof commandArg === "string") {
+          commandLineText.push(commandArg);
+        } else if ("positional" in commandArg) {
+          commandLineText.push(textUserInput(commandArg.positional));
+        } else if ("subcommand" in commandArg) {
+          commandLineText.push(textConstants(commandArg.subcommand));
+        } else if ("option" in commandArg) {
+          const option = commandArg.option;
+          if ("short" in option) {
+            commandLineText.push(textConstants(`-${option.short}`));
+          } else {
+            commandLineText.push(textConstants(`--${option.long}`));
+          }
+          if (option.value !== undefined) {
+            commandLineText.push(textSubtleInfo("="));
+            commandLineText.push(textUserInput(option.value));
+          }
+        }
+      }
+      lines.push(commandLineText.computeStyledString(typoSupport));
+    }
   }
 
   lines.push("");

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,
+};