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

package/dist/constructs.cjs

@@ -2,6 +2,7 @@ const require_annotations = require('./annotations.cjs');
 const require_message = require('./message.cjs');
 const require_dependency = require('./dependency.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
+const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
 const require_suggestion = require('./suggestion.cjs');
@@ -1001,6 +1002,7 @@ async function resolveDeferredParseStatesAsync(fieldStates, initialRegistry) {
 }
 function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const label = typeof labelOrParsers === "string" ? labelOrParsers : void 0;
+	if (label != null) require_validate.validateLabel(label);
 	let parsers;
 	let options = {};
 	if (typeof labelOrParsers === "string") {
@@ -1410,6 +1412,7 @@ async function* suggestTupleAsync(context, prefix, parsers) {
 }
 function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const label = typeof labelOrParsers === "string" ? labelOrParsers : void 0;
+	if (label != null) require_validate.validateLabel(label);
 	let parsers;
 	let options = {};
 	if (typeof labelOrParsers === "string") {
@@ -1723,6 +1726,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 }
 function merge(...args) {
 	const label = typeof args[0] === "string" ? args[0] : void 0;
+	if (label != null) require_validate.validateLabel(label);
 	const lastArg = args[args.length - 1];
 	const hasOptions = lastArg != null && typeof lastArg === "object" && !("$valueType" in lastArg);
 	const options = hasOptions ? lastArg : {};
@@ -2481,6 +2485,7 @@ function concat(...parsers) {
 	};
 }
 function group(label, parser, options = {}) {
+	require_validate.validateLabel(label);
 	const groupParser = {
 		$mode: parser.$mode,
 		$valueType: parser.$valueType,

package/dist/constructs.d.cts

@@ -1023,6 +1023,8 @@ declare function object<T extends {
  * @returns A {@link Parser} that produces an object with the same keys as
  *          the input, where each value is the result of the corresponding
  *          parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function object<T extends {
   readonly [key: string | symbol]: Parser<Mode, unknown, unknown>;
@@ -1040,6 +1042,8 @@ declare function object<T extends {
  * @returns A {@link Parser} that produces an object with the same keys as
  *          the input, where each value is the result of the corresponding
  *          parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.5.0
  */
 declare function object<T extends {
@@ -1084,6 +1088,8 @@ declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]
  * @returns A {@link Parser} that produces a readonly tuple with the same length
  *          as the input array, where each element is the result of the
  *          corresponding parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]>(label: string, parsers: T, options?: TupleOptions): Parser<CombineTupleModes<T>, { readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
 /**
@@ -1152,6 +1158,8 @@ declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
  * @throws {TypeError} If no parser arguments are provided.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.4.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1166,6 +1174,8 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...pa
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
  * @throws {TypeError} If no parser arguments are provided.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1271,6 +1281,8 @@ declare function concat<const TParsers extends ConcatParsers>(...parsers: TParse
  * @param options Optional visibility controls for the wrapped parser terms.
  * @returns A new parser that behaves identically to the input parser
  *          but generates documentation within a labeled section.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.4.0
  */
 /**

package/dist/constructs.d.ts

@@ -1023,6 +1023,8 @@ declare function object<T extends {
  * @returns A {@link Parser} that produces an object with the same keys as
  *          the input, where each value is the result of the corresponding
  *          parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function object<T extends {
   readonly [key: string | symbol]: Parser<Mode, unknown, unknown>;
@@ -1040,6 +1042,8 @@ declare function object<T extends {
  * @returns A {@link Parser} that produces an object with the same keys as
  *          the input, where each value is the result of the corresponding
  *          parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.5.0
  */
 declare function object<T extends {
@@ -1084,6 +1088,8 @@ declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]
  * @returns A {@link Parser} that produces a readonly tuple with the same length
  *          as the input array, where each element is the result of the
  *          corresponding parser.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  */
 declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]>(label: string, parsers: T, options?: TupleOptions): Parser<CombineTupleModes<T>, { readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
 /**
@@ -1152,6 +1158,8 @@ declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
  * @throws {TypeError} If no parser arguments are provided.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.4.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1166,6 +1174,8 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...pa
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
  * @throws {TypeError} If no parser arguments are provided.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1271,6 +1281,8 @@ declare function concat<const TParsers extends ConcatParsers>(...parsers: TParse
  * @param options Optional visibility controls for the wrapped parser terms.
  * @returns A new parser that behaves identically to the input parser
  *          but generates documentation within a labeled section.
+ * @throws {TypeError} If the label is not a string, is empty,
+ *         whitespace-only, or contains control characters.
  * @since 0.4.0
  */
 /**

package/dist/constructs.js

@@ -2,6 +2,7 @@ import { getAnnotations, inheritAnnotations, injectAnnotations } from "./annotat
 import { message, optionName, text, values } from "./message.js";
 import { DependencyRegistry, createDependencySourceState, dependencyId, isDeferredParseState, isDependencySourceState, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, wrappedDependencySourceMarker } from "./dependency.js";
 import { dispatchByMode, dispatchIterableByMode } from "./mode-dispatch.js";
+import { validateLabel } from "./validate.js";
 import { extractArgumentMetavars, extractCommandNames, extractOptionNames, isDocHidden, mergeHidden } from "./usage.js";
 import { deduplicateDocFragments } from "./doc.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, deduplicateSuggestions, findSimilar } from "./suggestion.js";
@@ -1001,6 +1002,7 @@ async function resolveDeferredParseStatesAsync(fieldStates, initialRegistry) {
 }
 function object(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const label = typeof labelOrParsers === "string" ? labelOrParsers : void 0;
+	if (label != null) validateLabel(label);
 	let parsers;
 	let options = {};
 	if (typeof labelOrParsers === "string") {
@@ -1410,6 +1412,7 @@ async function* suggestTupleAsync(context, prefix, parsers) {
 }
 function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 	const label = typeof labelOrParsers === "string" ? labelOrParsers : void 0;
+	if (label != null) validateLabel(label);
 	let parsers;
 	let options = {};
 	if (typeof labelOrParsers === "string") {
@@ -1723,6 +1726,7 @@ function tuple(labelOrParsers, maybeParsersOrOptions, maybeOptions) {
 }
 function merge(...args) {
 	const label = typeof args[0] === "string" ? args[0] : void 0;
+	if (label != null) validateLabel(label);
 	const lastArg = args[args.length - 1];
 	const hasOptions = lastArg != null && typeof lastArg === "object" && !("$valueType" in lastArg);
 	const options = hasOptions ? lastArg : {};
@@ -2481,6 +2485,7 @@ function concat(...parsers) {
 	};
 }
 function group(label, parser, options = {}) {
+	validateLabel(label);
 	const groupParser = {
 		$mode: parser.$mode,
 		$valueType: parser.$valueType,

package/dist/doc.cjs

@@ -185,8 +185,8 @@ function defaultSectionOrder(a, b) {
 * @returns A formatted string representation of the documentation page
 * @throws {TypeError} If `programName` is not a string, is empty,
 * whitespace-only, or contains control characters, if any non-empty
-* section's title is empty, whitespace-only, or contains a CR or LF
-* character, or if `maxWidth` is not a finite integer.
+* section's title is not a string, is empty, whitespace-only, or contains
+* control characters, or if `maxWidth` is not a finite integer.
 * @throws {RangeError} If any entry needs a description column and `maxWidth`
 * is too small to fit the minimum layout (less than `termIndent + 4`), or if
 * `showChoices.maxItems` is less than `1`.
@@ -312,7 +312,7 @@ function formatDocPage(programName, page, options = {}) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
 		if (section.title != null) {
-			if (section.title.trim() === "" || /[\r\n]/.test(section.title)) throw new TypeError("Section title must not be empty, whitespace-only, or contain newlines.");
+			require_validate.validateLabel(section.title);
 			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
 			output += sectionLabel;
 		}

package/dist/doc.d.cts

@@ -313,8 +313,8 @@ interface DocPageFormatOptions {
  * @returns A formatted string representation of the documentation page
  * @throws {TypeError} If `programName` is not a string, is empty,
  * whitespace-only, or contains control characters, if any non-empty
- * section's title is empty, whitespace-only, or contains a CR or LF
- * character, or if `maxWidth` is not a finite integer.
+ * section's title is not a string, is empty, whitespace-only, or contains
+ * control characters, or if `maxWidth` is not a finite integer.
  * @throws {RangeError} If any entry needs a description column and `maxWidth`
  * is too small to fit the minimum layout (less than `termIndent + 4`), or if
  * `showChoices.maxItems` is less than `1`.

package/dist/doc.d.ts

@@ -313,8 +313,8 @@ interface DocPageFormatOptions {
  * @returns A formatted string representation of the documentation page
  * @throws {TypeError} If `programName` is not a string, is empty,
  * whitespace-only, or contains control characters, if any non-empty
- * section's title is empty, whitespace-only, or contains a CR or LF
- * character, or if `maxWidth` is not a finite integer.
+ * section's title is not a string, is empty, whitespace-only, or contains
+ * control characters, or if `maxWidth` is not a finite integer.
  * @throws {RangeError} If any entry needs a description column and `maxWidth`
  * is too small to fit the minimum layout (less than `termIndent + 4`), or if
  * `showChoices.maxItems` is less than `1`.

package/dist/doc.js

@@ -1,5 +1,5 @@
 import { cloneMessage, formatMessage, text } from "./message.js";
-import { validateProgramName } from "./validate.js";
+import { validateLabel, validateProgramName } from "./validate.js";
 import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden, isUsageHidden } from "./usage.js";
 
 //#region src/doc.ts
@@ -185,8 +185,8 @@ function defaultSectionOrder(a, b) {
 * @returns A formatted string representation of the documentation page
 * @throws {TypeError} If `programName` is not a string, is empty,
 * whitespace-only, or contains control characters, if any non-empty
-* section's title is empty, whitespace-only, or contains a CR or LF
-* character, or if `maxWidth` is not a finite integer.
+* section's title is not a string, is empty, whitespace-only, or contains
+* control characters, or if `maxWidth` is not a finite integer.
 * @throws {RangeError} If any entry needs a description column and `maxWidth`
 * is too small to fit the minimum layout (less than `termIndent + 4`), or if
 * `showChoices.maxItems` is less than `1`.
@@ -312,7 +312,7 @@ function formatDocPage(programName, page, options = {}) {
 		if (section.entries.length < 1) continue;
 		output += "\n";
 		if (section.title != null) {
-			if (section.title.trim() === "" || /[\r\n]/.test(section.title)) throw new TypeError("Section title must not be empty, whitespace-only, or contain newlines.");
+			validateLabel(section.title);
 			const sectionLabel = options.colors ? `\x1b[1;2m${section.title}:\x1b[0m\n` : `${section.title}:\n`;
 			output += sectionLabel;
 		}

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/dist/validate.cjs

@@ -147,9 +147,28 @@ function validateProgramName(programName) {
 	if (/^\s+$/.test(programName)) throw new TypeError(`Program name must not be whitespace-only: "${escapeControlChars(programName)}".`);
 	if (CONTROL_CHAR_RE.test(programName)) throw new TypeError(`Program name must not contain control characters: "${escapeControlChars(programName)}".`);
 }
+/**
+* Validates a label at runtime.
+*
+* Labels are used as section titles in documentation output.  They may contain
+* spaces (e.g., "Connection options"), but must not be empty, whitespace-only,
+* or contain control characters.
+*
+* @param label The label to validate.
+* @throws {TypeError} If the label is not a string, is empty,
+*         whitespace-only, or contains control characters.
+* @since 1.0.0
+*/
+function validateLabel(label) {
+	if (typeof label !== "string") throw new TypeError("Label must be a string.");
+	if (label === "") throw new TypeError("Label must not be empty.");
+	if (/^\s+$/.test(label)) throw new TypeError(`Label must not be whitespace-only: "${escapeControlChars(label)}".`);
+	if (CONTROL_CHAR_RE.test(label)) throw new TypeError(`Label must not contain control characters: "${escapeControlChars(label)}".`);
+}
 
 //#endregion
 exports.validateCommandNames = validateCommandNames;
+exports.validateLabel = validateLabel;
 exports.validateMetaNameCollisions = validateMetaNameCollisions;
 exports.validateOptionNames = validateOptionNames;
 exports.validateProgramName = validateProgramName;

package/dist/validate.js

@@ -146,6 +146,24 @@ function validateProgramName(programName) {
 	if (/^\s+$/.test(programName)) throw new TypeError(`Program name must not be whitespace-only: "${escapeControlChars(programName)}".`);
 	if (CONTROL_CHAR_RE.test(programName)) throw new TypeError(`Program name must not contain control characters: "${escapeControlChars(programName)}".`);
 }
+/**
+* Validates a label at runtime.
+*
+* Labels are used as section titles in documentation output.  They may contain
+* spaces (e.g., "Connection options"), but must not be empty, whitespace-only,
+* or contain control characters.
+*
+* @param label The label to validate.
+* @throws {TypeError} If the label is not a string, is empty,
+*         whitespace-only, or contains control characters.
+* @since 1.0.0
+*/
+function validateLabel(label) {
+	if (typeof label !== "string") throw new TypeError("Label must be a string.");
+	if (label === "") throw new TypeError("Label must not be empty.");
+	if (/^\s+$/.test(label)) throw new TypeError(`Label must not be whitespace-only: "${escapeControlChars(label)}".`);
+	if (CONTROL_CHAR_RE.test(label)) throw new TypeError(`Label must not contain control characters: "${escapeControlChars(label)}".`);
+}
 
 //#endregion
-export { validateCommandNames, validateMetaNameCollisions, validateOptionNames, validateProgramName };
+export { validateCommandNames, validateLabel, validateMetaNameCollisions, validateOptionNames, validateProgramName };

package/package.json

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