@optique/core 1.0.0-dev.921 → 1.0.1

package/dist/parser.js

@@ -1,434 +1,3 @@
-import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
-import { message } from "./message.js";
-import { dispatchByMode } from "./mode-dispatch.js";
-import { normalizeUsage } from "./usage.js";
-import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
-import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
-import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
+import { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 
-//#region src/parser.ts
-function injectAnnotationsIntoState(state, options) {
-	const annotations = options?.annotations;
-	if (annotations == null) return state;
-	return 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 || 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: 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 ? 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 || 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: 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 ? 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 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 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 = [...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 = 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
-export { DuplicateOptionError, WithDefaultError, argument, command, concat, conditional, constant, fail, flag, getDocPage, getDocPageAsync, getDocPageSync, group, longestMatch, map, merge, multiple, nonEmpty, object, option, optional, or, parse, parseAsync, parseSync, passThrough, suggest, suggestAsync, suggestSync, tuple, withDefault };
+export { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync };

package/dist/phase2-seed.cjs

@@ -0,0 +1,59 @@
+const require_annotations = require('./internal/annotations.cjs');
+const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
+
+//#region src/phase2-seed.ts
+/**
+* Internal parser hook key for phase-two seed extraction.
+*
+* @internal
+*/
+const extractPhase2SeedKey = Symbol("@optique/core/extractPhase2Seed");
+/**
+* Converts a successful complete() result into a phase-two seed.
+*
+* @internal
+*/
+function phase2SeedFromValueResult(result) {
+	return {
+		value: require_annotations.unwrapInjectedAnnotationWrapper(result.value),
+		...result.deferred ? { deferred: true } : {},
+		...result.deferredKeys != null ? { deferredKeys: result.deferredKeys } : {}
+	};
+}
+/**
+* Invokes a parser's internal phase-two seed hook when present.
+*
+* @internal
+*/
+function extractPhase2Seed(parser, state, exec) {
+	return require_mode_dispatch.dispatchByMode(parser.mode, () => {
+		const extractor = parser[extractPhase2SeedKey];
+		return extractor == null ? null : extractor(state, exec);
+	}, async () => {
+		const extractor = parser[extractPhase2SeedKey];
+		return extractor == null ? null : await extractor(state, exec);
+	});
+}
+/**
+* Attempts to complete a parser and falls back to the internal phase-two
+* seed hook when completion returns an unsuccessful result.
+*
+* @internal
+*/
+function completeOrExtractPhase2Seed(parser, state, exec) {
+	return require_mode_dispatch.dispatchByMode(parser.mode, () => {
+		const result = parser.complete(state, exec);
+		if (result.success) return phase2SeedFromValueResult(result);
+		return extractPhase2Seed(parser, state, exec);
+	}, async () => {
+		const result = await parser.complete(state, exec);
+		if (result.success) return phase2SeedFromValueResult(result);
+		return await extractPhase2Seed(parser, state, exec);
+	});
+}
+
+//#endregion
+exports.completeOrExtractPhase2Seed = completeOrExtractPhase2Seed;
+exports.extractPhase2Seed = extractPhase2Seed;
+exports.extractPhase2SeedKey = extractPhase2SeedKey;
+exports.phase2SeedFromValueResult = phase2SeedFromValueResult;

package/dist/phase2-seed.js

@@ -0,0 +1,56 @@
+import { unwrapInjectedAnnotationWrapper } from "./internal/annotations.js";
+import { dispatchByMode } from "./internal/mode-dispatch.js";
+
+//#region src/phase2-seed.ts
+/**
+* Internal parser hook key for phase-two seed extraction.
+*
+* @internal
+*/
+const extractPhase2SeedKey = Symbol("@optique/core/extractPhase2Seed");
+/**
+* Converts a successful complete() result into a phase-two seed.
+*
+* @internal
+*/
+function phase2SeedFromValueResult(result) {
+	return {
+		value: unwrapInjectedAnnotationWrapper(result.value),
+		...result.deferred ? { deferred: true } : {},
+		...result.deferredKeys != null ? { deferredKeys: result.deferredKeys } : {}
+	};
+}
+/**
+* Invokes a parser's internal phase-two seed hook when present.
+*
+* @internal
+*/
+function extractPhase2Seed(parser, state, exec) {
+	return dispatchByMode(parser.mode, () => {
+		const extractor = parser[extractPhase2SeedKey];
+		return extractor == null ? null : extractor(state, exec);
+	}, async () => {
+		const extractor = parser[extractPhase2SeedKey];
+		return extractor == null ? null : await extractor(state, exec);
+	});
+}
+/**
+* Attempts to complete a parser and falls back to the internal phase-two
+* seed hook when completion returns an unsuccessful result.
+*
+* @internal
+*/
+function completeOrExtractPhase2Seed(parser, state, exec) {
+	return dispatchByMode(parser.mode, () => {
+		const result = parser.complete(state, exec);
+		if (result.success) return phase2SeedFromValueResult(result);
+		return extractPhase2Seed(parser, state, exec);
+	}, async () => {
+		const result = await parser.complete(state, exec);
+		if (result.success) return phase2SeedFromValueResult(result);
+		return await extractPhase2Seed(parser, state, exec);
+	});
+}
+
+//#endregion
+export { completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult };