@optique/core 0.9.0-dev.201 → 0.9.0-dev.202

package/dist/parser.js

@@ -9,17 +9,23 @@ import { argument, command, constant, flag, option, passThrough } from "./primit
 * Parses an array of command-line arguments using the provided combined parser.
 * This function processes the input arguments, applying the parser to each
 * argument until all arguments are consumed or an error occurs.
+*
+* This function only accepts synchronous parsers. For asynchronous parsers,
+* use {@link parseAsync}.
+*
 * @template T The type of the value produced by the parser.
 * @param parser The combined {@link Parser} to use for parsing the input
-*               arguments.
+*               arguments.  Must be a synchronous parser.
 * @param args The array of command-line arguments to parse.  Usually this is
 *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
 * @returns A {@link Result} object indicating whether the parsing was
 *          successful or not.  If successful, it contains the parsed value of
 *          type `T`.  If not, it contains an error message describing the
 *          failure.
+* @since 0.9.0 Renamed from the original `parse` function which now delegates
+*              to this for sync parsers.
 */
-function parse(parser, args) {
+function parseSync(parser, args) {
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
@@ -49,11 +55,86 @@ function parse(parser, args) {
 	};
 }
 /**
+* Parses an array of command-line arguments using the provided combined parser.
+* This function processes the input arguments, applying the parser to each
+* argument until all arguments are consumed or an error occurs.
+*
+* This function accepts any parser (sync or async) and always returns a Promise.
+* For synchronous parsing with sync parsers, use {@link parseSync} instead.
+*
+* @template T The type of the value produced by the parser.
+* @param parser The combined {@link Parser} to use for parsing the input
+*               arguments.
+* @param args The array of command-line arguments to parse.  Usually this is
+*             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+* @returns A Promise that resolves to a {@link Result} object indicating
+*          whether the parsing was successful or not.
+* @since 0.9.0
+*/
+async function parseAsync(parser, args) {
+	let context = {
+		buffer: args,
+		optionsTerminated: false,
+		state: parser.initialState,
+		usage: parser.usage
+	};
+	do {
+		const result = await parser.parse(context);
+		if (!result.success) return {
+			success: false,
+			error: result.error
+		};
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return {
+			success: false,
+			error: message`Unexpected option or argument: ${context.buffer[0]}.`
+		};
+	} while (context.buffer.length > 0);
+	const endResult = await parser.complete(context.state);
+	return endResult.success ? {
+		success: true,
+		value: endResult.value
+	} : {
+		success: false,
+		error: endResult.error
+	};
+}
+/**
+* Parses an array of command-line arguments using the provided combined parser.
+* This function processes the input arguments, applying the parser to each
+* argument until all arguments are consumed or an error occurs.
+*
+* The return type depends on the parser's mode:
+* - Sync parsers return `Result<T>` directly.
+* - Async parsers return `Promise<Result<T>>`.
+*
+* For explicit control, use {@link parseSync} or {@link parseAsync}.
+*
+* @template M The execution mode of the parser.
+* @template T The type of the value produced by the parser.
+* @param parser The combined {@link Parser} to use for parsing the input
+*               arguments.
+* @param args The array of command-line arguments to parse.  Usually this is
+*             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+* @returns A {@link Result} object (for sync) or Promise thereof (for async)
+*          indicating whether the parsing was successful or not.
+*/
+function parse(parser, args) {
+	if (parser.$mode === "async") return parseAsync(parser, args);
+	return parseSync(parser, args);
+}
+/**
 * Generates command-line suggestions based on current parsing state.
 * This function processes the input arguments up to the last argument,
 * then calls the parser's suggest method with the remaining prefix.
+*
+* This function only accepts synchronous parsers. For asynchronous parsers,
+* use {@link suggestAsync}.
+*
 * @template T The type of the value produced by the parser.
 * @param parser The {@link Parser} to use for generating suggestions.
+*               Must be a synchronous parser.
 * @param args The array of command-line arguments including the partial
 *             argument to complete.  The last element is treated as
 *             the prefix for suggestions.
@@ -67,16 +148,17 @@ function parse(parser, args) {
 * });
 *
 * // Get suggestions for options starting with "--"
-* const suggestions = suggest(parser, ["--"]);
+* const suggestions = suggestSync(parser, ["--"]);
 * // Returns: [{ text: "--verbose" }, { text: "--format" }]
 *
 * // Get suggestions after parsing some arguments
-* const suggestions2 = suggest(parser, ["-v", "--format="]);
+* const suggestions2 = suggestSync(parser, ["-v", "--format="]);
 * // Returns: [{ text: "--format=json" }, { text: "--format=yaml" }]
 * ```
 * @since 0.6.0
+* @since 0.9.0 Renamed from the original `suggest` function.
 */
-function suggest(parser, args) {
+function suggestSync(parser, args) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
 	let context = {
@@ -95,6 +177,73 @@ function suggest(parser, args) {
 	return Array.from(parser.suggest(context, prefix));
 }
 /**
+* Generates command-line suggestions based on current parsing state.
+* This function processes the input arguments up to the last argument,
+* then calls the parser's suggest method with the remaining prefix.
+*
+* This function accepts any parser (sync or async) and always returns a Promise.
+* For synchronous suggestion generation with sync parsers, use
+* {@link suggestSync} instead.
+*
+* @template T The type of the value produced by the parser.
+* @param parser The {@link Parser} to use for generating suggestions.
+* @param args The array of command-line arguments including the partial
+*             argument to complete.  The last element is treated as
+*             the prefix for suggestions.
+* @returns A Promise that resolves to an array of {@link Suggestion} objects
+*          containing completion candidates.
+* @since 0.9.0
+*/
+async function suggestAsync(parser, args) {
+	const allButLast = args.slice(0, -1);
+	const prefix = args[args.length - 1];
+	let context = {
+		buffer: allButLast,
+		optionsTerminated: false,
+		state: parser.initialState,
+		usage: parser.usage
+	};
+	while (context.buffer.length > 0) {
+		const result = await parser.parse(context);
+		if (!result.success) {
+			const suggestions$1 = [];
+			for await (const suggestion of parser.suggest(context, prefix)) suggestions$1.push(suggestion);
+			return suggestions$1;
+		}
+		const previousBuffer = context.buffer;
+		context = result.next;
+		if (context.buffer.length > 0 && context.buffer.length === previousBuffer.length && context.buffer.every((item, i) => item === previousBuffer[i])) return [];
+	}
+	const suggestions = [];
+	for await (const suggestion of parser.suggest(context, prefix)) suggestions.push(suggestion);
+	return suggestions;
+}
+/**
+* Generates command-line suggestions based on current parsing state.
+* This function processes the input arguments up to the last argument,
+* then calls the parser's suggest method with the remaining prefix.
+*
+* The return type depends on the parser's mode:
+* - Sync parsers return `readonly Suggestion[]` directly.
+* - Async parsers return `Promise<readonly Suggestion[]>`.
+*
+* For explicit control, use {@link suggestSync} or {@link suggestAsync}.
+*
+* @template M The execution mode of the parser.
+* @template T The type of the value produced by the parser.
+* @param parser The {@link Parser} to use for generating suggestions.
+* @param args The array of command-line arguments including the partial
+*             argument to complete.  The last element is treated as
+*             the prefix for suggestions.
+* @returns An array of {@link Suggestion} objects (for sync) or Promise thereof
+*          (for async) containing completion candidates.
+* @since 0.6.0
+*/
+function suggest(parser, args) {
+	if (parser.$mode === "async") return suggestAsync(parser, args);
+	return suggestSync(parser, args);
+}
+/**
 * Recursively searches for a command within nested exclusive usage terms.
 * When the command is found, returns the expanded usage terms for that command.
 *
@@ -193,4 +342,4 @@ function getDocPage(parser, args = []) {
 }
 
 //#endregion
-export { DuplicateOptionError, WithDefaultError, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, passThrough, suggest, tuple, withDefault };
+export { DuplicateOptionError, WithDefaultError, argument, command, concat, conditional, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };