@optique/core 0.10.0-dev.330 → 0.10.0-dev.332

package/dist/parser.js

@@ -1,3 +1,4 @@
+import { annotationKey } from "./annotations.js";
 import { message } from "./message.js";
 import { normalizeUsage } from "./usage.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
@@ -18,18 +19,25 @@ import { argument, command, constant, flag, option, passThrough } from "./primit
 *               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) {
+function parseSync(parser, args, options) {
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	do {
@@ -67,15 +75,22 @@ function parseSync(parser, args) {
 *               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) {
+async function parseAsync(parser, args, options) {
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	do {
@@ -117,12 +132,14 @@ async function parseAsync(parser, args) {
 *               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) {
-	if (parser.$mode === "async") return parseAsync(parser, args);
-	return parseSync(parser, args);
+function parse(parser, args, options) {
+	if (parser.$mode === "async") return parseAsync(parser, args, options);
+	return parseSync(parser, args, options);
 }
 /**
 * Generates command-line suggestions based on current parsing state.
@@ -138,6 +155,7 @@ function parse(parser, args) {
 * @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
@@ -157,14 +175,20 @@ function parse(parser, args) {
 * ```
 * @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) {
+function suggestSync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: allButLast,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	while (context.buffer.length > 0) {
@@ -190,17 +214,24 @@ function suggestSync(parser, args) {
 * @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) {
+async function suggestAsync(parser, args, options) {
 	const allButLast = args.slice(0, -1);
 	const prefix = args[args.length - 1];
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: allButLast,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	while (context.buffer.length > 0) {
@@ -235,13 +266,15 @@ async function suggestAsync(parser, args) {
 * @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) {
-	if (parser.$mode === "async") return suggestAsync(parser, args);
-	return suggestSync(parser, args);
+function suggest(parser, args, options) {
+	if (parser.$mode === "async") return suggestAsync(parser, args, options);
+	return suggestSync(parser, args, options);
 }
 /**
 * Recursively searches for a command within nested exclusive usage terms.
@@ -272,11 +305,13 @@ function findCommandInExclusive(term, commandName) {
 *
 * @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 = []) {
-	return getDocPageSyncImpl(parser, args);
+function getDocPageSync(parser, args = [], options) {
+	return getDocPageSyncImpl(parser, args, options);
 }
 /**
 * Generates a documentation page for any parser, returning a Promise.
@@ -287,25 +322,32 @@ function getDocPageSync(parser, args = []) {
 *
 * @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 = []) {
-	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args));
-	return getDocPageAsyncImpl(parser, args);
+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 = []) {
-	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args);
-	return getDocPageAsyncImpl(parser, args);
+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) {
+function getDocPageSyncImpl(parser, args, options) {
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	do {
@@ -318,11 +360,16 @@ function getDocPageSyncImpl(parser, args) {
 /**
 * Internal async implementation of getDocPage.
 */
-async function getDocPageAsyncImpl(parser, args) {
+async function getDocPageAsyncImpl(parser, args, options) {
+	let initialState = parser.initialState;
+	if (options?.annotations) initialState = {
+		...typeof initialState === "object" && initialState !== null ? initialState : {},
+		[annotationKey]: options.annotations
+	};
 	let context = {
 		buffer: args,
 		optionsTerminated: false,
-		state: parser.initialState,
+		state: initialState,
 		usage: parser.usage
 	};
 	do {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.10.0-dev.330+04823df7",
+  "version": "0.10.0-dev.332+be2882ab",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -51,6 +51,14 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./annotations": {
+      "types": {
+        "import": "./dist/annotations.d.ts",
+        "require": "./dist/annotations.d.cts"
+      },
+      "import": "./dist/annotations.js",
+      "require": "./dist/annotations.cjs"
+    },
     "./completion": {
       "types": {
         "import": "./dist/completion.d.ts",
@@ -59,6 +67,14 @@
       "import": "./dist/completion.js",
       "require": "./dist/completion.cjs"
     },
+    "./context": {
+      "types": {
+        "import": "./dist/context.d.ts",
+        "require": "./dist/context.d.cts"
+      },
+      "import": "./dist/context.js",
+      "require": "./dist/context.cjs"
+    },
     "./constructs": {
       "types": {
         "import": "./dist/constructs.d.ts",