cli-kiss 0.2.3 → 0.2.5

package/src/lib/Positional.ts

@@ -1,27 +1,19 @@
 import { ReaderPositionals } from "./Reader";
 import { Type } from "./Type";
-import {
-  TypoError,
-  TypoString,
-  typoStyleLogic,
-  typoStyleUserInput,
-  TypoText,
-} from "./Typo";
+import { TypoError, TypoString, typoStyleUserInput, TypoText } from "./Typo";
+import { UsagePositional } from "./Usage";
 
 /**
- * A bare (non-option) positional argument with its parsing and usage-generation logic.
- *
- * Created with {@link positionalRequired}, {@link positionalOptional}, or
- * {@link positionalVariadics} and passed via the `positionals` array of
- * {@link operation}, consumed in declaration order.
+ * A positional argument. Created with {@link positionalRequired}, {@link positionalOptional},
+ * or {@link positionalVariadics}.
  *
  * @typeParam Value - Decoded value type.
  */
 export type Positional<Value> = {
   /**
-   * Returns metadata used to render the `Positionals:` section of help.
+   * Returns metadata for the `Positionals:` section.
    */
-  generateUsage(): PositionalUsage;
+  generateUsage(): UsagePositional;
   /**
    * Consumes the next positional token from `readerPositionals`.
    * Returns a decoder that produces the final value.
@@ -45,63 +37,36 @@ export type PositionalDecoder<Value> = {
   decodeValue(): Value;
 };
 
-/**
- * Human-readable metadata for a single positional argument, used to render the
- * `Positionals:` section of the help output produced by {@link usageToStyledLines}.
- */
-export type PositionalUsage = {
-  /**
-   * 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>;
-};
-
 /**
  * Creates a required positional — missing token throws {@link TypoError}.
- * Label defaults to uppercased `type.content` in angle brackets (e.g. `<STRING>`).
  *
  * @typeParam Value - Type produced by the decoder.
  *
- * @param definition - Positional configuration.
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
- * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
  * @param definition.type - Decoder for the raw token.
  * @returns A {@link Positional}`<Value>`.
  *
  * @example
  * ```ts
  * const namePositional = positionalRequired({
- *   type: typeString,
- *   label: "NAME",
+ *   type: type("name"),
  *   description: "The name to greet",
  * });
- * // Parses: my-cli Alice  →  "Alice"
+ * // Usage:
+ * //   my-cli Alice  →  "Alice"
  * ```
  */
 export function positionalRequired<Value>(definition: {
   description?: string;
   hint?: string;
-  label?: Uppercase<string>;
   type: Type<Value>;
 }): Positional<Value> {
-  const label = `<${definition.label ?? definition.type.content.toUpperCase()}>`;
+  const { description, hint, type } = definition;
+  const label = `<${type.content}>`;
   return {
     generateUsage() {
-      return {
-        description: definition.description,
-        hint: definition.hint,
-        label: label as Uppercase<string>,
-      };
+      return { description, hint, label };
     },
     consumeAndMakeDecoder(readerPositionals: ReaderPositionals) {
       const positional = readerPositionals.consumePositional();
@@ -124,14 +89,11 @@ export function positionalRequired<Value>(definition: {
 
 /**
  * Creates an optional positional — absent token falls back to `default()`.
- * Label defaults to uppercased `type.content` in square brackets (e.g. `[STRING]`).
  *
  * @typeParam Value - Type produced by the decoder (or the default).
  *
- * @param definition - Positional configuration.
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
- * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
  * @param definition.type - Decoder for the raw token.
  * @param definition.default - Value when absent. Throw to make it required.
  * @returns A {@link Positional}`<Value>`.
@@ -139,30 +101,26 @@ export function positionalRequired<Value>(definition: {
  * @example
  * ```ts
  * const greeteePositional = positionalOptional({
- *   type: typeString,
- *   label: "NAME",
+ *   type: type("name"),
  *   description: "Name to greet (default: world)",
  *   default: () => "world",
  * });
- * // my-cli         →  "world"
- * // my-cli Alice   →  "Alice"
+ * // Usage:
+ * //   my-cli  →  "world"
+ * //   my-cli Alice  →  "Alice"
  * ```
  */
 export function positionalOptional<Value>(definition: {
   description?: string;
   hint?: string;
-  label?: Uppercase<string>;
   type: Type<Value>;
   default: () => Value;
 }): Positional<Value> {
-  const label = `[${definition.label ?? definition.type.content.toUpperCase()}]`;
+  const { description, hint, type } = definition;
+  const label = `[${type.content}]`;
   return {
     generateUsage() {
-      return {
-        description: definition.description,
-        hint: definition.hint,
-        label: label as Uppercase<string>,
-      };
+      return { description, hint, label };
     },
     consumeAndMakeDecoder(readerPositionals: ReaderPositionals) {
       const positional = readerPositionals.consumePositional();
@@ -172,13 +130,7 @@ export function positionalOptional<Value>(definition: {
             try {
               return definition.default();
             } catch (error) {
-              throw new TypoError(
-                new TypoText(
-                  new TypoString(label, typoStyleUserInput),
-                  new TypoString(`: Failed to get default value`),
-                ),
-                error,
-              );
+              throwsWhenFailedToGetDefault(label);
             }
           }
           return decodeValue(label, definition.type, positional);
@@ -190,47 +142,41 @@ export function positionalOptional<Value>(definition: {
 
 /**
  * Creates a variadic positional that collects zero or more remaining tokens into an array.
- * Stops at `endDelimiter` (consumed, not included). Label: `[TYPE]...` notation.
+ * Optionally stops at `endDelimiter` (consumed, not included).
  *
  * @typeParam Value - Type produced by the decoder for each token.
  *
- * @param definition - Positional configuration.
  * @param definition.endDelimiter - Sentinel token that stops collection (consumed, not included).
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
- * @param definition.label - Label without brackets; defaults to uppercased `type.content`.
  * @param definition.type - Decoder applied to each token.
  * @returns A {@link Positional}`<Array<Value>>`.
  *
  * @example
  * ```ts
  * const filesPositional = positionalVariadics({
- *   type: typeString,
- *   label: "FILE",
+ *   type: typePath(),
  *   description: "Files to process",
  * });
- * // my-cli a.ts b.ts c.ts  →  ["a.ts", "b.ts", "c.ts"]
- * // my-cli                  →  []
+ * // Usage:
+ * //   my-cli  →  []
+ * //   my-cli a.ts b.ts c.ts  →  ["a.ts", "b.ts", "c.ts"]
  * ```
  */
 export function positionalVariadics<Value>(definition: {
   endDelimiter?: string;
   description?: string;
   hint?: string;
-  label?: Uppercase<string>;
   type: Type<Value>;
 }): Positional<Array<Value>> {
-  const label = `[${definition.label ?? definition.type.content.toUpperCase()}]`;
+  const { description, hint, type } = definition;
+  const labelSingle = `[${type.content}]`;
+  const labelMultiple =
+    `${labelSingle}...` +
+    (definition.endDelimiter ? ` ["${definition.endDelimiter}"]` : "");
   return {
     generateUsage() {
-      return {
-        description: definition.description,
-        hint: definition.hint,
-        label: (`${label}...` +
-          (definition.endDelimiter
-            ? `["${definition.endDelimiter}"]`
-            : "")) as Uppercase<string>,
-      };
+      return { description, hint, label: labelMultiple };
     },
     consumeAndMakeDecoder(readerPositionals: ReaderPositionals) {
       const positionals = new Array<string>();
@@ -246,9 +192,9 @@ export function positionalVariadics<Value>(definition: {
       }
       return {
         decodeValue() {
-          return positionals.map((positional) => {
-            return decodeValue(label, definition.type, positional);
-          });
+          return positionals.map((positional) =>
+            decodeValue(labelSingle, definition.type, positional),
+          );
         },
       };
     },
@@ -262,11 +208,15 @@ function decodeValue<Value>(
 ): Value {
   return TypoError.tryWithContext(
     () => type.decoder(input),
-    () =>
-      new TypoText(
-        new TypoString(label, typoStyleUserInput),
-        new TypoString(`: `),
-        new TypoString(type.content, typoStyleLogic),
-      ),
+    () => new TypoText(new TypoString(label, typoStyleUserInput)),
+  );
+}
+
+function throwsWhenFailedToGetDefault(label: string): never {
+  throw new TypoError(
+    new TypoText(
+      new TypoString(label, typoStyleUserInput),
+      new TypoString(`: Failed to get default value`),
+    ),
   );
 }

package/src/lib/Reader.ts

@@ -7,44 +7,58 @@ import {
 } from "./Typo";
 
 /**
- * Opaque key identifying a registered option within a {@link ReaderArgs} instance.
- * Returned by {@link ReaderArgs.registerOption}; passed to {@link ReaderArgs.getOptionValues}.
+ * Opaque key returned by {@link ReaderArgs.registerOption}.
  */
 export type ReaderOptionKey = (string | { __brand: "ReaderOptionKey" }) & {
   __brand: "ReaderOptionKey";
 };
 
 /**
- * Option registration and query interface, implemented by {@link ReaderArgs}.
- * Exposed separately from {@link ReaderPositionals} so parsers depend only on what they need.
+ * Parsing behaviour for a registered option, passed to {@link ReaderArgs.registerOption}.
+ */
+export type ReaderOptionParsing = {
+  consumeShortGroup: boolean; // TODO - this doesnt matter when no short option
+  consumeNextArg: (
+    inlined: string | null,
+    separated: Array<string>,
+    nextArg: string | undefined,
+  ) => boolean;
+};
+
+/**
+ * Result of parsing an option, including its inlined value and any following separated values.
+ */
+export type ReaderOptionValue = {
+  inlined: string | null;
+  separated: Array<string>;
+};
+
+/**
+ * Option registration/query interface. Subset of {@link ReaderArgs}.
  */
 export type ReaderOptions = {
   /**
-   * Registers an option so the parser can recognise it.
+   * Registers an option; all `longs` and `shorts` share the same key.
    *
    * @param definition.longs - Long-form names (without `--`).
    * @param definition.shorts - Short-form names (without `-`).
-   * @param definition.valued - `true` if the option takes a value; `false` for flags.
+   * @param definition.parsing - Parsing behaviour.
    * @returns A {@link ReaderOptionKey} for later retrieval.
    * @throws `Error` if a name is already registered or short names overlap.
    */
   registerOption(definition: {
     longs: Array<string>;
     shorts: Array<string>;
-    valued: boolean;
+    parsing: ReaderOptionParsing;
   }): ReaderOptionKey;
   /**
-   * Returns all values collected for the option identified by `key`.
-   *
-   * @param key - Key from {@link ReaderOptions.registerOption}.
-   * @returns Raw string values, one per occurrence; empty if never provided.
-   * @throws `Error` if `key` was not registered.
+   * Returns all values collected for `key`.
    */
-  getOptionValues(key: ReaderOptionKey): Array<string>;
+  getOptionValues(key: ReaderOptionKey): Array<ReaderOptionValue>;
 };
 
 /**
- * Positional token consumption interface, implemented by {@link ReaderArgs}.
+ * Positional consumption interface. Subset of {@link ReaderArgs}.
  */
 export type ReaderPositionals = {
   /**
@@ -69,10 +83,9 @@ export class ReaderArgs {
   #args: ReadonlyArray<string>;
   #parsedIndex: number;
   #parsedDouble: boolean;
-  #keyByLong: Map<string, ReaderOptionKey>;
-  #keyByShort: Map<string, ReaderOptionKey>;
-  #valuedByKey: Map<ReaderOptionKey, boolean>;
-  #resultByKey: Map<ReaderOptionKey, Array<string>>;
+  #optionContextByLong: Map<string, ReaderOptionContext>;
+  #optionContextByShort: Map<string, ReaderOptionContext>;
+  #optionContextByKey: Map<ReaderOptionKey, ReaderOptionContext>;
 
   /**
    * @param args - Raw CLI tokens (e.g. `process.argv.slice(2)`). Not mutated.
@@ -81,27 +94,25 @@ export class ReaderArgs {
     this.#args = args;
     this.#parsedIndex = 0;
     this.#parsedDouble = false;
-    this.#keyByLong = new Map();
-    this.#keyByShort = new Map();
-    this.#valuedByKey = new Map();
-    this.#resultByKey = new Map();
+    this.#optionContextByLong = new Map();
+    this.#optionContextByShort = new Map();
+    this.#optionContextByKey = new Map();
   }
 
   /**
    * Registers an option; all `longs` and `shorts` share the same key.
-   * Short names support stacking (e.g. `-abc`) and inline values (e.g. `-nvalue`),
-   * but must not be prefixes of one another.
+   * Short names must not be prefixes of one another.
    *
    * @param definition.longs - Long-form names (without `--`).
    * @param definition.shorts - Short-form names (without `-`).
-   * @param definition.valued - `true` if the option takes a value; `false` for flags.
+   * @param definition.parsing - Parsing behaviour.
    * @returns A {@link ReaderOptionKey} for {@link ReaderArgs.getOptionValues}.
    * @throws `Error` if any name is already registered or short names overlap.
    */
   registerOption(definition: {
     longs: Array<string>;
     shorts: Array<string>;
-    valued: boolean;
+    parsing: ReaderOptionParsing;
   }) {
     const key = [
       ...definition.longs.map((long) => `--${long}`),
@@ -111,7 +122,7 @@ export class ReaderArgs {
       if (!this.#isValidOptionName(long)) {
         throw new Error(`Invalid option name: --${long}`);
       }
-      if (this.#keyByLong.has(long)) {
+      if (this.#optionContextByLong.has(long)) {
         throw new Error(`Option already registered: --${long}`);
       }
     }
@@ -119,18 +130,18 @@ export class ReaderArgs {
       if (!this.#isValidOptionName(short)) {
         throw new Error(`Invalid option name: -${short}`);
       }
-      if (this.#keyByShort.has(short)) {
+      if (this.#optionContextByShort.has(short)) {
         throw new Error(`Option already registered: -${short}`);
       }
       for (let i = 0; i < short.length; i++) {
         const shortSlice = short.slice(0, i);
-        if (this.#keyByShort.has(shortSlice)) {
+        if (this.#optionContextByShort.has(shortSlice)) {
           throw new Error(
             `Option -${short} overlap with shorter option: -${shortSlice}`,
           );
         }
       }
-      for (const shortOther of this.#keyByShort.keys()) {
+      for (const shortOther of this.#optionContextByShort.keys()) {
         if (shortOther.startsWith(short)) {
           throw new Error(
             `Option -${short} overlap with longer option: -${shortOther}`,
@@ -138,35 +149,37 @@ export class ReaderArgs {
         }
       }
     }
+    const optionContext = {
+      parsing: definition.parsing,
+      results: new Array<ReaderOptionValue>(),
+    };
     for (const long of definition.longs) {
-      this.#keyByLong.set(long, key);
+      this.#optionContextByLong.set(long, optionContext);
     }
     for (const short of definition.shorts) {
-      this.#keyByShort.set(short, key);
+      this.#optionContextByShort.set(short, optionContext);
     }
-    this.#valuedByKey.set(key, definition.valued);
-    this.#resultByKey.set(key, new Array<string>());
+    this.#optionContextByKey.set(key, optionContext);
     return key;
   }
 
   /**
-   * Returns all values collected for the option key.
+   * Returns all values collected for `key`.
    *
    * @param key - Key from {@link ReaderArgs.registerOption}.
-   * @returns String values, one per occurrence.
+   * @returns One entry per occurrence.
    * @throws `Error` if `key` was not registered.
    */
-  getOptionValues(key: ReaderOptionKey): Array<string> {
-    const optionResult = this.#resultByKey.get(key);
-    if (optionResult === undefined) {
+  getOptionValues(key: ReaderOptionKey): Array<ReaderOptionValue> {
+    const optionContext = this.#optionContextByKey.get(key);
+    if (optionContext === undefined) {
       throw new Error(`Unregistered option: ${key}`);
     }
-    return optionResult;
+    return optionContext.results;
   }
 
   /**
-   * Returns the next bare positional token.
-   * Parse intervening options as side-effects.
+   * Returns the next positional token; parses intervening options as a side-effect.
    * All tokens after `--` are treated as positionals.
    *
    * @returns The next positional, or `undefined` when exhausted.
@@ -175,19 +188,19 @@ export class ReaderArgs {
   consumePositional(): string | undefined {
     while (true) {
       const arg = this.#consumeArg();
-      if (arg === null) {
+      if (arg === undefined) {
         return undefined;
       }
-      if (this.#processedAsPositional(arg)) {
+      if (!this.#tryConsumeAsOption(arg)) {
         return arg;
       }
     }
   }
 
-  #consumeArg(): string | null {
+  #consumeArg(): string | undefined {
     const arg = this.#args[this.#parsedIndex];
     if (arg === undefined) {
-      return null;
+      return undefined;
     }
     this.#parsedIndex++;
     if (!this.#parsedDouble) {
@@ -199,9 +212,9 @@ export class ReaderArgs {
     return arg;
   }
 
-  #processedAsPositional(arg: string): boolean {
+  #tryConsumeAsOption(arg: string): boolean {
     if (this.#parsedDouble) {
-      return true;
+      return false;
     }
     if (arg.startsWith("--")) {
       const valueIndexStart = arg.indexOf("=");
@@ -213,80 +226,90 @@ export class ReaderArgs {
           arg.slice(valueIndexStart + 1),
         );
       }
-      return false;
+      return true;
     }
     if (arg.startsWith("-")) {
       let shortIndexStart = 1;
       let shortIndexEnd = 2;
       while (shortIndexEnd <= arg.length) {
-        const result = this.#tryConsumeOptionShort(
-          arg.slice(shortIndexStart, shortIndexEnd),
-          arg.slice(shortIndexEnd),
-        );
-        if (result === true) {
-          return false;
-        }
-        if (result === false) {
+        const short = arg.slice(shortIndexStart, shortIndexEnd);
+        const optionContext = this.#optionContextByShort.get(short);
+        if (optionContext !== undefined) {
+          const rest = arg.slice(shortIndexEnd);
+          if (this.#tryConsumeOptionShort(optionContext, short, rest)) {
+            return true;
+          }
           shortIndexStart = shortIndexEnd;
         }
         shortIndexEnd++;
       }
       throw new TypoError(
         new TypoText(
-          new TypoString(`-${arg.slice(shortIndexStart)}`, typoStyleConstants),
-          new TypoString(`: Unexpected unknown option`),
+          new TypoString(`Unexpected unknown option(s): `),
+          new TypoString(`-${arg.slice(shortIndexStart)}`, typoStyleQuote),
         ),
       );
     }
-    return true;
+    return false;
   }
 
-  #consumeOptionLong(long: string, direct: string | null): void {
+  #consumeOptionLong(long: string, inlined: string | null): void {
     const constant = `--${long}`;
-    const key = this.#keyByLong.get(long);
-    if (key !== undefined) {
-      if (direct !== null) {
-        return this.#acknowledgeOption(key, direct);
-      }
-      const valued = this.#valuedByKey.get(key);
-      if (valued) {
-        return this.#acknowledgeOption(key, this.#consumeOptionValue(constant));
-      }
-      return this.#acknowledgeOption(key, "true");
+    const optionContext = this.#optionContextByLong.get(long);
+    if (optionContext !== undefined) {
+      return this.#consumeOptionValues(optionContext, constant, inlined);
     }
     throw new TypoError(
       new TypoText(
-        new TypoString(constant, typoStyleConstants),
-        new TypoString(`: Unexpected unknown option`),
+        new TypoString(`Unexpected unknown option: `),
+        new TypoString(constant, typoStyleQuote),
       ),
     );
   }
 
-  #tryConsumeOptionShort(short: string, rest: string): boolean | null {
-    const key = this.#keyByShort.get(short);
-    if (key !== undefined) {
-      if (rest.startsWith("=")) {
-        this.#acknowledgeOption(key, rest.slice(1));
-        return true;
-      }
-      const valued = this.#valuedByKey.get(key);
-      if (valued) {
-        if (rest === "") {
-          this.#acknowledgeOption(key, this.#consumeOptionValue(`-${short}`));
-        } else {
-          this.#acknowledgeOption(key, rest);
-        }
-        return true;
-      }
-      this.#acknowledgeOption(key, "true");
-      return rest === "";
+  #tryConsumeOptionShort(
+    optionContext: ReaderOptionContext,
+    short: string,
+    rest: string,
+  ): boolean {
+    const constant = `-${short}`;
+    if (rest.startsWith("=")) {
+      this.#consumeOptionValues(optionContext, constant, rest.slice(1));
+      return true;
+    }
+    if (rest.length === 0) {
+      this.#consumeOptionValues(optionContext, constant, null);
+      return true;
+    }
+    if (optionContext.parsing.consumeShortGroup) {
+      this.#consumeOptionValues(optionContext, constant, rest);
+      return true;
     }
-    return null;
+    this.#consumeOptionValues(optionContext, constant, null);
+    return false;
   }
 
-  #consumeOptionValue(constant: string) {
+  #consumeOptionValues(
+    optionContext: ReaderOptionContext,
+    constant: string,
+    inlined: string | null,
+  ) {
+    const separated = new Array<string>();
+    while (
+      optionContext.parsing.consumeNextArg(
+        inlined,
+        separated,
+        this.#args[this.#parsedIndex],
+      )
+    ) {
+      separated.push(this.#consumeOptionValue(constant));
+    }
+    optionContext.results.push({ inlined, separated });
+  }
+
+  #consumeOptionValue(constant: string): string {
     const arg = this.#consumeArg();
-    if (arg === null) {
+    if (arg === undefined) {
       throw new TypoError(
         new TypoText(
           new TypoString(constant, typoStyleConstants),
@@ -316,11 +339,12 @@ export class ReaderArgs {
     return arg;
   }
 
-  #acknowledgeOption(key: ReaderOptionKey, value: string) {
-    this.getOptionValues(key).push(value);
-  }
-
   #isValidOptionName(name: string): boolean {
-    return name.length > 0 && !name.includes("=");
+    return name.length > 0 && !name.includes("=") && !name.includes("\0");
   }
 }
+
+type ReaderOptionContext = {
+  parsing: ReaderOptionParsing;
+  results: Array<ReaderOptionValue>;
+};