cli-kiss 0.2.7 → 0.2.9

package/src/lib/Typo.ts

@@ -1,5 +1,3 @@
-import { typeBooleanValuesFalse } from "./Type";
-
 /**
  * Color names for terminal styling, used by {@link TypoStyle}.
  * `dark*` = standard ANSI (30–37); `bright*` = high-intensity (90–97).
@@ -125,14 +123,14 @@ export const typoStyleRegularWeaker: TypoStyle = {
  */
 export class TypoString {
   #value: string;
-  #typoStyle: TypoStyle | undefined;
+  #style: TypoStyle | undefined;
   /**
    * @param value - Raw text content.
-   * @param typoStyle - Style to apply when rendering. Defaults to `undefined` (no style).
+   * @param style - Style to apply when rendering.
    */
-  constructor(value: string, typoStyle?: TypoStyle) {
+  constructor(value: string, style?: TypoStyle) {
     this.#value = value;
-    this.#typoStyle = typoStyle;
+    this.#style = style;
   }
   /**
    * Returns the text styled by `typoSupport`.
@@ -140,51 +138,75 @@ export class TypoString {
    * @param typoSupport - Rendering mode.
    */
   computeStyledString(typoSupport: TypoSupport): string {
-    return typoSupport.computeStyledString(this.#value, this.#typoStyle);
+    return typoSupport.computeStyledString(this.#value, this.#style);
   }
   /**
    * Returns the raw text.
    */
   getRawString(): string {
+    // TODO - should there be a global config or smthg instead of passing support everywhere?
     return this.#value;
   }
+  /**
+   * Predefined ellipsis segment with subtle styling.
+   */
+  static elipsis = new TypoString("...", typoStyleRegularWeaker);
 }
 
 /**
  * A segment of styled text, a string, or an array of segments.
  */
-export type TypoSegment = TypoText | TypoString | string | Array<TypoSegment>;
+export type TypoSegment = TypoText | TypoString | Array<TypoSegment>;
 
 /**
  * Mutable sequence of {@link TypoString} segments.
  */
 export class TypoText {
-  #typoStrings: Array<TypoString>;
+  #strings: Array<TypoString>;
   /**
    * @param segments - Initial text segments
    */
-  constructor(...segments: TypoSegment[]) {
-    this.#typoStrings = [];
+  constructor(...segments: Array<TypoSegment>) {
+    this.#strings = [];
     for (const segment of segments) {
       this.push(segment);
     }
   }
   /**
    * Appends new text segment(s).
-   *
-   * @param segment - Text segment(s) to append.
    */
-  push(segment: TypoSegment) {
-    if (typeof segment === "string") {
-      this.#typoStrings.push(new TypoString(segment));
-    } else if (segment instanceof TypoText) {
-      this.#typoStrings.push(...segment.#typoStrings);
-    } else if (Array.isArray(segment)) {
-      for (const typoString of segment) {
-        this.push(typoString);
+  push(...segments: Array<TypoSegment>): void {
+    for (const segment of segments) {
+      if (typeof segment === "string") {
+        this.#strings.push(new TypoString(segment));
+      } else if (segment instanceof TypoString) {
+        this.#strings.push(segment);
+      } else if (segment instanceof TypoText) {
+        this.#strings.push(...segment.#strings);
+      } else if (Array.isArray(segment)) {
+        for (const part of segment) {
+          this.push(part);
+        }
+      }
+    }
+  }
+  /**
+   * Appends separated segments, optionally truncating with an ellipsis.
+   */
+  pushJoined(
+    segments: Array<TypoSegment>,
+    separator: TypoSegment,
+    ellipsisLimit: number,
+  ): void {
+    for (let index = 0; index < segments.length; index++) {
+      if (index > 0) {
+        this.push(separator);
+      }
+      if (ellipsisLimit !== undefined && index >= ellipsisLimit) {
+        this.push(TypoString.elipsis);
+        break;
       }
-    } else {
-      this.#typoStrings.push(segment);
+      this.push(segments[index]!);
     }
   }
   /**
@@ -194,7 +216,7 @@ export class TypoText {
    * @returns Concatenated styled string.
    */
   computeStyledString(typoSupport: TypoSupport): string {
-    return this.#typoStrings
+    return this.#strings
       .map((t) => t.computeStyledString(typoSupport))
       .join("");
   }
@@ -202,32 +224,18 @@ export class TypoText {
    * Returns the concatenated raw text.
    */
   computeRawString(): string {
-    return this.#typoStrings.map((t) => t.getRawString()).join("");
+    return this.#strings.map((t) => t.getRawString()).join("");
   }
   /**
    * Returns the total raw character count.
    */
   computeRawLength(): number {
     let length = 0;
-    for (const typoString of this.#typoStrings) {
+    for (const typoString of this.#strings) {
       length += typoString.getRawString().length;
     }
     return length;
   }
-  /**
-   * Joins multiple segments with a separator.
-   * @returns A new {@link TypoText} containing the joined segments.
-   */
-  static join(segments: Array<TypoSegment>, separator: TypoSegment): TypoText {
-    const result = new TypoText();
-    for (let index = 0; index < segments.length; index++) {
-      if (index > 0) {
-        result.push(separator);
-      }
-      result.push(segments[index]!);
-    }
-    return result;
-  }
 }
 
 /**
@@ -377,15 +385,6 @@ export class TypoSupport {
    * Auto-detects styling mode from the process environment on best-effort basis.
    */
   static inferFromEnv(): TypoSupport {
-    /*
-    console.warn({
-      no: readEnvVar("NO_COLOR"),
-      force: readEnvVar("FORCE_COLOR"),
-      mock: readEnvVar("MOCK_COLOR"),
-      term: readEnvVar("TERM"),
-      tty: process.stdout.isTTY,
-    });
-    */
     if (!process || !process.env || !process.stdout) {
       return TypoSupport.none();
     }
@@ -396,13 +395,17 @@ export class TypoSupport {
     if (envForceColor === "0") {
       return TypoSupport.none();
     }
-    if (envForceColor !== undefined) {
-      if (!typeBooleanValuesFalse.has(envForceColor.toLowerCase())) {
-        return TypoSupport.tty();
-      }
+    if (envForceColor === "1") {
+      return TypoSupport.tty();
+    }
+    if (envForceColor === "2") {
+      return TypoSupport.tty();
+    }
+    if (envForceColor === "3") {
+      return TypoSupport.tty();
     }
-    if (readEnvVar("MOCK_COLOR")) {
-      return TypoSupport.mock();
+    if (envForceColor) {
+      return TypoSupport.tty();
     }
     if (!process.stdout.isTTY) {
       return TypoSupport.none();

package/src/lib/Usage.ts

@@ -93,7 +93,7 @@ export type UsageOption = {
   /**
    * Extra annotation appended to the option label in help.
    */
-  annotation?: string | undefined;
+  annotation?: string | undefined; // TODO - maybe prefix/postfix would be more useful
   /**
    * Help text.
    */
@@ -175,7 +175,7 @@ export function usageToStyledLines(params: {
   lines.push("");
   const introText = new TypoText();
   introText.push(textUsageText(usage.information.description));
-  if (usage.information.hint) {
+  if (usage.information.hint !== undefined) {
     introText.push(textDelimiter(" "));
     introText.push(textSubtleInfo(`(${usage.information.hint})`));
   }
@@ -221,7 +221,7 @@ export function usageToStyledLines(params: {
     for (const optionUsage of usage.options) {
       const typoGridRow = new Array<TypoText>();
       typoGridRow.push(new TypoText(textDelimiter("  ")));
-      if (optionUsage.short) {
+      if (optionUsage.short !== undefined) {
         typoGridRow.push(
           new TypoText(
             textConstants(`-${optionUsage.short}`),
@@ -234,11 +234,11 @@ export function usageToStyledLines(params: {
       const longOptionText = new TypoText(
         textConstants(`--${optionUsage.long}`),
       );
-      if (optionUsage.label) {
+      if (optionUsage.label !== undefined) {
         longOptionText.push(textDelimiter(" "));
         longOptionText.push(textUserInput(optionUsage.label));
       }
-      if (optionUsage.annotation) {
+      if (optionUsage.annotation !== undefined) {
         longOptionText.push(textSubtleInfo(optionUsage.annotation));
       }
       typoGridRow.push(longOptionText);
@@ -248,14 +248,14 @@ export function usageToStyledLines(params: {
     lines.push(...typoGrid.computeStyledLines(typoSupport));
   }
 
-  if (usage.information.examples) {
+  if (usage.information.examples !== undefined) {
     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 explanationText = new TypoText();
+      explanationText.push(textDelimiter(" "));
+      explanationText.push(textSubtleInfo(`# ${example.explanation}`));
+      lines.push(explanationText.computeStyledString(typoSupport));
       const commandLineText = new TypoText();
       commandLineText.push(textDelimiter(" "));
       commandLineText.push(textConstants(cliName));
@@ -299,11 +299,11 @@ function createInformationals(usage: {
   hint?: string | undefined;
 }): Array<TypoText> {
   const informationals = [];
-  if (usage.description) {
+  if (usage.description !== undefined) {
     informationals.push(textDelimiter(" "));
     informationals.push(textUsefulInfo(usage.description));
   }
-  if (usage.hint) {
+  if (usage.hint !== undefined) {
     informationals.push(textDelimiter(" "));
     informationals.push(textSubtleInfo(`(${usage.hint})`));
   }

package/tests/unit.Reader.commons.ts

@@ -1,5 +1,5 @@
 import { expect, it } from "@jest/globals";
-import { ReaderArgs, ReaderOptionParsing } from "../src";
+import { ReaderArgs, ReaderOptionNextGuard } from "../src";
 
 it("run", async function () {
   const stream = new ReaderArgs([
@@ -36,105 +36,97 @@ it("run", async function () {
 
   expect(stream.consumePositional()).toStrictEqual("positional-0");
 
-  const kFlagUnset = stream.registerOption({
-    longs: ["flag-unset"],
-    shorts: [],
-    parsing: optionFlagParsing,
+  const kFlagUnset = stream.registerOptionLong({
+    key: "flag-unset",
+    nextGuard: optionFlagNextGuard,
   });
-  const kFlagNo = stream.registerOption({
-    longs: ["no-flag-no"],
-    shorts: [],
-    parsing: optionFlagParsing,
+  const kFlagNo = stream.registerOptionLong({
+    key: "no-flag-no",
+    nextGuard: optionFlagNextGuard,
   });
-  const kFlagNormal = stream.registerOption({
-    longs: ["flag-normal"],
-    shorts: [],
-    parsing: optionFlagParsing,
+  const kFlagNormal = stream.registerOptionLong({
+    key: "flag-normal",
+    nextGuard: optionFlagNextGuard,
   });
-  const kFlagPositive = stream.registerOption({
-    longs: ["flag-positive"],
-    shorts: [],
-    parsing: optionFlagParsing,
+  const kFlagPositive = stream.registerOptionLong({
+    key: "flag-positive",
+    nextGuard: optionFlagNextGuard,
   });
-  const kFlagNegative = stream.registerOption({
-    longs: ["flag-negative"],
-    shorts: [],
-    parsing: optionFlagParsing,
+  const kFlagNegative = stream.registerOptionLong({
+    key: "flag-negative",
+    nextGuard: optionFlagNextGuard,
   });
 
   expect(stream.consumePositional()).toStrictEqual("positional-1");
 
-  const kOptionUnset = stream.registerOption({
-    longs: ["option-unset"],
-    shorts: [],
-    parsing: optionValueFixedUniqueParsing,
+  const kOptionUnset = stream.registerOptionLong({
+    key: "option-unset",
+    nextGuard: optionValuedNextGuard,
   });
-  const kOptionSplit = stream.registerOption({
-    longs: ["option-split"],
-    shorts: [],
-    parsing: optionValueFixedUniqueParsing,
+  const kOptionSplit = stream.registerOptionLong({
+    key: "option-split",
+    nextGuard: optionValuedNextGuard,
   });
-  const kOptionJoin = stream.registerOption({
-    longs: ["option-join"],
-    shorts: [],
-    parsing: optionValueFixedUniqueParsing,
+  const kOptionJoin = stream.registerOptionLong({
+    key: "option-join",
+    nextGuard: optionValuedNextGuard,
   });
 
-  const kA = stream.registerOption({
-    longs: [],
-    shorts: ["a"],
-    parsing: optionFlagParsing,
+  const kA = stream.registerOptionShort({
+    key: "a",
+    nextGuard: optionFlagNextGuard,
+    consumeGroupRestAsValue: false,
   });
-  const kB = stream.registerOption({
-    longs: [],
-    shorts: ["b"],
-    parsing: optionValueFixedUniqueParsing,
+  const kB = stream.registerOptionShort({
+    key: "b",
+    nextGuard: optionValuedNextGuard,
+    consumeGroupRestAsValue: true,
   });
 
-  const kC = stream.registerOption({
-    longs: [],
-    shorts: ["c"],
-    parsing: optionFlagParsing,
+  const kC = stream.registerOptionShort({
+    key: "c",
+    nextGuard: optionFlagNextGuard,
+    consumeGroupRestAsValue: false,
   });
-  const kD = stream.registerOption({
-    longs: [],
-    shorts: ["d"],
-    parsing: optionValueFixedUniqueParsing,
+  const kD = stream.registerOptionShort({
+    key: "d",
+    nextGuard: optionValuedNextGuard,
+    consumeGroupRestAsValue: true,
   });
 
-  const kE = stream.registerOption({
-    longs: [],
-    shorts: ["e"],
-    parsing: optionFlagParsing,
+  const kE = stream.registerOptionShort({
+    key: "e",
+    nextGuard: optionFlagNextGuard,
+    consumeGroupRestAsValue: false,
   });
-  const kF = stream.registerOption({
-    longs: [],
-    shorts: ["f"],
-    parsing: optionValueFixedUniqueParsing,
+  const kF = stream.registerOptionShort({
+    key: "f",
+    nextGuard: optionValuedNextGuard,
+    consumeGroupRestAsValue: true,
   });
 
   expect(stream.consumePositional()).toStrictEqual("positional-2");
 
-  const kG = stream.registerOption({
-    longs: [],
-    shorts: ["g"],
-    parsing: optionFlagParsing,
+  const kG = stream.registerOptionShort({
+    key: "g",
+    nextGuard: optionFlagNextGuard,
+    consumeGroupRestAsValue: false,
   });
-  const kH = stream.registerOption({
-    longs: [],
-    shorts: ["h"],
-    parsing: optionFlagParsing,
+  const kH = stream.registerOptionShort({
+    key: "h",
+    nextGuard: optionValuedNextGuard,
+    consumeGroupRestAsValue: true,
   });
 
-  const kI = stream.registerOption({
-    longs: [],
-    shorts: ["i"],
-    parsing: optionFlagParsing,
+  const kI = stream.registerOptionShort({
+    key: "i",
+    nextGuard: optionFlagNextGuard,
+    consumeGroupRestAsValue: false,
   });
-  const kJ = stream.registerOption({
-    longs: [],
-    shorts: ["j"],
-    parsing: optionFlagParsing,
+  const kJ = stream.registerOptionShort({
+    key: "j",
+    nextGuard: optionValuedNextGuard,
+    consumeGroupRestAsValue: true,
   });
 
   expect(stream.consumePositional()).toStrictEqual("positional-3");
@@ -145,76 +137,47 @@ it("run", async function () {
   expect(stream.consumePositional()).toStrictEqual("positional-4");
   expect(stream.consumePositional()).toStrictEqual(undefined);
 
-  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(kFlagUnset()).toStrictEqual([]);
+  expect(kFlagNo()).toStrictEqual([{ inlined: null, separated: [] }]);
+  expect(kFlagNormal()).toStrictEqual([{ inlined: null, separated: [] }]);
+  expect(kFlagPositive()).toStrictEqual([{ inlined: "true", separated: [] }]);
+  expect(kFlagNegative()).toStrictEqual([{ inlined: "false", separated: [] }]);
 
-  expect(stream.getOptionValues(kOptionUnset)).toStrictEqual([]);
-  expect(stream.getOptionValues(kOptionSplit)).toStrictEqual([
+  expect(kOptionUnset()).toStrictEqual([]);
+  expect(kOptionSplit()).toStrictEqual([
     { inlined: null, separated: ["1.1"] },
     { inlined: null, separated: ["1.2"] },
   ]);
-  expect(stream.getOptionValues(kOptionJoin)).toStrictEqual([
+  expect(kOptionJoin()).toStrictEqual([
     { inlined: "2.1", separated: [] },
     { inlined: "2.2", separated: [] },
   ]);
 
-  expect(stream.getOptionValues(kA)).toStrictEqual([
-    { inlined: null, separated: [] },
-  ]);
-  expect(stream.getOptionValues(kB)).toStrictEqual([
+  expect(kA()).toStrictEqual([{ inlined: null, separated: [] }]);
+  expect(kB()).toStrictEqual([
     { inlined: null, separated: ["3.1"] },
     { inlined: null, separated: ["3.2"] },
   ]);
 
-  expect(stream.getOptionValues(kC)).toStrictEqual([
-    { inlined: null, separated: [] },
-  ]);
-  expect(stream.getOptionValues(kD)).toStrictEqual([
+  expect(kC()).toStrictEqual([{ inlined: null, separated: [] }]);
+  expect(kD()).toStrictEqual([
     { inlined: "4.1", separated: [] },
     { inlined: "4.2", separated: [] },
   ]);
 
-  expect(stream.getOptionValues(kE)).toStrictEqual([
-    { inlined: null, separated: [] },
-  ]);
-  expect(stream.getOptionValues(kF)).toStrictEqual([
+  expect(kE()).toStrictEqual([{ inlined: null, separated: [] }]);
+  expect(kF()).toStrictEqual([
     { inlined: "5.1", separated: [] },
     { inlined: "5.2", separated: [] },
   ]);
 
-  expect(stream.getOptionValues(kG)).toStrictEqual([
-    { inlined: null, separated: [] },
-  ]);
-  expect(stream.getOptionValues(kH)).toStrictEqual([
-    { inlined: "FALSE", separated: [] },
-  ]);
+  expect(kG()).toStrictEqual([{ inlined: null, separated: [] }]);
+  expect(kH()).toStrictEqual([{ inlined: "FALSE", separated: [] }]);
 
-  expect(stream.getOptionValues(kI)).toStrictEqual([
-    { inlined: null, separated: [] },
-  ]);
-  expect(stream.getOptionValues(kJ)).toStrictEqual([
-    { inlined: "TRUE", separated: [] },
-  ]);
+  expect(kI()).toStrictEqual([{ inlined: null, separated: [] }]);
+  expect(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,
-};
+const optionFlagNextGuard: ReaderOptionNextGuard = () => false;
+const optionValuedNextGuard: ReaderOptionNextGuard = (value) =>
+  value.inlined === null && value.separated.length === 0;

package/tests/unit.Reader.parsings.ts

@@ -3,47 +3,35 @@ 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",
-    },
+  const kOptionVariadicStop = readerArgs1.registerOptionLong({
+    key: "val",
+    nextGuard: (value, nextArg) =>
+      nextArg !== undefined &&
+      value.separated[value.separated.length - 1] !== "STOP",
   });
   expect(readerArgs1.consumePositional()).toStrictEqual("C");
   expect(readerArgs1.consumePositional()).toStrictEqual(undefined);
-  expect(readerArgs1.getOptionValues(kOptionVariadicStop)).toStrictEqual([
+  expect(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,
-    },
+  const kOptionVariadicFull = readerArgs2.registerOptionLong({
+    key: "val",
+    nextGuard: (_value, nextArg) => nextArg !== undefined,
   });
   expect(readerArgs2.consumePositional()).toStrictEqual(undefined);
-  expect(readerArgs2.getOptionValues(kOptionVariadicFull)).toStrictEqual([
+  expect(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"),
-    },
+  const kOptionVariadicKeyed = readerArgs3.registerOptionLong({
+    key: "val",
+    nextGuard: (value) => value.separated.length < Number(value.inlined ?? "0"),
   });
   expect(readerArgs3.consumePositional()).toStrictEqual(undefined);
-  expect(readerArgs3.getOptionValues(kOptionVariadicKeyed)).toStrictEqual([
+  expect(kOptionVariadicKeyed()).toStrictEqual([
     { inlined: "2", separated: ["A", "B"] },
     { inlined: "1", separated: ["C"] },
   ]);