cli-kiss 0.2.2 → 0.2.4

package/src/lib/Option.ts

@@ -1,4 +1,4 @@
-import { ReaderArgs as ReaderOptions } from "./Reader";
+import { ReaderOptionParsing, ReaderArgs as ReaderOptions } from "./Reader";
 import { Type, typeBoolean } from "./Type";
 import {
   TypoError,
@@ -8,91 +8,51 @@ import {
   typoStyleUserInput,
   TypoText,
 } from "./Typo";
+import { UsageOption } from "./Usage";
 
 /**
- * Describes a single CLI option (a flag or a valued option) together with its parsing
- * and usage-generation logic.
+ * A CLI option. Created with {@link optionFlag}, {@link optionSingleValue},
+ * or {@link optionRepeatable}.
  *
- * Options are created with {@link optionFlag}, {@link optionSingleValue}, or
- * {@link optionRepeatable} and are passed via the `options` map of {@link operation}.
- *
- * @typeParam Value - The TypeScript type of the parsed option value.
- *   - `boolean` for flags created with {@link optionFlag}.
- *   - `T` for single-value options created with {@link optionSingleValue}.
- *   - `Array<T>` for repeatable options created with {@link optionRepeatable}.
+ * @typeParam Value - Decoded value type.
  */
 export type Option<Value> = {
-  /** Returns human-readable metadata used to render the `Options:` section of help. */
-  generateUsage(): OptionUsage;
   /**
-   * Registers the option on `readerOptions` so the argument reader recognises it, and
-   * returns an {@link OptionParser} that can later retrieve the parsed value(s).
-   *
-   * @param readerOptions - The shared {@link ReaderArgs} that will parse the raw
-   *   command-line tokens.
+   * Returns metadata for the `Options:` section.
    */
-  createParser(readerOptions: ReaderOptions): OptionParser<Value>;
+  generateUsage(): UsageOption;
+  /**
+   * Registers the option on `readerOptions` and returns an {@link OptionDecoder}.
+   */
+  registerAndMakeDecoder(readerOptions: ReaderOptions): OptionDecoder<Value>;
 };
 
 /**
- * Retrieves the parsed value for a registered option after argument parsing is complete.
- *
- * Returned by {@link Option.createParser} and called by {@link OperationFactory.createInstance}.
+ * Produced by {@link Option.registerAndMakeDecoder}.
  *
- * @typeParam Value - The TypeScript type of the parsed value.
- */
-export type OptionParser<Value> = {
-  parseValue(): Value;
-};
-
-/**
- * Human-readable metadata for a single CLI option, used to render the `Options:` section
- * of the help output produced by {@link usageToStyledLines}.
+ * @typeParam Value - Decoded value type.
  */
-export type OptionUsage = {
-  /** Short description of what the option does. */
-  description: string | undefined;
+export type OptionDecoder<Value> = {
   /**
-   * Optional supplementary note shown in parentheses next to the description.
-   * Suitable for short caveats such as `"required"` or `"defaults to 42"`.
-   */
-  hint: string | undefined;
-  /**
-   * The primary long-form name of the option, without the `--` prefix (e.g. `"verbose"`).
-   * The user passes this as `--verbose` on the command line.
-   */
-  long: Lowercase<string>; // TODO - better type for long option names ?
-  /**
-   * The optional short-form name of the option, without the `-` prefix (e.g. `"v"`).
-   * The user passes this as `-v` on the command line.
-   */
-  short: string | undefined;
-  /**
-   * The value placeholder label shown after the long option name in the help output
-   * (e.g. `"<FILE>"`). `undefined` for flags that take no value.
+   * Returns the decoded option value.
+   *
+   * @throws {@link TypoError} if decoding failed.
    */
-  label: Uppercase<string> | undefined;
+  getAndDecodeValue(): Value;
 };
 
 /**
- * Creates a boolean flag option — an option that the user passes without a value (e.g.
- * `--verbose`) to signal `true`, or can explicitly set with `--flag=true` / `--flag=no`.
+ * Creates a boolean flag option (`--verbose`, optionally `--flag=no`).
  *
- * **Parsing rules:**
- * - Absent → `false` (or the return value of `default()` when provided).
- * - `--flag` / `--flag=true` / `--flag=yes` → `true`.
- * - `--flag=false` / `--flag=no` → `false`.
- * - Specified more than once → {@link TypoError} ("Must not be set multiple times").
+ * Parsing: absent → `false`; `--flag` / `--flag=yes` → `true`; `--flag=no` → `false`;
+ * specified more than once → {@link TypoError}.
  *
- * @param definition - Configuration for the flag.
- * @param definition.long - Primary long-form name (without `--`). Must be lowercase.
- * @param definition.short - Optional short-form name (without `-`).
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.aliases - Additional long/short names that the parser also
- *   recognises as this flag.
- * @param definition.default - Factory for the default value when the flag is absent.
- *   Defaults to `() => false` when omitted.
+ * @param definition.long - Long-form name (without `--`).
+ * @param definition.short - Short-form name (without `-`).
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.aliases - Additional names.
+ * @param definition.default - Default when absent. Defaults to `false`.
  * @returns An {@link Option}`<boolean>`.
  *
  * @example
@@ -110,28 +70,44 @@ export function optionFlag(definition: {
   description?: string;
   hint?: string;
   aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
-  default?: () => boolean;
+  default?: boolean;
 }): Option<boolean> {
   const label = `<${typeBoolean.content.toUpperCase()}>`;
   return {
     generateUsage() {
       return {
-        description: definition.description,
-        hint: definition.hint,
-        long: definition.long,
         short: definition.short,
+        long: definition.long,
         label: undefined,
+        annotation: "[=no]",
+        description: definition.description,
+        hint: definition.hint,
       };
     },
-    createParser(readerOptions: ReaderOptions) {
-      const key = registerOption(readerOptions, {
-        ...definition,
-        valued: false,
+    registerAndMakeDecoder(readerOptions: ReaderOptions) {
+      const longNegative = `no-${definition.long}` as Lowercase<string>;
+      const aliasesLongsNegatives = definition.aliases?.longs?.map(
+        (aliasLong) => `no-${aliasLong}` as Lowercase<string>,
+      );
+      const keyNegative = registerOption(readerOptions, {
+        long: longNegative,
+        short: undefined,
+        aliasesShorts: undefined,
+        aliasesLongs: aliasesLongsNegatives,
+        parsing: { consumeShortGroup: false, consumeNextArg: () => false },
+      });
+      const keyPositive = registerOption(readerOptions, {
+        long: definition.long,
+        short: definition.short,
+        aliasesLongs: definition.aliases?.longs,
+        aliasesShorts: definition.aliases?.shorts,
+        parsing: { consumeShortGroup: false, consumeNextArg: () => false },
       });
       return {
-        parseValue() {
-          const optionValues = readerOptions.getOptionValues(key);
-          if (optionValues.length > 1) {
+        getAndDecodeValue() {
+          const negativeResults = readerOptions.getOptionValues(keyNegative);
+          const positiveResults = readerOptions.getOptionValues(keyPositive);
+          if (positiveResults.length > 1) {
             throw new TypoError(
               new TypoText(
                 new TypoString(`--${definition.long}`, typoStyleConstants),
@@ -139,21 +115,49 @@ export function optionFlag(definition: {
               ),
             );
           }
-          const optionValue = optionValues[0];
-          if (optionValue === undefined) {
-            try {
-              return definition.default ? definition.default() : false;
-            } catch (error) {
+          if (negativeResults.length > 1) {
+            throw new TypoError(
+              new TypoText(
+                new TypoString(`--${longNegative}`, typoStyleConstants),
+                new TypoString(`: Must not be set multiple times`),
+              ),
+            );
+          }
+          if (negativeResults.length > 0 && positiveResults.length > 0) {
+            throw new TypoError(
+              new TypoText(
+                new TypoString(`--${definition.long}`, typoStyleConstants),
+                new TypoString(`: Must not be set in combination with: `),
+                new TypoString(`--${longNegative}`, typoStyleConstants),
+              ),
+            );
+          }
+          if (negativeResults.length > 0) {
+            const negativeResult = negativeResults[0]!;
+            if (negativeResult.inlined) {
               throw new TypoError(
                 new TypoText(
-                  new TypoString(`--${definition.long}`, typoStyleConstants),
-                  new TypoString(`: Failed to get default value`),
+                  new TypoString(`--${longNegative}`, typoStyleConstants),
+                  new TypoString(`: Must not have a value`),
                 ),
-                error,
               );
             }
+            return false;
           }
-          return decodeValue(definition.long, label, typeBoolean, optionValue);
+          if (positiveResults.length > 0) {
+            const positiveResult = positiveResults[0]!;
+            return decodeValue({
+              long: definition.long,
+              short: definition.short,
+              label,
+              type: typeBoolean,
+              input:
+                positiveResult.inlined === null
+                  ? "true"
+                  : positiveResult.inlined,
+            });
+          }
+          return definition.default ?? false;
         },
       };
     },
@@ -161,32 +165,21 @@ export function optionFlag(definition: {
 }
 
 /**
- * Creates an option that accepts exactly one value (e.g. `--output dist/` or
- * `--output=dist/`).
- *
- * **Parsing rules:**
- * - Absent → `definition.default()` is called. If the default factory throws, a
- *   {@link TypoError} is produced.
- * - Specified once → the value is decoded with `definition.type`.
- * - Specified more than once → {@link TypoError} ("Requires a single value, but got
- *   multiple").
+ * Creates an option that accepts exactly one value (e.g. `--output dist/`).
  *
- * **Value syntax:** `--long value`, `--long=value`, or (if `short` is set) `-s value`,
- * `-s=value`, or `-svalue`.
+ * Parsing: absent → `default()`; once → decoded with `type`; more than once → {@link TypoError}.
+ * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
  *
- * @typeParam Value - The TypeScript type produced by the type decoder.
+ * @typeParam Value - Type produced by the decoder.
  *
- * @param definition - Configuration for the option.
- * @param definition.long - Primary long-form name (without `--`). Must be lowercase.
- * @param definition.short - Optional short-form name (without `-`).
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.aliases - Additional long/short names the parser also recognises.
- * @param definition.label - Custom label shown in the help output (e.g. `"FILE"`).
- *   Defaults to the uppercased `type.content`.
- * @param definition.type - The {@link Type} used to decode the raw string value.
- * @param definition.default - Factory for the default value when the option is absent.
- *   Throw an error from this factory to make the option effectively required.
+ * @param definition.long - Long-form name (without `--`).
+ * @param definition.short - Short-form name (without `-`).
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.aliases - Additional names.
+ * @param definition.label - Value placeholder in help. Defaults to uppercased `type.content`.
+ * @param definition.type - Decoder for the raw string value.
+ * @param definition.default - Default when absent. Throw to make the option required.
  * @returns An {@link Option}`<Value>`.
  *
  * @example
@@ -215,22 +208,30 @@ export function optionSingleValue<Value>(definition: {
   return {
     generateUsage() {
       return {
-        description: definition.description,
-        hint: definition.hint,
-        long: definition.long,
         short: definition.short,
+        long: definition.long,
         label: label as Uppercase<string>,
+        annotation: undefined,
+        description: definition.description,
+        hint: definition.hint,
       };
     },
-    createParser(readerOptions: ReaderOptions) {
+    registerAndMakeDecoder(readerOptions: ReaderOptions) {
       const key = registerOption(readerOptions, {
-        ...definition,
-        valued: true,
+        long: definition.long,
+        short: definition.short,
+        aliasesLongs: definition.aliases?.longs,
+        aliasesShorts: definition.aliases?.shorts,
+        parsing: {
+          consumeShortGroup: true,
+          consumeNextArg: (inlined, separated) =>
+            inlined === null && separated.length === 0,
+        },
       });
       return {
-        parseValue() {
-          const optionValues = readerOptions.getOptionValues(key);
-          if (optionValues.length > 1) {
+        getAndDecodeValue() {
+          const optionResults = readerOptions.getOptionValues(key);
+          if (optionResults.length > 1) {
             throw new TypoError(
               new TypoText(
                 new TypoString(`--${definition.long}`, typoStyleConstants),
@@ -238,8 +239,8 @@ export function optionSingleValue<Value>(definition: {
               ),
             );
           }
-          const optionValue = optionValues[0];
-          if (optionValue === undefined) {
+          const optionResult = optionResults[0];
+          if (optionResult === undefined) {
             try {
               return definition.default();
             } catch (error) {
@@ -252,12 +253,13 @@ export function optionSingleValue<Value>(definition: {
               );
             }
           }
-          return decodeValue(
-            definition.long,
+          return decodeValue({
+            long: definition.long,
+            short: definition.short,
             label,
-            definition.type,
-            optionValue,
-          );
+            type: definition.type,
+            input: optionResult.inlined ?? optionResult.separated[0]!,
+          });
         },
       };
     },
@@ -265,30 +267,20 @@ export function optionSingleValue<Value>(definition: {
 }
 
 /**
- * Creates an option that can be specified any number of times, collecting all provided
- * values into an array (e.g. `--file a.ts --file b.ts`).
- *
- * **Parsing rules:**
- * - Absent → empty array `[]`.
- * - Specified N times → array of N decoded values, in the order they appear on the
- *   command line.
- * - Each occurrence is decoded independently with `definition.type`.
+ * Creates an option that collects every occurrence into an array (e.g. `--file a.ts --file b.ts`).
  *
- * **Value syntax:** `--long value`, `--long=value`, or (if `short` is set) `-s value`,
- * `-s=value`, or `-svalue`.
+ * Parsing: absent → `[]`; N occurrences → array of N decoded values in order.
+ * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
  *
- * @typeParam Value - The TypeScript type produced by the type decoder for each
- *   occurrence.
+ * @typeParam Value - Type produced by the decoder for each occurrence.
  *
- * @param definition - Configuration for the option.
- * @param definition.long - Primary long-form name (without `--`). Must be lowercase.
- * @param definition.short - Optional short-form name (without `-`).
- * @param definition.description - Human-readable description for the help output.
- * @param definition.hint - Optional supplementary note shown in parentheses.
- * @param definition.aliases - Additional long/short names the parser also recognises.
- * @param definition.label - Custom label shown in the help output (e.g. `"FILE"`).
- *   Defaults to the uppercased `type.content`.
- * @param definition.type - The {@link Type} used to decode each raw string value.
+ * @param definition.long - Long-form name (without `--`).
+ * @param definition.short - Short-form name (without `-`).
+ * @param definition.description - Help text.
+ * @param definition.hint - Short note shown in parentheses.
+ * @param definition.aliases - Additional names.
+ * @param definition.label - Value placeholder in help. Defaults to uppercased `type.content`.
+ * @param definition.type - Decoder applied to each raw string value.
  * @returns An {@link Option}`<Array<Value>>`.
  *
  * @example
@@ -317,23 +309,37 @@ export function optionRepeatable<Value>(definition: {
     generateUsage() {
       // TODO - showcase that it can be repeated ?
       return {
-        description: definition.description,
-        hint: definition.hint,
-        long: definition.long,
         short: definition.short,
+        long: definition.long,
         label: label as Uppercase<string>,
+        annotation: " [*]",
+        description: definition.description,
+        hint: definition.hint,
       };
     },
-    createParser(readerOptions: ReaderOptions) {
+    registerAndMakeDecoder(readerOptions: ReaderOptions) {
       const key = registerOption(readerOptions, {
-        ...definition,
-        valued: true,
+        long: definition.long,
+        short: definition.short,
+        aliasesLongs: definition.aliases?.longs,
+        aliasesShorts: definition.aliases?.shorts,
+        parsing: {
+          consumeShortGroup: true,
+          consumeNextArg: (inlined, separated) =>
+            inlined === null && separated.length === 0,
+        },
       });
       return {
-        parseValue() {
-          const optionValues = readerOptions.getOptionValues(key);
-          return optionValues.map((optionValue) =>
-            decodeValue(definition.long, label, definition.type, optionValue),
+        getAndDecodeValue() {
+          const optionResults = readerOptions.getOptionValues(key);
+          return optionResults.map((optionResult) =>
+            decodeValue({
+              long: definition.long,
+              short: definition.short,
+              label,
+              type: definition.type,
+              input: optionResult.inlined ?? optionResult.separated[0]!,
+            }),
           );
         },
       };
@@ -341,22 +347,28 @@ export function optionRepeatable<Value>(definition: {
   };
 }
 
-function decodeValue<Value>(
-  long: string,
-  label: string,
-  type: Type<Value>,
-  value: string,
-): Value {
+function decodeValue<Value>(params: {
+  long: string;
+  short: string | undefined;
+  label: string;
+  type: Type<Value>;
+  input: string;
+}): Value {
   return TypoError.tryWithContext(
-    () => type.decoder(value),
-    () =>
-      new TypoText(
-        new TypoString(`--${long}`, typoStyleConstants),
-        new TypoString(`: `),
-        new TypoString(label, typoStyleUserInput),
-        new TypoString(`: `),
-        new TypoString(type.content, typoStyleLogic),
-      ),
+    () => 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));
+      text.push(new TypoString(`: `));
+      text.push(new TypoString(params.label, typoStyleUserInput));
+      text.push(new TypoString(`: `));
+      text.push(new TypoString(params.type.content, typoStyleLogic));
+      return text;
+    },
   );
 }
 
@@ -364,19 +376,20 @@ function registerOption(
   readerOptions: ReaderOptions,
   definition: {
     long: Lowercase<string>;
-    short?: string;
-    aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
-    valued: boolean;
+    short: undefined | string;
+    aliasesLongs: undefined | Array<Lowercase<string>>;
+    aliasesShorts: undefined | Array<string>;
+    parsing: ReaderOptionParsing;
   },
 ) {
-  const { long, short, aliases, valued } = definition;
+  const { long, short, aliasesLongs, aliasesShorts, parsing } = definition;
   const longs = long ? [long] : [];
-  if (aliases?.longs) {
-    longs.push(...aliases?.longs);
+  if (aliasesLongs) {
+    longs.push(...aliasesLongs);
   }
   const shorts = short ? [short] : [];
-  if (aliases?.shorts) {
-    shorts.push(...aliases?.shorts);
+  if (aliasesShorts) {
+    shorts.push(...aliasesShorts);
   }
-  return readerOptions.registerOption({ longs, shorts, valued });
+  return readerOptions.registerOption({ longs, shorts, parsing });
 }