@optique/core 1.0.0-dev.1523 → 1.0.0-dev.1531

package/dist/parser.cjs

@@ -299,14 +299,20 @@ function findCommandInExclusive(term, commandName) {
 * 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.
+* @param argsOrOptions Optional array of command-line arguments for context,
+*        or a {@link ParseOptions} object for annotations.  When a
+*        `ParseOptions` is passed here, the `options` parameter is ignored.
+* @param options Optional {@link ParseOptions} for customizing parsing
+*        behavior.  Only used when `argsOrOptions` is an array or omitted.
 * @returns A {@link DocPage} or `undefined`.
 * @since 0.9.0
 * @since 0.10.0 Added optional `options` parameter for annotations support.
+* @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+*              directly.
 */
-function getDocPageSync(parser, args = [], options) {
-	return getDocPageSyncImpl(parser, args, options);
+function getDocPageSync(parser, argsOrOptions, options) {
+	if (Array.isArray(argsOrOptions)) return getDocPageSyncImpl(parser, argsOrOptions, options);
+	return getDocPageSyncImpl(parser, [], argsOrOptions ?? options);
 }
 /**
 * Generates a documentation page for any parser, returning a Promise.
@@ -316,19 +322,28 @@ function getDocPageSync(parser, args = [], options) {
 * 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.
+* @param argsOrOptions Optional array of command-line arguments for context,
+*        or a {@link ParseOptions} object for annotations.  When a
+*        `ParseOptions` is passed here, the `options` parameter is ignored.
+* @param options Optional {@link ParseOptions} for customizing parsing
+*        behavior.  Only used when `argsOrOptions` is an array or omitted.
 * @returns A Promise of {@link DocPage} or `undefined`.
 * @since 0.9.0
 * @since 0.10.0 Added optional `options` parameter for annotations support.
+* @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+*              directly.
 */
-function getDocPageAsync(parser, args = [], options) {
-	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args, options));
-	return getDocPageAsyncImpl(parser, args, options);
+function getDocPageAsync(parser, argsOrOptions, options) {
+	const args = Array.isArray(argsOrOptions) ? argsOrOptions : [];
+	const opts = Array.isArray(argsOrOptions) ? options : argsOrOptions ?? options;
+	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args, opts));
+	return getDocPageAsyncImpl(parser, args, opts);
 }
-function getDocPage(parser, args = [], options) {
-	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args, options);
-	return getDocPageAsyncImpl(parser, args, options);
+function getDocPage(parser, argsOrOptions, options) {
+	const args = Array.isArray(argsOrOptions) ? argsOrOptions : [];
+	const opts = Array.isArray(argsOrOptions) ? options : argsOrOptions ?? options;
+	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args, opts);
+	return getDocPageAsyncImpl(parser, args, opts);
 }
 /**
 * Internal sync implementation of getDocPage.

package/dist/parser.d.cts

@@ -511,13 +511,18 @@ declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args:
  * 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.
+ * @param argsOrOptions Optional array of command-line arguments for context,
+ *        or a {@link ParseOptions} object for annotations.  When a
+ *        `ParseOptions` is passed here, the `options` parameter is ignored.
+ * @param options Optional {@link ParseOptions} for customizing parsing
+ *        behavior.  Only used when `argsOrOptions` is an array or omitted.
  * @returns A {@link DocPage} or `undefined`.
  * @since 0.9.0
  * @since 0.10.0 Added optional `options` parameter for annotations support.
+ * @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+ *              directly.
  */
-declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?: readonly string[], options?: ParseOptions): DocPage | undefined;
+declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): DocPage | undefined;
 /**
  * Generates a documentation page for any parser, returning a Promise.
  *
@@ -526,13 +531,18 @@ declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?:
  * 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.
+ * @param argsOrOptions Optional array of command-line arguments for context,
+ *        or a {@link ParseOptions} object for annotations.  When a
+ *        `ParseOptions` is passed here, the `options` parameter is ignored.
+ * @param options Optional {@link ParseOptions} for customizing parsing
+ *        behavior.  Only used when `argsOrOptions` is an array or omitted.
  * @returns A Promise of {@link DocPage} or `undefined`.
  * @since 0.9.0
  * @since 0.10.0 Added optional `options` parameter for annotations support.
+ * @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+ *              directly.
  */
-declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
+declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 /**
  * Generates a documentation page for a parser based on its current state after
  * attempting to parse the provided arguments. This function is useful for
@@ -548,10 +558,12 @@ declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?:
  * For async parsers, returns a Promise of the documentation page.
  *
  * @param parser The parser to generate documentation for
- * @param args Optional array of command-line arguments that have been parsed
- *             so far. Defaults to an empty array. This is used to determine
- *             the current parsing context and generate contextual documentation.
- * @param options Optional {@link ParseOptions} for customizing parsing behavior.
+ * @param argsOrOptions Optional array of command-line arguments that have been
+ *        parsed so far, or a {@link ParseOptions} object for annotations.
+ *        When a `ParseOptions` is passed here, the `options` parameter is
+ *        ignored.  Defaults to an empty array when omitted.
+ * @param options Optional {@link ParseOptions} for customizing parsing
+ *        behavior.  Only used when `argsOrOptions` is an array or omitted.
  * @returns For sync parsers, returns a {@link DocPage} directly.
  *          For async parsers, returns a Promise of {@link DocPage}.
  *          Returns `undefined` if no documentation can be generated.
@@ -571,9 +583,11 @@ declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?:
  * ```
  * @since 0.9.0 Updated to support async parsers.
  * @since 0.10.0 Added optional `options` parameter for annotations support.
+ * @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+ *              directly.
  */
-declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: readonly string[], options?: ParseOptions): DocPage | undefined;
-declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
-declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[], options?: ParseOptions): ModeValue<M, DocPage | undefined>;
+declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): DocPage | undefined;
+declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
+declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
 export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, 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 };

package/dist/parser.d.ts

@@ -511,13 +511,18 @@ declare function suggest<M extends Mode, T>(parser: Parser<M, T, unknown>, args:
  * 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.
+ * @param argsOrOptions Optional array of command-line arguments for context,
+ *        or a {@link ParseOptions} object for annotations.  When a
+ *        `ParseOptions` is passed here, the `options` parameter is ignored.
+ * @param options Optional {@link ParseOptions} for customizing parsing
+ *        behavior.  Only used when `argsOrOptions` is an array or omitted.
  * @returns A {@link DocPage} or `undefined`.
  * @since 0.9.0
  * @since 0.10.0 Added optional `options` parameter for annotations support.
+ * @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+ *              directly.
  */
-declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?: readonly string[], options?: ParseOptions): DocPage | undefined;
+declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): DocPage | undefined;
 /**
  * Generates a documentation page for any parser, returning a Promise.
  *
@@ -526,13 +531,18 @@ declare function getDocPageSync(parser: Parser<"sync", unknown, unknown>, args?:
  * 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.
+ * @param argsOrOptions Optional array of command-line arguments for context,
+ *        or a {@link ParseOptions} object for annotations.  When a
+ *        `ParseOptions` is passed here, the `options` parameter is ignored.
+ * @param options Optional {@link ParseOptions} for customizing parsing
+ *        behavior.  Only used when `argsOrOptions` is an array or omitted.
  * @returns A Promise of {@link DocPage} or `undefined`.
  * @since 0.9.0
  * @since 0.10.0 Added optional `options` parameter for annotations support.
+ * @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+ *              directly.
  */
-declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
+declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
 /**
  * Generates a documentation page for a parser based on its current state after
  * attempting to parse the provided arguments. This function is useful for
@@ -548,10 +558,12 @@ declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?:
  * For async parsers, returns a Promise of the documentation page.
  *
  * @param parser The parser to generate documentation for
- * @param args Optional array of command-line arguments that have been parsed
- *             so far. Defaults to an empty array. This is used to determine
- *             the current parsing context and generate contextual documentation.
- * @param options Optional {@link ParseOptions} for customizing parsing behavior.
+ * @param argsOrOptions Optional array of command-line arguments that have been
+ *        parsed so far, or a {@link ParseOptions} object for annotations.
+ *        When a `ParseOptions` is passed here, the `options` parameter is
+ *        ignored.  Defaults to an empty array when omitted.
+ * @param options Optional {@link ParseOptions} for customizing parsing
+ *        behavior.  Only used when `argsOrOptions` is an array or omitted.
  * @returns For sync parsers, returns a {@link DocPage} directly.
  *          For async parsers, returns a Promise of {@link DocPage}.
  *          Returns `undefined` if no documentation can be generated.
@@ -571,9 +583,11 @@ declare function getDocPageAsync(parser: Parser<Mode, unknown, unknown>, args?:
  * ```
  * @since 0.9.0 Updated to support async parsers.
  * @since 0.10.0 Added optional `options` parameter for annotations support.
+ * @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+ *              directly.
  */
-declare function getDocPage(parser: Parser<"sync", unknown, unknown>, args?: readonly string[], options?: ParseOptions): DocPage | undefined;
-declare function getDocPage(parser: Parser<"async", unknown, unknown>, args?: readonly string[], options?: ParseOptions): Promise<DocPage | undefined>;
-declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, args?: readonly string[], options?: ParseOptions): ModeValue<M, DocPage | undefined>;
+declare function getDocPage(parser: Parser<"sync", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): DocPage | undefined;
+declare function getDocPage(parser: Parser<"async", unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): Promise<DocPage | undefined>;
+declare function getDocPage<M extends Mode>(parser: Parser<M, unknown, unknown>, argsOrOptions?: readonly string[] | ParseOptions, options?: ParseOptions): ModeValue<M, DocPage | undefined>;
 //#endregion
 export { ArgumentErrorOptions, ArgumentOptions, CombineModes, CommandErrorOptions, CommandOptions, ConditionalErrorOptions, ConditionalOptions, DocState, DuplicateOptionError, FlagErrorOptions, FlagOptions, GroupOptions, InferMode, InferValue, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionOptions, OptionState, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, PassThroughFormat, PassThroughOptions, Result, Suggestion, TupleOptions, WithDefaultError, WithDefaultOptions, 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 };

package/dist/parser.js

@@ -299,14 +299,20 @@ function findCommandInExclusive(term, commandName) {
 * 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.
+* @param argsOrOptions Optional array of command-line arguments for context,
+*        or a {@link ParseOptions} object for annotations.  When a
+*        `ParseOptions` is passed here, the `options` parameter is ignored.
+* @param options Optional {@link ParseOptions} for customizing parsing
+*        behavior.  Only used when `argsOrOptions` is an array or omitted.
 * @returns A {@link DocPage} or `undefined`.
 * @since 0.9.0
 * @since 0.10.0 Added optional `options` parameter for annotations support.
+* @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+*              directly.
 */
-function getDocPageSync(parser, args = [], options) {
-	return getDocPageSyncImpl(parser, args, options);
+function getDocPageSync(parser, argsOrOptions, options) {
+	if (Array.isArray(argsOrOptions)) return getDocPageSyncImpl(parser, argsOrOptions, options);
+	return getDocPageSyncImpl(parser, [], argsOrOptions ?? options);
 }
 /**
 * Generates a documentation page for any parser, returning a Promise.
@@ -316,19 +322,28 @@ function getDocPageSync(parser, args = [], options) {
 * 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.
+* @param argsOrOptions Optional array of command-line arguments for context,
+*        or a {@link ParseOptions} object for annotations.  When a
+*        `ParseOptions` is passed here, the `options` parameter is ignored.
+* @param options Optional {@link ParseOptions} for customizing parsing
+*        behavior.  Only used when `argsOrOptions` is an array or omitted.
 * @returns A Promise of {@link DocPage} or `undefined`.
 * @since 0.9.0
 * @since 0.10.0 Added optional `options` parameter for annotations support.
+* @since 1.0.0 The second parameter now also accepts a `ParseOptions` object
+*              directly.
 */
-function getDocPageAsync(parser, args = [], options) {
-	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args, options));
-	return getDocPageAsyncImpl(parser, args, options);
+function getDocPageAsync(parser, argsOrOptions, options) {
+	const args = Array.isArray(argsOrOptions) ? argsOrOptions : [];
+	const opts = Array.isArray(argsOrOptions) ? options : argsOrOptions ?? options;
+	if (parser.$mode === "sync") return Promise.resolve(getDocPageSyncImpl(parser, args, opts));
+	return getDocPageAsyncImpl(parser, args, opts);
 }
-function getDocPage(parser, args = [], options) {
-	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args, options);
-	return getDocPageAsyncImpl(parser, args, options);
+function getDocPage(parser, argsOrOptions, options) {
+	const args = Array.isArray(argsOrOptions) ? argsOrOptions : [];
+	const opts = Array.isArray(argsOrOptions) ? options : argsOrOptions ?? options;
+	if (parser.$mode === "sync") return getDocPageSyncImpl(parser, args, opts);
+	return getDocPageAsyncImpl(parser, args, opts);
 }
 /**
 * Internal sync implementation of getDocPage.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1523+edc4d966",
+  "version": "1.0.0-dev.1531+6382e76e",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",