cli-kiss 0.2.3 → 0.2.5

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,20 +8,19 @@ import {
   typoStyleUserInput,
   TypoText,
 } from "./Typo";
+import { UsageOption } from "./Usage";
 
 /**
- * A CLI option (flag or valued) with its parsing and usage-generation logic.
- *
- * Created with {@link optionFlag}, {@link optionSingleValue}, or
- * {@link optionRepeatable} and passed via the `options` map of {@link operation}.
+ * A CLI option. Created with {@link optionFlag}, {@link optionSingleValue},
+ * or {@link optionRepeatable}.
  *
  * @typeParam Value - Decoded value type.
  */
 export type Option<Value> = {
   /**
-   * Returns metadata used to render the `Options:` section of help.
+   * Returns metadata for the `Options:` section.
    */
-  generateUsage(): OptionUsage;
+  generateUsage(): UsageOption;
   /**
    * Registers the option on `readerOptions` and returns an {@link OptionDecoder}.
    */
@@ -42,46 +41,18 @@ export type OptionDecoder<Value> = {
   getAndDecodeValue(): Value;
 };
 
-/**
- * Human-readable metadata for a single option, used to render the `Options:` section
- * of the help output produced by {@link usageToStyledLines}.
- */
-export type OptionUsage = {
-  /**
-   * Long-form name without `--` (e.g. `"verbose"`).
-   */
-  long: Lowercase<string>;
-  /**
-   * Short-form name without `-` (e.g. `"v"`).
-   */
-  short: string | undefined;
-  /**
-   * Help text in usage.
-   */
-  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;
-};
-
 /**
  * Creates a boolean flag option (`--verbose`, optionally `--flag=no`).
  *
- * Parsing: absent → `false`; `--flag` / `--flag=yes` → `true`; `--flag=no` → `false`;
- * specified more than once → {@link TypoError}.
+ * Parsing: absent → default value; `--flag` / `--flag=yes` → `true`; `--flag=no` → `false`;
+ * specified more than once → throws {@link TypoError}.
  *
- * @param definition - Flag configuration.
  * @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`.
+ * @param definition.default - Default value when absent.
  * @returns An {@link Option}`<boolean>`.
  *
  * @example
@@ -91,64 +62,50 @@ export type OptionUsage = {
  *   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: {
-  long: Lowercase<string>;
+  long: string;
   short?: string;
   description?: string;
   hint?: string;
-  aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
-  default?: () => boolean;
+  aliases?: { longs?: Array<string>; shorts?: Array<string> };
+  default?: boolean;
 }): Option<boolean> {
-  const label = `<${typeBoolean.content.toUpperCase()}>`;
+  const type = typeBoolean("value");
+  const { long, short, description, hint, aliases } = definition;
   return {
     generateUsage() {
-      return {
-        description: definition.description,
-        hint: definition.hint,
-        long: definition.long,
-        short: definition.short,
-        label: undefined,
-      };
+      return { short, long, annotation: "[=no]", description, hint };
     },
     registerAndMakeDecoder(readerOptions: ReaderOptions) {
       const key = registerOption(readerOptions, {
-        ...definition,
-        valued: false,
+        long,
+        short,
+        aliasesLongs: aliases?.longs,
+        aliasesShorts: aliases?.shorts,
+        parsing: { consumeShortGroup: false, consumeNextArg: () => false },
       });
       return {
         getAndDecodeValue() {
-          const optionValues = readerOptions.getOptionValues(key);
-          if (optionValues.length > 1) {
-            throw new TypoError(
-              new TypoText(
-                new TypoString(`--${definition.long}`, typoStyleConstants),
-                new TypoString(`: Must not be set multiple times`),
-              ),
-            );
+          const optionResults = readerOptions.getOptionValues(key);
+          if (optionResults.length > 1) {
+            throwSetMultipleTimesError(long);
           }
-          const optionValue = optionValues[0];
-          if (optionValue === undefined) {
-            try {
-              return definition.default ? definition.default() : false;
-            } catch (error) {
-              throw new TypoError(
-                new TypoText(
-                  new TypoString(`--${definition.long}`, typoStyleConstants),
-                  new TypoString(`: Failed to get default value`),
-                ),
-                error,
-              );
-            }
+          if (optionResults.length === 0) {
+            return definition.default === undefined
+              ? false
+              : definition.default;
           }
-          return decodeValue({
-            long: definition.long,
-            short: definition.short,
-            label,
-            type: typeBoolean,
-            input: optionValue,
-          });
+          const positiveResult = optionResults[0]!;
+          const value =
+            positiveResult.inlined === null ? "true" : positiveResult.inlined;
+          return decodeValue({ long, short, type, input: value });
         },
       };
     },
@@ -158,20 +115,19 @@ export function optionFlag(definition: {
 /**
  * Creates an option that accepts exactly one value (e.g. `--output dist/`).
  *
- * Parsing: absent → `default()`; once → decoded with `type`; more than once → {@link TypoError}.
+ * Parsing: absent → `defaultValue()`; once → decoded with `type`; more than once → {@link TypoError}.
  * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
  *
  * @typeParam Value - Type produced by the decoder.
  *
- * @param definition - Option configuration.
  * @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.
+ * @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`).
  * @returns An {@link Option}`<Value>`.
  *
  * @example
@@ -179,71 +135,75 @@ export function optionFlag(definition: {
  * const outputOption = optionSingleValue({
  *   long: "output",
  *   short: "o",
- *   type: typeString,
- *   label: "PATH",
+ *   type: typePath(),
  *   description: "Output directory",
- *   default: () => "dist/",
+ *   valueWhenNotDefined: () => "dist",
  * });
+ * // Usage:
+ * //   my-cli  →  "dist"
+ * //   my-cli --output folder  →  "folder"
+ * //   my-cli -o folder  →  "folder"
  * ```
  */
 export function optionSingleValue<Value>(definition: {
-  long: Lowercase<string>;
+  long: string;
   short?: string;
   description?: string;
   hint?: string;
-  aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
-  label?: Uppercase<string>;
+  aliases?: { longs?: Array<string>; shorts?: Array<string> };
   type: Type<Value>;
-  default: () => Value;
+  defaultWhenNotDefined: () => Value;
+  defaultWhenNotInlined?: () => Value;
 }): Option<Value> {
-  const label = `<${definition.label ?? definition.type.content.toUpperCase()}>`;
+  const { long, short, description, hint, aliases, type } = definition;
+  const label = `<${type.content}>`;
   return {
     generateUsage() {
-      return {
-        description: definition.description,
-        hint: definition.hint,
-        long: definition.long,
-        short: definition.short,
-        label: label as Uppercase<string>,
-      };
+      return { short, long, label, description, hint };
     },
     registerAndMakeDecoder(readerOptions: ReaderOptions) {
       const key = registerOption(readerOptions, {
-        ...definition,
-        valued: true,
+        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;
+          },
+        },
       });
       return {
         getAndDecodeValue() {
-          const optionValues = readerOptions.getOptionValues(key);
-          if (optionValues.length > 1) {
-            throw new TypoError(
-              new TypoText(
-                new TypoString(`--${definition.long}`, typoStyleConstants),
-                new TypoString(`: Requires a single value, but got multiple`),
-              ),
-            );
+          const optionResults = readerOptions.getOptionValues(key);
+          if (optionResults.length > 1) {
+            throwSetMultipleTimesError(long);
           }
-          const optionValue = optionValues[0];
-          if (optionValue === undefined) {
+          const optionResult = optionResults[0];
+          if (optionResult === undefined) {
             try {
-              return definition.default();
+              return definition.defaultWhenNotDefined();
             } catch (error) {
-              throw new TypoError(
-                new TypoText(
-                  new TypoString(`--${definition.long}`, typoStyleConstants),
-                  new TypoString(`: Failed to get default value`),
-                ),
-                error,
-              );
+              throwFailedToGetDefaultValueError(long, error, "not set");
             }
           }
-          return decodeValue({
-            long: definition.long,
-            short: definition.short,
-            label,
-            type: definition.type,
-            input: optionValue,
-          });
+          if (optionResult.inlined) {
+            const inlined = optionResult.inlined;
+            return decodeValue({ long, short, label, type, input: inlined });
+          }
+          if (definition.defaultWhenNotInlined !== undefined) {
+            try {
+              return definition.defaultWhenNotInlined();
+            } catch (error) {
+              throwFailedToGetDefaultValueError(long, error, "not inlined");
+            }
+          }
+          const separated = optionResult.separated[0]!;
+          return decodeValue({ long, short, label, type, input: separated });
         },
       };
     },
@@ -258,13 +218,11 @@ export function optionSingleValue<Value>(definition: {
  *
  * @typeParam Value - Type produced by the decoder for each occurrence.
  *
- * @param definition - Option configuration.
  * @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>>`.
  *
@@ -281,43 +239,38 @@ export function optionSingleValue<Value>(definition: {
  * ```
  */
 export function optionRepeatable<Value>(definition: {
-  long: Lowercase<string>;
+  long: string;
   short?: string;
   description?: string;
   hint?: string;
-  aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
-  label?: Uppercase<string>;
+  aliases?: { longs?: Array<string>; shorts?: Array<string> };
   type: Type<Value>;
 }): Option<Array<Value>> {
-  const label = `<${definition.label ?? definition.type.content.toUpperCase()}>`;
+  const { long, short, description, hint, aliases, type } = definition;
+  const label = `<${type.content}>`;
   return {
     generateUsage() {
-      // TODO - showcase that it can be repeated ?
-      return {
-        description: definition.description,
-        hint: definition.hint,
-        long: definition.long,
-        short: definition.short,
-        label: label as Uppercase<string>,
-      };
+      return { short, long, label, annotation: " [*]", description, hint };
     },
     registerAndMakeDecoder(readerOptions: ReaderOptions) {
       const key = registerOption(readerOptions, {
-        ...definition,
-        valued: true,
+        long,
+        short,
+        aliasesLongs: aliases?.longs,
+        aliasesShorts: aliases?.shorts,
+        parsing: {
+          consumeShortGroup: true,
+          consumeNextArg: (inlined, separated) =>
+            inlined === null && separated.length === 0,
+        },
       });
       return {
         getAndDecodeValue() {
-          const optionValues = readerOptions.getOptionValues(key);
-          return optionValues.map((optionValue) =>
-            decodeValue({
-              long: definition.long,
-              short: definition.short,
-              label,
-              type: definition.type,
-              input: optionValue,
-            }),
-          );
+          const optionResults = readerOptions.getOptionValues(key);
+          return optionResults.map((optionResult) => {
+            const input = optionResult.inlined ?? optionResult.separated[0]!;
+            return decodeValue({ long, short, label, type, input });
+          });
         },
       };
     },
@@ -326,8 +279,8 @@ export function optionRepeatable<Value>(definition: {
 
 function decodeValue<Value>(params: {
   long: string;
-  short: string | undefined;
-  label: string;
+  short?: string | undefined;
+  label?: string | undefined;
   type: Type<Value>;
   input: string;
 }): Value {
@@ -336,14 +289,17 @@ function decodeValue<Value>(params: {
     () => {
       const text = new TypoText();
       if (params.short) {
-        text.pushString(new TypoString(`-${params.short}`, typoStyleConstants));
-        text.pushString(new TypoString(`, `));
+        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));
       }
-      text.pushString(new TypoString(`--${params.long}`, typoStyleConstants));
-      text.pushString(new TypoString(`: `));
-      text.pushString(new TypoString(params.label, typoStyleUserInput));
-      text.pushString(new TypoString(`: `));
-      text.pushString(new TypoString(params.type.content, typoStyleLogic));
       return text;
     },
   );
@@ -352,20 +308,44 @@ function decodeValue<Value>(params: {
 function registerOption(
   readerOptions: ReaderOptions,
   definition: {
-    long: Lowercase<string>;
-    short?: string;
-    aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
-    valued: boolean;
+    long: string;
+    short: undefined | string;
+    aliasesLongs: undefined | Array<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 });
+}
+
+function throwSetMultipleTimesError(long: string): never {
+  throw new TypoError(
+    new TypoText(
+      new TypoString(`--${long}`, typoStyleConstants),
+      new TypoString(`: Must not be set multiple times`),
+    ),
+  );
+}
+
+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,
+  );
 }