@optique/core 1.0.0-dev.908 → 1.0.0

package/dist/parser.cjs

@@ -1,464 +1,12 @@
-const require_annotations = require('./annotations.cjs');
-const require_message = require('./message.cjs');
-const require_mode_dispatch = require('./mode-dispatch.cjs');
-const require_usage = require('./usage.cjs');
-const require_constructs = require('./constructs.cjs');
-const require_modifiers = require('./modifiers.cjs');
-const require_primitives = require('./primitives.cjs');
+const require_parser = require('./internal/parser.cjs');
 
-//#region src/parser.ts
-function injectAnnotationsIntoState(state, options) {
-	const annotations = options?.annotations;
-	if (annotations == null) return state;
-	return require_annotations.injectAnnotations(state, annotations);
-}
-/**
-* 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.  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.
-* @param options Optional {@link ParseOptions} for customizing parsing behavior.
-* @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.
-* @since 0.10.0 Added optional `options` parameter for annotations support.
-*/
-function parseSync(parser, args, options) {
-	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = options?.annotations != null || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
-	let context = {
-		buffer: args,
-		optionsTerminated: false,
-		state: initialState,
-		usage: parser.usage
-	};
-	do {
-		const result = 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: require_message.message`Unexpected option or argument: ${context.buffer[0]}.`
-		};
-	} while (context.buffer.length > 0);
-	const endResult = parser.complete(context.state);
-	return endResult.success ? {
-		success: true,
-		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.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.
-*
-* 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.
-* @param options Optional {@link ParseOptions} for customizing parsing behavior.
-* @returns A Promise that resolves to a {@link Result} object indicating
-*          whether the parsing was successful or not.
-* @since 0.9.0
-* @since 0.10.0 Added optional `options` parameter for annotations support.
-*/
-async function parseAsync(parser, args, options) {
-	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	const shouldUnwrapAnnotatedValue = options?.annotations != null || require_annotations.isInjectedAnnotationWrapper(parser.initialState);
-	let context = {
-		buffer: args,
-		optionsTerminated: false,
-		state: 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: require_message.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: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.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.
-* @param options Optional {@link ParseOptions} for customizing parsing behavior.
-* @returns A {@link Result} object (for sync) or Promise thereof (for async)
-*          indicating whether the parsing was successful or not.
-* @since 0.10.0 Added optional `options` parameter for annotations support.
-*/
-function parse(parser, args, options) {
-	return require_mode_dispatch.dispatchByMode(parser.$mode, () => parseSync(parser, args, options), () => parseAsync(parser, args, options));
-}
-/**
-* 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.
-* @param options Optional {@link ParseOptions} for customizing parsing behavior.
-* @returns An array of {@link Suggestion} objects containing completion
-*          candidates.
-* @example
-* ```typescript
-* const parser = object({
-*   verbose: option("-v", "--verbose"),
-*   format: option("-f", "--format", choice(["json", "yaml"]))
-* });
-*
-* // Get suggestions for options starting with "--"
-* const suggestions = suggestSync(parser, ["--"]);
-* // Returns: [{ text: "--verbose" }, { text: "--format" }]
-*
-* // Get suggestions after parsing some arguments
-* 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.
-* @since 0.10.0 Added optional `options` parameter for annotations support.
-*/
-function suggestSync(parser, args, options) {
-	const allButLast = args.slice(0, -1);
-	const prefix = args[args.length - 1];
-	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	let context = {
-		buffer: allButLast,
-		optionsTerminated: false,
-		state: initialState,
-		usage: parser.usage
-	};
-	while (context.buffer.length > 0) {
-		const result = parser.parse(context);
-		if (!result.success) return Array.from(parser.suggest(context, prefix));
-		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 [];
-	}
-	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.
-* @param options Optional {@link ParseOptions} for customizing parsing behavior.
-* @returns A Promise that resolves to an array of {@link Suggestion} objects
-*          containing completion candidates.
-* @since 0.9.0
-* @since 0.10.0 Added optional `options` parameter for annotations support.
-*/
-async function suggestAsync(parser, args, options) {
-	const allButLast = args.slice(0, -1);
-	const prefix = args[args.length - 1];
-	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	let context = {
-		buffer: allButLast,
-		optionsTerminated: false,
-		state: 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.
-* @param options Optional {@link ParseOptions} for customizing parsing behavior.
-* @returns An array of {@link Suggestion} objects (for sync) or Promise thereof
-*          (for async) containing completion candidates.
-* @since 0.6.0
-* @since 0.10.0 Added optional `options` parameter for annotations support.
-*/
-function suggest(parser, args, options) {
-	return require_mode_dispatch.dispatchByMode(parser.$mode, () => suggestSync(parser, args, options), () => suggestAsync(parser, args, options));
-}
-/**
-* Recursively searches for a command within nested exclusive usage terms.
-* When the command is found, returns the expanded usage terms for that command.
-*
-* @param term The usage term to search in
-* @param commandName The command name to find
-* @returns The expanded usage terms if found, null otherwise
-*/
-function findCommandInExclusive(term, commandName) {
-	if (term.type !== "exclusive") return null;
-	for (const termGroup of term.terms) {
-		const firstTerm = termGroup[0];
-		if (firstTerm?.type === "command" && firstTerm.name === commandName) return termGroup;
-		if (firstTerm?.type === "exclusive") {
-			const found = findCommandInExclusive(firstTerm, commandName);
-			if (found) return [...found, ...termGroup.slice(1)];
-		}
-	}
-	return null;
-}
-/**
-* Generates a documentation page for a synchronous parser.
-*
-* This is the sync-specific version of {@link getDocPage}. It only accepts
-* sync parsers and returns the documentation page directly (not wrapped
-* in a Promise).
-*
-* @param parser The sync parser to generate documentation for.
-* @param args Optional array of command-line arguments for context.
-* @param options Optional {@link ParseOptions} for customizing parsing behavior.
-* @returns A {@link DocPage} or `undefined`.
-* @since 0.9.0
-* @since 0.10.0 Added optional `options` parameter for annotations support.
-*/
-function getDocPageSync(parser, args = [], options) {
-	return getDocPageSyncImpl(parser, args, options);
-}
-/**
-* Generates a documentation page for any parser, returning a Promise.
-*
-* This function accepts parsers of any mode (sync or async) and always
-* returns a Promise. Use this when working with parsers that may contain
-* async value parsers.
-*
-* @param parser The parser to generate documentation for.
-* @param args Optional array of command-line arguments for context.
-* @param options Optional {@link ParseOptions} for customizing parsing behavior.
-* @returns A Promise of {@link DocPage} or `undefined`.
-* @since 0.9.0
-* @since 0.10.0 Added optional `options` parameter for annotations support.
-*/
-function getDocPageAsync(parser, args = [], options) {
-	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args, options));
-	return getDocPageAsyncImpl(parser, args, options);
-}
-function getDocPage(parser, args = [], options) {
-	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args, options);
-	return getDocPageAsyncImpl(parser, args, options);
-}
-/**
-* Internal sync implementation of getDocPage.
-*/
-function getDocPageSyncImpl(parser, args, options) {
-	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	let context = {
-		buffer: args,
-		optionsTerminated: false,
-		state: initialState,
-		usage: parser.usage
-	};
-	while (context.buffer.length > 0) {
-		const result = parser.parse(context);
-		if (!result.success) break;
-		context = result.next;
-	}
-	return buildDocPage(parser, context, args);
-}
-/**
-* Internal async implementation of getDocPage.
-*/
-async function getDocPageAsyncImpl(parser, args, options) {
-	const initialState = injectAnnotationsIntoState(parser.initialState, options);
-	let context = {
-		buffer: args,
-		optionsTerminated: false,
-		state: initialState,
-		usage: parser.usage
-	};
-	while (context.buffer.length > 0) {
-		const result = await parser.parse(context);
-		if (!result.success) break;
-		context = result.next;
-	}
-	return buildDocPage(parser, context, args);
-}
-/**
-* Builds a DocPage from the parser and context.
-* Shared by both sync and async implementations.
-*/
-function buildDocPage(parser, context, args) {
-	const { brief, description, fragments, footer } = parser.getDocFragments({
-		kind: "available",
-		state: context.state
-	}, void 0);
-	const buildingSections = [];
-	let untitledSection = null;
-	const titledSectionMap = /* @__PURE__ */ new Map();
-	for (const fragment of fragments) if (fragment.type === "entry") {
-		if (untitledSection == null) {
-			untitledSection = { entries: [] };
-			buildingSections.push(untitledSection);
-		}
-		untitledSection.entries.push(fragment);
-	} else if (fragment.type === "section") if (fragment.title == null) {
-		if (untitledSection == null) {
-			untitledSection = { entries: [] };
-			buildingSections.push(untitledSection);
-		}
-		untitledSection.entries.push(...fragment.entries);
-	} else {
-		let section = titledSectionMap.get(fragment.title);
-		if (section == null) {
-			section = {
-				title: fragment.title,
-				entries: []
-			};
-			titledSectionMap.set(fragment.title, section);
-			buildingSections.push(section);
-		}
-		section.entries.push(...fragment.entries);
-	}
-	const sections = buildingSections;
-	const usage = [...require_usage.normalizeUsage(parser.usage)];
-	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
-		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
-		const defaultUsageLine = usage.slice(usageIndex + 1);
-		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
-		const normalizedCustomUsageLine = require_usage.normalizeUsage(customUsageLine);
-		usage.splice(usageIndex + 1, usage.length - (usageIndex + 1), ...normalizedCustomUsageLine);
-	};
-	let i = 0;
-	for (let argIndex = 0; argIndex < args.length; argIndex++) {
-		const arg = args[argIndex];
-		if (i >= usage.length) break;
-		let term = usage[i];
-		if (term.type === "exclusive") {
-			const found = findCommandInExclusive(term, arg);
-			if (found) {
-				usage.splice(i, 1, ...found);
-				term = usage[i];
-			}
-		}
-		maybeApplyCommandUsageLine(term, arg, argIndex === args.length - 1, i);
-		i++;
-	}
-	return {
-		usage,
-		sections,
-		...brief != null && { brief },
-		...description != null && { description },
-		...footer != null && { footer }
-	};
-}
-
-//#endregion
-exports.DuplicateOptionError = require_constructs.DuplicateOptionError;
-exports.WithDefaultError = require_modifiers.WithDefaultError;
-exports.argument = require_primitives.argument;
-exports.command = require_primitives.command;
-exports.concat = require_constructs.concat;
-exports.conditional = require_constructs.conditional;
-exports.constant = require_primitives.constant;
-exports.fail = require_primitives.fail;
-exports.flag = require_primitives.flag;
-exports.getDocPage = getDocPage;
-exports.getDocPageAsync = getDocPageAsync;
-exports.getDocPageSync = getDocPageSync;
-exports.group = require_constructs.group;
-exports.longestMatch = require_constructs.longestMatch;
-exports.map = require_modifiers.map;
-exports.merge = require_constructs.merge;
-exports.multiple = require_modifiers.multiple;
-exports.nonEmpty = require_modifiers.nonEmpty;
-exports.object = require_constructs.object;
-exports.option = require_primitives.option;
-exports.optional = require_modifiers.optional;
-exports.or = require_constructs.or;
-exports.parse = parse;
-exports.parseAsync = parseAsync;
-exports.parseSync = parseSync;
-exports.passThrough = require_primitives.passThrough;
-exports.suggest = suggest;
-exports.suggestAsync = suggestAsync;
-exports.suggestSync = suggestSync;
-exports.tuple = require_constructs.tuple;
-exports.withDefault = require_modifiers.withDefault;
+exports.createParserContext = require_parser.createParserContext;
+exports.getDocPage = require_parser.getDocPage;
+exports.getDocPageAsync = require_parser.getDocPageAsync;
+exports.getDocPageSync = require_parser.getDocPageSync;
+exports.parse = require_parser.parse;
+exports.parseAsync = require_parser.parseAsync;
+exports.parseSync = require_parser.parseSync;
+exports.suggest = require_parser.suggest;
+exports.suggestAsync = require_parser.suggestAsync;
+exports.suggestSync = require_parser.suggestSync;