feat: custom separators for variadic flags

Author: molisani

Diff for: docs/docs/features/argument-parsing/flags.mdx

@@ -151,6 +151,8 @@ import DefaultFlagCode from "./examples/default-flag.txt";
 
 A flag can be variadic when the type it represents is an array of values. In this case, the flag can be specified multiple times and each value is then parsed individually and added to a single array. If the type of a flag is an array it must be set as variadic.
 
+If the `variadic` config property is set to a string, Stricli will use that as a separator and split each input string. This is useful for cases where the input string is a single value that contains multiple values separated by a specific character (like a comma).
+
 import VariadicFlagCode from "./examples/variadic-flag.txt";
 
 <StricliPlayground filename="variadic-flag" rootExport="root" appName="run" defaultInput="--id 5 -i 10 -i 15">

Diff for: packages/core/src/parameter/flag/types.ts

@@ -120,7 +120,7 @@ export interface BaseEnumFlagParameter<T extends string> extends BaseFlagParamet
     readonly default?: T;
     readonly optional?: boolean;
     readonly hidden?: boolean;
-    readonly variadic?: boolean;
+    readonly variadic?: boolean | string;
 }
 
 interface RequiredEnumFlagParameter<T extends string> extends BaseEnumFlagParameter<T> {
@@ -169,8 +169,12 @@ interface OptionalVariadicEnumFlagParameter<T extends string> extends BaseEnumFl
     readonly hidden?: false;
     /**
      * Parameter extends array and must be set as variadic.
+     * Also supports using an arbitrary string as a separator for individual inputs.
+     * For example, `variadic: ","` will scan `--flag a,b,c` as `["a", "b", "c"]`.
+     * If no separator is provided, the default behavior is to parse the input as a single string.
+     * The separator cannot be the empty string or contain any whitespace.
      */
-    readonly variadic: true;
+    readonly variadic: true | string;
 }
 
 interface RequiredVariadicEnumFlagParameter<T extends string> extends BaseEnumFlagParameter<T> {
@@ -189,8 +193,12 @@ interface RequiredVariadicEnumFlagParameter<T extends string> extends BaseEnumFl
     readonly hidden?: false;
     /**
      * Parameter extends array and must be set as variadic.
+     * Also supports using an arbitrary string as a separator for individual inputs.
+     * For example, `variadic: ","` will scan `--flag a,b,c` as `["a", "b", "c"]`.
+     * If no separator is provided, the default behavior is to parse the input as a single string.
+     * The separator cannot be the empty string or contain any whitespace.
      */
-    readonly variadic: true;
+    readonly variadic: true | string;
 }
 
 export interface BaseParsedFlagParameter<T, CONTEXT extends CommandContext>
@@ -209,7 +217,7 @@ export interface BaseParsedFlagParameter<T, CONTEXT extends CommandContext>
      */
     readonly inferEmpty?: boolean;
     readonly optional?: boolean;
-    readonly variadic?: boolean;
+    readonly variadic?: boolean | string;
     readonly hidden?: boolean;
 }
 
@@ -271,8 +279,12 @@ interface OptionalVariadicParsedFlagParameter<T, CONTEXT extends CommandContext>
     readonly optional: true;
     /**
      * Parameter extends array and must be set as variadic.
+     * Also supports using an arbitrary string as a separator for individual inputs.
+     * For example, `variadic: ","` will scan `--flag a,b,c` as `["a", "b", "c"]`.
+     * If no separator is provided, the default behavior is to parse the input as a single string.
+     * The separator cannot be the empty string or contain any whitespace.
      */
-    readonly variadic: true;
+    readonly variadic: true | string;
     /**
      * Default values are not supported for variadic parameters.
      */
@@ -288,8 +300,12 @@ interface RequiredVariadicParsedFlagParameter<T, CONTEXT extends CommandContext>
     readonly optional?: false;
     /**
      * Parameter extends array and must be set as variadic.
+     * Also supports using an arbitrary string as a separator for individual inputs.
+     * For example, `variadic: ","` will scan `--flag a,b,c` as `["a", "b", "c"]`.
+     * If no separator is provided, the default behavior is to parse the input as a single string.
+     * The separator cannot be the empty string or contain any whitespace.
      */
-    readonly variadic: true;
+    readonly variadic: true | string;
     /**
      * Default values are not supported for variadic parameters.
      */

Diff for: packages/core/src/parameter/scanner.ts

@@ -632,16 +632,21 @@ function isVariadicFlag<CONTEXT extends CommandContext>(flag: FlagParameter<CONT
 function storeInput<CONTEXT extends CommandContext>(
     flagInputs: Map<InternalFlagName, ArgumentInputs>,
     scannerCaseStyle: ScannerCaseStyle,
-    namedFlag: NamedFlag<CONTEXT, FlagParameter<CONTEXT>>,
+    [internalFlagName, flag]: NamedFlag<CONTEXT, FlagParameter<CONTEXT>>,
     input: string,
 ) {
-    const inputs = flagInputs.get(namedFlag[0]) ?? [];
-    if (inputs.length > 0 && !isVariadicFlag(namedFlag[1])) {
-        const externalFlagName = asExternal(namedFlag[0], scannerCaseStyle);
+    const inputs = flagInputs.get(internalFlagName) ?? [];
+    if (inputs.length > 0 && !isVariadicFlag(flag)) {
+        const externalFlagName = asExternal(internalFlagName, scannerCaseStyle);
         // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
         throw new UnexpectedFlagError(externalFlagName, inputs[0]!, input);
     }
-    flagInputs.set(namedFlag[0], [...inputs, input]);
+    if ("variadic" in flag && typeof flag.variadic === "string") {
+        const multipleInputs = input.split(flag.variadic) as unknown as ArgumentInputs;
+        flagInputs.set(internalFlagName, [...inputs, ...multipleInputs]);
+    } else {
+        flagInputs.set(internalFlagName, [...inputs, input]);
+    }
 }
 
 function isFlagSatisfiedByInputs(
@@ -858,24 +863,7 @@ export function buildArgumentScanner<FLAGS extends BaseFlags, ARGS extends BaseA
         },
         proposeCompletions: async ({ partial, completionConfig, text, context, includeVersionFlag }) => {
             if (activeFlag) {
-                const flag = activeFlag[1];
-                let values: readonly string[];
-                if (flag.kind === "enum") {
-                    values = flag.values;
-                } else if (flag.proposeCompletions) {
-                    values = await flag.proposeCompletions.call(context, partial);
-                } else {
-                    values = [];
-                }
-                return values
-                    .map<ArgumentCompletion>((value) => {
-                        return {
-                            kind: "argument:value",
-                            completion: value,
-                            brief: flag.brief,
-                        };
-                    })
-                    .filter(({ completion }) => completion.startsWith(partial));
+                return proposeFlagCompletionsForPartialInput<CONTEXT>(activeFlag[1], context, partial);
             }
             const completions: ArgumentCompletion[] = [];
             if (!treatInputsAsArguments) {
@@ -1016,6 +1004,35 @@ export function buildArgumentScanner<FLAGS extends BaseFlags, ARGS extends BaseA
     };
 }
 
+async function proposeFlagCompletionsForPartialInput<CONTEXT extends CommandContext>(
+    flag: FlagParserExpectingInput<CONTEXT>,
+    context: CONTEXT,
+    partial: string,
+) {
+    if (typeof flag.variadic === "string") {
+        if (partial.endsWith(flag.variadic)) {
+            return proposeFlagCompletionsForPartialInput(flag, context, "");
+        }
+    }
+    let values: readonly string[];
+    if (flag.kind === "enum") {
+        values = flag.values;
+    } else if (flag.proposeCompletions) {
+        values = await flag.proposeCompletions.call(context, partial);
+    } else {
+        values = [];
+    }
+    return values
+        .map<ArgumentCompletion>((value) => {
+            return {
+                kind: "argument:value",
+                completion: value,
+                brief: flag.brief,
+            };
+        })
+        .filter(({ completion }) => completion.startsWith(partial));
+}
+
 /**
  * @internal
  */

Diff for: packages/core/src/routing/command/builder.ts

@@ -74,6 +74,23 @@ function checkForNegationCollisions(flags: Record<string, FlagParameter<CommandC
     }
 }
 
+function checkForInvalidVariadicSeparators(flags: Record<string, FlagParameter<CommandContext>>): void {
+    for (const [internalFlagName, flag] of Object.entries(flags)) {
+        if ("variadic" in flag && typeof flag.variadic === "string") {
+            if (flag.variadic.length < 1) {
+                throw new InternalError(
+                    `Unable to use "" as variadic separator for --${internalFlagName} as it is empty`,
+                );
+            }
+            if (/\s/.test(flag.variadic)) {
+                throw new InternalError(
+                    `Unable to use "${flag.variadic}" as variadic separator for --${internalFlagName} as it contains whitespace`,
+                );
+            }
+        }
+    }
+}
+
 /**
  * Build command from loader or local function as action with associated parameters and documentation.
  */
@@ -89,6 +106,7 @@ export function buildCommand<
     checkForReservedFlags(flags, ["help", "helpAll", "help-all"]);
     checkForReservedAliases(aliases, ["h", "H"]);
     checkForNegationCollisions(flags);
+    checkForInvalidVariadicSeparators(flags);
     let loader: CommandFunctionLoader<BaseFlags, BaseArgs, CONTEXT>;
     if ("func" in builderArgs) {
         loader = async () => builderArgs.func as CommandFunction<BaseFlags, BaseArgs, CONTEXT>;