cli-kiss 0.2.6 → 0.2.8

package/src/lib/Option.ts

@@ -1,4 +1,10 @@
-import { ReaderOptionParsing, ReaderArgs as ReaderOptions } from "./Reader";
+import {
+  ReaderOptionGetter,
+  ReaderOptionNextGuard,
+  ReaderOptionRestGuard,
+  ReaderOptions,
+  ReaderOptionValue,
+} from "./Reader";
 import { Type, typeBoolean } from "./Type";
 import {
   TypoError,
@@ -36,7 +42,7 @@ export type OptionDecoder<Value> = {
   /**
    * Returns the decoded option value.
    *
-   * @throws {@link TypoError} if decoding failed.
+   * @throws if decoding failed.
    */
   getAndDecodeValue(): Value;
 };
@@ -44,8 +50,12 @@ export type OptionDecoder<Value> = {
 /**
  * Creates a boolean flag option (`--verbose`, optionally `--flag=no`).
  *
- * Parsing: absent → default value; `--flag` / `--flag=yes` → `true`; `--flag=no` → `false`;
- * specified more than once → throws {@link TypoError}.
+ * Syntax: `--long`, `--long=no`, `-s`, `-s=no`.
+ * Parsing logic:
+ * - absent → default value
+ * - `--flag` / `--flag=yes` → `true`
+ * - `--flag=no` → `false`
+ * - specified more than once → throws.
  *
  * @param definition.long - Long-form name (without `--`).
  * @param definition.short - Short-form name (without `-`).
@@ -62,11 +72,6 @@ export type OptionDecoder<Value> = {
  *   short: "v",
  *   description: "Enable verbose output",
  * });
- * // Usage:
- * //   my-cli  →  false
- * //   my-cli --verbose  →  true
- * //   my-cli --verbose=yes  →  true
- * //   my-cli -v=no  →  false
  * ```
  */
 export function optionFlag(definition: {
@@ -84,28 +89,30 @@ export function optionFlag(definition: {
       return { short, long, annotation: "[=no]", description, hint };
     },
     registerAndMakeDecoder(readerOptions: ReaderOptions) {
-      const key = registerOption(readerOptions, {
-        long,
-        short,
-        aliasesLongs: aliases?.longs,
-        aliasesShorts: aliases?.shorts,
-        parsing: { consumeShortGroup: false, consumeNextArg: () => false },
+      const resultsGetter = setupOptionAliased(readerOptions, {
+        longKey: long,
+        shortKey: short,
+        aliasLongKeys: aliases?.longs,
+        aliasShortKeys: aliases?.shorts,
+        restGuard: () => false,
+        nextGuard: () => false,
       });
       return {
         getAndDecodeValue() {
-          const optionResults = readerOptions.getOptionValues(key);
-          if (optionResults.length > 1) {
-            throwSetMultipleTimesError(long);
+          const results = resultsGetter();
+          if (results.length > 1) {
+            throwSetMultipleTimesError(results.map((r) => r.identifier));
           }
-          if (optionResults.length === 0) {
+          if (results.length === 0) {
             return definition.default === undefined
               ? false
               : definition.default;
           }
-          const positiveResult = optionResults[0]!;
-          const value =
-            positiveResult.inlined === null ? "true" : positiveResult.inlined;
-          return decodeValue({ long, short, type, input: value });
+          const input = results[0]!.value.inlined;
+          if (input === null) {
+            return true;
+          }
+          return decodeValue({ long, label: undefined, type, input });
         },
       };
     },
@@ -115,8 +122,13 @@ export function optionFlag(definition: {
 /**
  * Creates an option that accepts exactly one value (e.g. `--output dist/`).
  *
- * Parsing: absent → `defaultValue()`; once → decoded with `type`; more than once → {@link TypoError}.
- * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ * Syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ * Parsing logic:
+ * - absent → `fallbackValueIfAbsent()`
+ * - `--long value` → decoded with `type.decoder("value")`
+ * - more than once → throws
+ * - if `impliedValueIfNotInlined` is not provided, then: `--long` / `-s` without a value → throws
+ * - if `impliedValueIfNotInlined` is provided, then: `--long` / `-s` without an inline value → `impliedValueIfNotInlined()`
  *
  * @typeParam Value - Type produced by the decoder.
  *
@@ -126,8 +138,8 @@ export function optionFlag(definition: {
  * @param definition.hint - Short note shown in parentheses.
  * @param definition.aliases - Additional names.
  * @param definition.type - Decoder for the raw string value.
- * @param definition.valueWhenNotDefined - Default value when the option is not specified at all.
- * @param definition.valueWhenNotInlined - Default value when the option is specified without an inline value (e.g. `--option` or `-o`).
+ * @param definition.fallbackValueIfAbsent - Default value when the option is not specified at all.
+ * @param definition.impliedValueIfNotInlined - Default value when the option is specified without an inline value (e.g. `--option` or `-o`).
  * @returns An {@link Option}`<Value>`.
  *
  * @example
@@ -137,12 +149,8 @@ export function optionFlag(definition: {
  *   short: "o",
  *   type: typePath(),
  *   description: "Output directory",
- *   valueWhenNotDefined: () => "dist",
+ *   fallbackValueIfAbsent: () => "dist",
  * });
- * // Usage:
- * //   my-cli  →  "dist"
- * //   my-cli --output folder  →  "folder"
- * //   my-cli -o folder  →  "folder"
  * ```
  */
 export function optionSingleValue<Value>(definition: {
@@ -152,58 +160,83 @@ export function optionSingleValue<Value>(definition: {
   hint?: string;
   aliases?: { longs?: Array<string>; shorts?: Array<string> };
   type: Type<Value>;
-  defaultWhenNotDefined: () => Value;
-  defaultWhenNotInlined?: () => Value;
+  fallbackValueIfAbsent?: () => Value;
+  impliedValueIfNotInlined?: () => Value;
 }): Option<Value> {
   const { long, short, description, hint, aliases, type } = definition;
-  const label = `<${type.content}>`;
+  const label = definition.impliedValueIfNotInlined
+    ? undefined
+    : `<${type.content}>`;
+  const annotation = definition.impliedValueIfNotInlined
+    ? `[=${type.content}]`
+    : undefined; // TODO - handle implied value and default better in usage and errors
   return {
     generateUsage() {
-      return { short, long, label, description, hint };
+      return { short, long, label, annotation, description, hint };
     },
     registerAndMakeDecoder(readerOptions: ReaderOptions) {
-      const key = registerOption(readerOptions, {
-        long,
-        short,
-        aliasesLongs: aliases?.longs,
-        aliasesShorts: aliases?.shorts,
-        parsing: {
-          consumeShortGroup: true,
-          consumeNextArg(inlined, separated) {
-            if (definition.defaultWhenNotInlined !== undefined) {
-              return false;
-            }
-            return inlined === null && separated.length === 0;
-          },
+      const resultsGetter = setupOptionAliased(readerOptions, {
+        longKey: long,
+        shortKey: short,
+        aliasLongKeys: aliases?.longs,
+        aliasShortKeys: aliases?.shorts,
+        restGuard: () => {
+          if (definition.impliedValueIfNotInlined !== undefined) {
+            return false;
+          }
+          return true;
+        },
+        nextGuard: (value) => {
+          if (definition.impliedValueIfNotInlined !== undefined) {
+            return false;
+          }
+          if (value.inlined !== null) {
+            return false;
+          }
+          if (value.separated.length !== 0) {
+            return false;
+          }
+          return true;
         },
       });
       return {
         getAndDecodeValue() {
-          const optionResults = readerOptions.getOptionValues(key);
-          if (optionResults.length > 1) {
-            throwSetMultipleTimesError(long);
+          const results = resultsGetter();
+          if (results.length > 1) {
+            throwSetMultipleTimesError(
+              results.map((result) => result.identifier),
+            );
           }
-          const optionResult = optionResults[0];
-          if (optionResult === undefined) {
+          const result = results[0];
+          if (result === undefined) {
+            if (definition.fallbackValueIfAbsent === undefined) {
+              const errorText = makeErrorText({ long, label, type });
+              errorText.push(new TypoString(`: Is required, but was not set.`));
+              throw new TypoError(errorText);
+            }
             try {
-              return definition.defaultWhenNotDefined();
+              return definition.fallbackValueIfAbsent();
             } catch (error) {
-              throwFailedToGetDefaultValueError(long, error, "not set");
+              const errorText = makeErrorText({ long, label, type });
+              errorText.push(new TypoString(`: Failed to get fallback value.`));
+              throw new TypoError(errorText, error);
             }
           }
-          if (optionResult.inlined) {
-            const inlined = optionResult.inlined;
-            return decodeValue({ long, short, label, type, input: inlined });
+          const inlined = result.value.inlined;
+          if (inlined !== null) {
+            return decodeValue({ long, label, type, input: inlined });
           }
-          if (definition.defaultWhenNotInlined !== undefined) {
+          if (definition.impliedValueIfNotInlined !== undefined) {
             try {
-              return definition.defaultWhenNotInlined();
+              return definition.impliedValueIfNotInlined();
             } catch (error) {
-              throwFailedToGetDefaultValueError(long, error, "not inlined");
+              const errorText = makeErrorText({ long, label, type });
+              errorText.push(new TypoString(`: Failed to get implied value.`));
+              throw new TypoError(errorText, error);
             }
           }
-          const separated = optionResult.separated[0]!;
-          return decodeValue({ long, short, label, type, input: separated });
+          const separated = result.value.separated[0]!;
+          return decodeValue({ long, label, type, input: separated });
         },
       };
     },
@@ -213,8 +246,10 @@ export function optionSingleValue<Value>(definition: {
 /**
  * Creates an option that collects every occurrence into an array (e.g. `--file a.ts --file b.ts`).
  *
- * Parsing: absent → `[]`; N occurrences → array of N decoded values in order.
- * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ * Syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ * Parsing logic:
+ * - absent → `[]`
+ * - N occurrences → array of N decoded values in order.
  *
  * @typeParam Value - Type produced by the decoder for each occurrence.
  *
@@ -235,7 +270,6 @@ export function optionSingleValue<Value>(definition: {
  *   label: "PATH",
  *   description: "Input file (may be repeated)",
  * });
- * // Usage: my-cli --file a.ts --file b.ts  →  ["a.ts", "b.ts"]
  * ```
  */
 export function optionRepeatable<Value>(definition: {
@@ -253,23 +287,28 @@ export function optionRepeatable<Value>(definition: {
       return { short, long, label, annotation: " [*]", description, hint };
     },
     registerAndMakeDecoder(readerOptions: ReaderOptions) {
-      const key = registerOption(readerOptions, {
-        long,
-        short,
-        aliasesLongs: aliases?.longs,
-        aliasesShorts: aliases?.shorts,
-        parsing: {
-          consumeShortGroup: true,
-          consumeNextArg: (inlined, separated) =>
-            inlined === null && separated.length === 0,
+      const resultsGetter = setupOptionAliased(readerOptions, {
+        longKey: long,
+        shortKey: short,
+        aliasLongKeys: aliases?.longs,
+        aliasShortKeys: aliases?.shorts,
+        restGuard: () => true,
+        nextGuard: (value) => {
+          if (value.inlined !== null) {
+            return false;
+          }
+          if (value.separated.length !== 0) {
+            return false;
+          }
+          return true;
         },
       });
       return {
         getAndDecodeValue() {
-          const optionResults = readerOptions.getOptionValues(key);
-          return optionResults.map((optionResult) => {
-            const input = optionResult.inlined ?? optionResult.separated[0]!;
-            return decodeValue({ long, short, label, type, input });
+          return resultsGetter().map((result) => {
+            const value = result.value;
+            const input = value.inlined ?? value.separated[0]!;
+            return decodeValue({ long, label, type, input });
           });
         },
       };
@@ -279,73 +318,99 @@ export function optionRepeatable<Value>(definition: {
 
 function decodeValue<Value>(params: {
   long: string;
-  short?: string | undefined;
-  label?: string | undefined;
+  label: string | undefined;
   type: Type<Value>;
   input: string;
 }): Value {
+  const { long, label, type, input } = params;
   return TypoError.tryWithContext(
-    () => params.type.decoder(params.input),
-    () => {
-      const text = new TypoText();
-      if (params.short) {
-        text.push(new TypoString(`-${params.short}`, typoStyleConstants));
-        text.push(new TypoString(`, `));
-      }
-      text.push(new TypoString(`--${params.long}`, typoStyleConstants));
-      if (params.label) {
-        text.push(new TypoString(`: `));
-        text.push(new TypoString(params.label, typoStyleUserInput));
-      } else {
-        text.push(new TypoString(`: `));
-        text.push(new TypoString(params.type.content, typoStyleLogic));
-      }
-      return text;
-    },
+    () => type.decoder(input),
+    () => makeErrorText({ long, label, type }),
   );
 }
 
-function registerOption(
+function makeErrorText(params: {
+  long: string;
+  label: string | undefined;
+  type: Type<any>;
+}): TypoText {
+  const errorText = new TypoText();
+  errorText.push(new TypoString(`--${params.long}`, typoStyleConstants));
+  if (params.label !== undefined) {
+    errorText.push(new TypoString(`: `));
+    errorText.push(new TypoString(params.label, typoStyleUserInput));
+  } else {
+    errorText.push(new TypoString(`: `));
+    errorText.push(new TypoString(params.type.content, typoStyleLogic));
+  }
+  return errorText;
+}
+
+function setupOptionAliased(
   readerOptions: ReaderOptions,
-  definition: {
-    long: string;
-    short: undefined | string;
-    aliasesLongs: undefined | Array<string>;
-    aliasesShorts: undefined | Array<string>;
-    parsing: ReaderOptionParsing;
+  params: {
+    longKey: string;
+    shortKey: string | undefined;
+    aliasLongKeys: Array<string> | undefined;
+    aliasShortKeys: Array<string> | undefined;
+    restGuard: ReaderOptionRestGuard;
+    nextGuard: ReaderOptionNextGuard;
   },
-) {
-  const { long, short, aliasesLongs, aliasesShorts, parsing } = definition;
-  const longs = long ? [long] : [];
-  if (aliasesLongs) {
-    longs.push(...aliasesLongs);
+): () => Array<{ identifier: string; value: ReaderOptionValue }> {
+  const { longKey, shortKey, aliasLongKeys, aliasShortKeys } = params;
+  const longKeys = [longKey];
+  if (aliasLongKeys !== undefined) {
+    longKeys.push(...aliasLongKeys);
   }
-  const shorts = short ? [short] : [];
-  if (aliasesShorts) {
-    shorts.push(...aliasesShorts);
+  const shortKeys = shortKey ? [shortKey] : [];
+  if (aliasShortKeys !== undefined) {
+    shortKeys.push(...aliasShortKeys);
   }
-  return readerOptions.registerOption({ longs, shorts, parsing });
+  return setupOptionMany(readerOptions, {
+    longKeys,
+    shortKeys,
+    restGuard: params.restGuard,
+    nextGuard: params.nextGuard,
+  });
 }
 
-function throwSetMultipleTimesError(long: string): never {
-  throw new TypoError(
-    new TypoText(
-      new TypoString(`--${long}`, typoStyleConstants),
-      new TypoString(`: Must not be set multiple times`),
-    ),
-  );
+function setupOptionMany(
+  readerOptions: ReaderOptions,
+  params: {
+    longKeys: Array<string>;
+    shortKeys: Array<string>;
+    restGuard: ReaderOptionRestGuard;
+    nextGuard: ReaderOptionNextGuard;
+  },
+): () => Array<{ identifier: string; value: ReaderOptionValue }> {
+  const { longKeys, shortKeys, restGuard, nextGuard } = params;
+  const getters = new Array<ReaderOptionGetter>();
+  for (const key of longKeys) {
+    getters.push(readerOptions.registerOptionLong({ key, nextGuard }));
+  }
+  for (const key of shortKeys) {
+    getters.push(
+      readerOptions.registerOptionShort({ key, restGuard, nextGuard }),
+    );
+  }
+  return () => {
+    const results = new Array();
+    for (const getter of getters) {
+      const { identifier, values } = getter();
+      for (const value of values) {
+        results.push({ identifier, value });
+      }
+    }
+    return results;
+  };
 }
 
-function throwFailedToGetDefaultValueError(
-  long: string,
-  error: unknown,
-  context: string,
-): never {
-  throw new TypoError(
-    new TypoText(
-      new TypoString(`--${long}`, typoStyleConstants),
-      new TypoString(`: Failed to get default value (${context})`),
-    ),
-    error,
+function throwSetMultipleTimesError(identifiers: Array<string>): never {
+  const identifiersTexts = Array.from(new Set(identifiers)).map(
+    (identifier) => new TypoString(identifier, typoStyleConstants),
   );
+  const errorText = new TypoText();
+  errorText.pushJoined(identifiersTexts, new TypoString(", "), 3);
+  errorText.push(new TypoString(`: Must not be set multiple times.`));
+  throw new TypoError(errorText);
 }

package/src/lib/Positional.ts

@@ -1,6 +1,12 @@
 import { ReaderPositionals } from "./Reader";
 import { Type } from "./Type";
-import { TypoError, TypoString, typoStyleUserInput, TypoText } from "./Typo";
+import {
+  TypoError,
+  TypoString,
+  typoStyleRegularWeaker,
+  typoStyleUserInput,
+  TypoText,
+} from "./Typo";
 import { UsagePositional } from "./Usage";
 
 /**
@@ -32,19 +38,25 @@ export type PositionalDecoder<Value> = {
   /**
    * Returns the decoded positional value.
    *
-   * @throws {@link TypoError} if decoding failed.
+   * @throws if decoding failed.
    */
   decodeValue(): Value;
 };
 
 /**
- * Creates a required positional — missing token throws {@link TypoError}.
+ * Creates a required positional — missing token throws.
+ *
+ * Syntax: `<type>`, e.g. `<NAME>`.
+ * Parsing logic:
+ * - "token" → decoded with `type.decoder("token")`
+ * - token missing → throws
  *
  * @typeParam Value - Type produced by the decoder.
  *
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
  * @param definition.type - Decoder for the raw token.
+ * @param definition.missing - Message shown when the token is missing.
  * @returns A {@link Positional}`<Value>`.
  *
  * @example
@@ -53,8 +65,6 @@ export type PositionalDecoder<Value> = {
  *   type: type("name"),
  *   description: "The name to greet",
  * });
- * // Usage:
- * //   my-cli Alice  →  "Alice"
  * ```
  */
 export function positionalRequired<Value>(definition: {
@@ -71,12 +81,15 @@ export function positionalRequired<Value>(definition: {
     consumeAndMakeDecoder(readerPositionals: ReaderPositionals) {
       const positional = readerPositionals.consumePositional();
       if (positional === undefined) {
-        throw new TypoError(
-          new TypoText(
-            new TypoString(label, typoStyleUserInput),
-            new TypoString(`: Is required, but was not provided`),
-          ),
-        );
+        const errorText = makeErrorText(label);
+        errorText.push(new TypoString(`: Is required, but was not provided.`));
+        if (description !== undefined) {
+          // TODO - should there be a dedicated hint here ?
+          errorText.push(
+            new TypoString(` (${description})`, typoStyleRegularWeaker),
+          );
+        }
+        throw new TypoError(errorText);
       }
       return {
         decodeValue() {
@@ -90,6 +103,11 @@ export function positionalRequired<Value>(definition: {
 /**
  * Creates an optional positional — absent token falls back to `default()`.
  *
+ * Syntax: `[type]`, e.g. `[NAME]`.
+ * Parsing logic:
+ * - "token" → decoded with `type.decoder("token")`
+ * - token missing → `default()`
+ *
  * @typeParam Value - Type produced by the decoder (or the default).
  *
  * @param definition.description - Help text.
@@ -102,12 +120,10 @@ export function positionalRequired<Value>(definition: {
  * ```ts
  * const greeteePositional = positionalOptional({
  *   type: type("name"),
- *   description: "Name to greet (default: world)",
+ *   description: "Name to greet",
+ *   hint: "Defaults to \"world\"",
  *   default: () => "world",
  * });
- * // Usage:
- * //   my-cli  →  "world"
- * //   my-cli Alice  →  "Alice"
  * ```
  */
 export function positionalOptional<Value>(definition: {
@@ -144,6 +160,12 @@ export function positionalOptional<Value>(definition: {
  * Creates a variadic positional that collects zero or more remaining tokens into an array.
  * Optionally stops at `endDelimiter` (consumed, not included).
  *
+ * Syntax: `[type]...`, e.g. `[NAME]...`.
+ * Parsing logic:
+ * - "a b ..." → decoded with `[type.decoder("a")`, `type.decoder("b"), ...]``
+ * - token missing → stops collection
+ * - endDelimiter encountered → stops collection
+ *
  * @typeParam Value - Type produced by the decoder for each token.
  *
  * @param definition.endDelimiter - Sentinel token that stops collection (consumed, not included).
@@ -158,9 +180,6 @@ export function positionalOptional<Value>(definition: {
  *   type: typePath(),
  *   description: "Files to process",
  * });
- * // Usage:
- * //   my-cli  →  []
- * //   my-cli a.ts b.ts c.ts  →  ["a.ts", "b.ts", "c.ts"]
  * ```
  */
 export function positionalVariadics<Value>(definition: {
@@ -212,11 +231,14 @@ function decodeValue<Value>(
   );
 }
 
+function makeErrorText(label: string): TypoText {
+  const errorText = new TypoText();
+  errorText.push(new TypoString(label, typoStyleUserInput));
+  return errorText;
+}
+
 function throwsWhenFailedToGetDefault(label: string): never {
-  throw new TypoError(
-    new TypoText(
-      new TypoString(label, typoStyleUserInput),
-      new TypoString(`: Failed to get default value`),
-    ),
-  );
+  const errorText = makeErrorText(label);
+  errorText.push(new TypoString(`: Failed to get default value.`));
+  throw new TypoError(errorText);
 }