@optique/core 0.1.0-dev.1

package/dist/usage.cjs

@@ -0,0 +1,242 @@
+
+//#region src/usage.ts
+/**
+* Formats a usage description into a human-readable string representation
+* suitable for command-line help text.
+*
+* This function converts a structured {@link Usage} description into a
+* formatted string that follows common CLI conventions. It supports various
+* formatting options including colors and compact option display.
+* @param programName The name of the program or command for which the usage
+*                    description is being formatted. This is typically the
+*                    name of the executable or script that the user will run.
+* @param usage The usage description to format, consisting of an array
+*              of usage terms representing the command-line structure.
+* @param options Optional formatting options to customize the output.
+*                See {@link UsageFormatOptions} for available options.
+* @returns A formatted string representation of the usage description.
+*/
+function formatUsage(programName, usage, options = {}) {
+	usage = normalizeUsage(usage);
+	if (options.expandCommands) {
+		const lastTerm = usage.at(-1);
+		if (usage.length > 0 && usage.slice(0, -1).every((t) => t.type === "command") && lastTerm.type === "exclusive" && lastTerm.terms.every((t) => t.length > 0 && (t[0].type === "command" || t[0].type === "option" || t[0].type === "argument" || t[0].type === "optional" && t[0].terms.length === 1 && (t[0].terms[0].type === "command" || t[0].terms[0].type === "option" || t[0].terms[0].type === "argument")))) {
+			const lines = [];
+			for (let command of lastTerm.terms) {
+				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
+				lines.push(formatUsage(programName, command, options));
+			}
+			return lines.join("\n");
+		}
+	}
+	let output = options.colors ? `\x1b[1m${programName}\x1b[0m ` : `${programName} `;
+	let lineWidth = programName.length + 1;
+	for (const { text, width } of formatUsageTerms(usage, options)) {
+		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+			output += "\n";
+			lineWidth = 0;
+			if (text === " ") continue;
+		}
+		output += text;
+		lineWidth += width;
+	}
+	return output;
+}
+/**
+* Normalizes a usage description by flattening nested exclusive terms,
+* sorting terms for better readability, and ensuring consistent structure
+* throughout the usage tree.
+*
+* This function performs two main operations:
+*
+* 1. *Flattening*: Recursively processes all usage terms and merges any
+*    nested exclusive terms into their parent exclusive term to avoid
+*    redundant nesting. For example, an exclusive term containing another
+*    exclusive term will have its nested terms flattened into the parent.
+*
+* 2. *Sorting*: Reorders terms to improve readability by placing:
+*    - Commands (subcommands) first
+*    - Options and other terms in the middle
+*    - Positional arguments last (including optional/multiple wrappers around
+*      arguments)
+*
+* The sorting logic also recognizes when optional or multiple terms contain
+* positional arguments and treats them as arguments for sorting purposes.
+*
+* @param usage The usage description to normalize.
+* @returns A normalized usage description with flattened exclusive terms
+*          and terms sorted for optimal readability.
+*/
+function normalizeUsage(usage) {
+	const terms = usage.map(normalizeUsageTerm);
+	terms.sort((a, b) => {
+		const aCmd = a.type === "command";
+		const bCmd = b.type === "command";
+		const aArg = a.type === "argument" || (a.type === "optional" || a.type === "multiple") && a.terms.at(-1)?.type === "argument";
+		const bArg = b.type === "argument" || (b.type === "optional" || b.type === "multiple") && b.terms.at(-1)?.type === "argument";
+		return aCmd === bCmd ? aArg === bArg ? 0 : aArg ? 1 : -1 : aCmd ? -1 : 1;
+	});
+	return terms;
+}
+function normalizeUsageTerm(term) {
+	if (term.type === "optional") return {
+		type: "optional",
+		terms: normalizeUsage(term.terms)
+	};
+	else if (term.type === "multiple") return {
+		type: "multiple",
+		terms: normalizeUsage(term.terms),
+		min: term.min
+	};
+	else if (term.type === "exclusive") {
+		const terms = [];
+		for (const usage of term.terms) {
+			const normalized = normalizeUsage(usage);
+			if (normalized.length === 1 && normalized[0].type === "exclusive") for (const subUsage of normalized[0].terms) terms.push(subUsage);
+			else terms.push(normalized);
+		}
+		return {
+			type: "exclusive",
+			terms
+		};
+	} else return term;
+}
+function* formatUsageTerms(terms, options) {
+	let i = 0;
+	for (const t of terms) {
+		if (i > 0) yield {
+			text: " ",
+			width: 1
+		};
+		yield* formatUsageTermInternal(t, options);
+		i++;
+	}
+}
+/**
+* Formats a single {@link UsageTerm} into a string representation
+* suitable for command-line help text.
+* @param term The usage term to format, which can be an argument,
+*             option, command, optional term, exclusive term, or multiple term.
+* @param options Optional formatting options to customize the output.
+*                See {@link UsageTermFormatOptions} for available options.
+* @returns A formatted string representation of the usage term.
+*/
+function formatUsageTerm(term, options = {}) {
+	let lineWidth = 0;
+	let output = "";
+	for (const { text, width } of formatUsageTermInternal(term, options)) {
+		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
+			output += "\n";
+			lineWidth = 0;
+			if (text === " ") continue;
+		}
+		output += text;
+		lineWidth += width;
+	}
+	return output;
+}
+function* formatUsageTermInternal(term, options) {
+	const optionsSeparator = options.optionsSeparator ?? "/";
+	if (term.type === "argument") yield {
+		text: options?.colors ? `\x1b[4m${term.metavar}\x1b[0m` : term.metavar,
+		width: term.metavar.length
+	};
+	else if (term.type === "option") if (options?.onlyShortestOptions) {
+		const shortestName = term.names.reduce((a, b) => a.length <= b.length ? a : b);
+		yield {
+			text: options?.colors ? `\x1b[3m${shortestName}\x1b[0m` : shortestName,
+			width: shortestName.length
+		};
+	} else {
+		let i = 0;
+		for (const optionName of term.names) {
+			if (i > 0) yield {
+				text: options?.colors ? `\x1b[2m${optionsSeparator}\x1b[0m` : optionsSeparator,
+				width: optionsSeparator.length
+			};
+			yield {
+				text: options?.colors ? `\x1b[3m${optionName}\x1b[0m` : optionName,
+				width: optionName.length
+			};
+			i++;
+		}
+		if (term.metavar != null) {
+			yield {
+				text: " ",
+				width: 1
+			};
+			yield {
+				text: options?.colors ? `\x1b[4m\x1b[2m${term.metavar}\x1b[0m` : term.metavar,
+				width: term.metavar.length
+			};
+		}
+	}
+	else if (term.type === "command") yield {
+		text: options?.colors ? `\x1b[1m${term.name}\x1b[0m` : term.name,
+		width: term.name.length
+	};
+	else if (term.type === "optional") {
+		yield {
+			text: options?.colors ? `\x1b[2m[\x1b[0m` : "[",
+			width: 1
+		};
+		yield* formatUsageTerms(term.terms, options);
+		yield {
+			text: options?.colors ? `\x1b[2m]\x1b[0m` : "]",
+			width: 1
+		};
+	} else if (term.type === "exclusive") {
+		yield {
+			text: options?.colors ? `\x1b[2m(\x1b[0m` : "(",
+			width: 1
+		};
+		let i = 0;
+		for (const termGroup of term.terms) {
+			if (i > 0) {
+				yield {
+					text: " ",
+					width: 1
+				};
+				yield {
+					text: "|",
+					width: 1
+				};
+				yield {
+					text: " ",
+					width: 1
+				};
+			}
+			yield* formatUsageTerms(termGroup, options);
+			i++;
+		}
+		yield {
+			text: options?.colors ? `\x1b[2m)\x1b[0m` : ")",
+			width: 1
+		};
+	} else if (term.type === "multiple") {
+		if (term.min < 1) yield {
+			text: options?.colors ? `\x1b[2m[\x1b[0m` : "[",
+			width: 1
+		};
+		for (let i = 0; i < Math.max(1, term.min); i++) {
+			if (i > 0) yield {
+				text: " ",
+				width: 1
+			};
+			yield* formatUsageTerms(term.terms, options);
+		}
+		yield {
+			text: options?.colors ? `\x1b[2m...\x1b[0m` : "...",
+			width: 3
+		};
+		if (term.min < 1) yield {
+			text: options?.colors ? `\x1b[2m]\x1b[0m` : "]",
+			width: 1
+		};
+	} else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
+}
+
+//#endregion
+exports.formatUsage = formatUsage;
+exports.formatUsageTerm = formatUsageTerm;
+exports.normalizeUsage = normalizeUsage;

package/dist/usage.d.cts

@@ -0,0 +1,217 @@
+//#region src/usage.d.ts
+/**
+ * Represents the name of a command-line option.  There are four types of
+ * option syntax:
+ *
+ * - GNU-style long options (`--option`)
+ * - POSIX-style short options (`-o`) or Java-style options (`-option`)
+ * - MS-DOS-style options (`/o`, `/option`)
+ * - Plus-prefixed options (`+o`)
+ */
+type OptionName = `--${string}` | `-${string}` | `/${string}` | `+${string}`;
+/**
+ * Represents a single term in a command-line usage description.
+ */
+type UsageTerm =
+/**
+ * An argument term, which represents a positional argument in
+ * the command-line usage.
+ */
+{
+  /**
+   * The type of the term, which is always `"argument"` for this term.
+   */
+  readonly type: "argument";
+  /**
+   * The name of the argument, which is used to identify it in
+   * the command-line usage.
+   */
+  readonly metavar: string;
+}
+/**
+ * An option term, which represents a command-line option that can
+ * be specified by the user.
+ */ | {
+  /**
+   * The type of the term, which is always `"option"` for this term.
+   */
+  readonly type: "option";
+  /**
+   * The names of the option, which can include multiple
+   * short and long forms.
+   */
+  readonly names: readonly OptionName[];
+  /**
+   * An optional metavariable name for the option, which is used
+   * to indicate what value the option expects.
+   */
+  readonly metavar?: string;
+}
+/**
+ * A command term, which represents a subcommand in the command-line
+ * usage.
+ */ | {
+  /**
+   * The type of the term, which is always `"command"` for this term.
+   */
+  readonly type: "command";
+  /**
+   * The name of the command, which is used to identify it
+   * in the command-line usage.
+   */
+  readonly name: string;
+}
+/**
+ * An optional term, which represents an optional component
+ * in the command-line usage.
+ */ | {
+  /**
+   * The type of the term, which is always `"optional"` for this term.
+   */
+  readonly type: "optional";
+  /**
+   * The terms that are optional, which can be an argument, an option,
+   * a command, or another usage term.
+   */
+  readonly terms: Usage;
+}
+/**
+ * A term of multiple occurrences, which allows a term to be specified
+ * multiple times in the command-line usage.
+ */ | {
+  /**
+   * The type of the term, which is always `"multiple"` for this term.
+   */
+  readonly type: "multiple";
+  /**
+   * The terms that can occur multiple times, which can be an argument,
+   * an option, a command, or another usage term.
+   */
+  readonly terms: Usage;
+  /**
+   * The minimum number of times the term must occur.
+   */
+  readonly min: number;
+} |
+/**
+* An exclusive term, which represents a group of terms that are mutually
+* exclusive, meaning that only one of the terms in the group can be
+* specified at a time.
+*/
+{
+  /**
+   * The type of the term, which is always `"exclusive"` for this term.
+   */
+  readonly type: "exclusive";
+  /**
+   * The terms that are mutually exclusive, which can include
+   * arguments, options, commands, or other usage terms.
+   */
+  readonly terms: readonly Usage[];
+};
+/**
+ * Represents a command-line usage description, which is a sequence of
+ * {@link UsageTerm} objects.  This type is used to describe how a command-line
+ * parser expects its input to be structured, including the required and
+ * optional components, as well as any exclusive groups of terms.
+ */
+type Usage = readonly UsageTerm[];
+/**
+ * Options for formatting usage descriptions.
+ */
+interface UsageFormatOptions {
+  /**
+   * When `true`, expands commands in the usage description
+   * to multiple lines, showing each command on a new line.
+   * This is useful for commands with many subcommands, making it easier
+   * to read and understand the available commands.
+   * @default `false`
+   */
+  readonly expandCommands?: boolean;
+  /**
+   * When `true`, only shows the shortest option name for each option
+   * instead of showing all aliases separated by `/`.
+   * For example, `--verbose/-v` becomes just `-v`.
+   * @default `false`
+   */
+  readonly onlyShortestOptions?: boolean;
+  /**
+   * When `true`, applies ANSI color codes to the output for better readability.
+   * Different elements (options, arguments, commands, etc.) will be styled
+   * with different colors and formatting.
+   * @default `false`
+   */
+  readonly colors?: boolean;
+  /**
+   * The maximum width of the formatted output.  If specified, the output
+   * will be wrapped to fit within this width, breaking lines as necessary.
+   * If not specified, the output will not be wrapped.
+   * @default `undefined`
+   */
+  readonly maxWidth?: number;
+}
+/**
+ * Formats a usage description into a human-readable string representation
+ * suitable for command-line help text.
+ *
+ * This function converts a structured {@link Usage} description into a
+ * formatted string that follows common CLI conventions. It supports various
+ * formatting options including colors and compact option display.
+ * @param programName The name of the program or command for which the usage
+ *                    description is being formatted. This is typically the
+ *                    name of the executable or script that the user will run.
+ * @param usage The usage description to format, consisting of an array
+ *              of usage terms representing the command-line structure.
+ * @param options Optional formatting options to customize the output.
+ *                See {@link UsageFormatOptions} for available options.
+ * @returns A formatted string representation of the usage description.
+ */
+declare function formatUsage(programName: string, usage: Usage, options?: UsageFormatOptions): string;
+/**
+ * Normalizes a usage description by flattening nested exclusive terms,
+ * sorting terms for better readability, and ensuring consistent structure
+ * throughout the usage tree.
+ *
+ * This function performs two main operations:
+ *
+ * 1. *Flattening*: Recursively processes all usage terms and merges any
+ *    nested exclusive terms into their parent exclusive term to avoid
+ *    redundant nesting. For example, an exclusive term containing another
+ *    exclusive term will have its nested terms flattened into the parent.
+ *
+ * 2. *Sorting*: Reorders terms to improve readability by placing:
+ *    - Commands (subcommands) first
+ *    - Options and other terms in the middle
+ *    - Positional arguments last (including optional/multiple wrappers around
+ *      arguments)
+ *
+ * The sorting logic also recognizes when optional or multiple terms contain
+ * positional arguments and treats them as arguments for sorting purposes.
+ *
+ * @param usage The usage description to normalize.
+ * @returns A normalized usage description with flattened exclusive terms
+ *          and terms sorted for optimal readability.
+ */
+declare function normalizeUsage(usage: Usage): Usage;
+/**
+ * Options for formatting a single {@link UsageTerm}.
+ */
+interface UsageTermFormatOptions extends UsageFormatOptions {
+  /**
+   * A string that separates multiple option names in the formatted output.
+   * @default `"/"`
+   */
+  readonly optionsSeparator?: string;
+}
+/**
+ * Formats a single {@link UsageTerm} into a string representation
+ * suitable for command-line help text.
+ * @param term The usage term to format, which can be an argument,
+ *             option, command, optional term, exclusive term, or multiple term.
+ * @param options Optional formatting options to customize the output.
+ *                See {@link UsageTermFormatOptions} for available options.
+ * @returns A formatted string representation of the usage term.
+ */
+declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
+//#endregion
+export { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage };

package/dist/usage.d.ts

@@ -0,0 +1,217 @@
+//#region src/usage.d.ts
+/**
+ * Represents the name of a command-line option.  There are four types of
+ * option syntax:
+ *
+ * - GNU-style long options (`--option`)
+ * - POSIX-style short options (`-o`) or Java-style options (`-option`)
+ * - MS-DOS-style options (`/o`, `/option`)
+ * - Plus-prefixed options (`+o`)
+ */
+type OptionName = `--${string}` | `-${string}` | `/${string}` | `+${string}`;
+/**
+ * Represents a single term in a command-line usage description.
+ */
+type UsageTerm =
+/**
+ * An argument term, which represents a positional argument in
+ * the command-line usage.
+ */
+{
+  /**
+   * The type of the term, which is always `"argument"` for this term.
+   */
+  readonly type: "argument";
+  /**
+   * The name of the argument, which is used to identify it in
+   * the command-line usage.
+   */
+  readonly metavar: string;
+}
+/**
+ * An option term, which represents a command-line option that can
+ * be specified by the user.
+ */ | {
+  /**
+   * The type of the term, which is always `"option"` for this term.
+   */
+  readonly type: "option";
+  /**
+   * The names of the option, which can include multiple
+   * short and long forms.
+   */
+  readonly names: readonly OptionName[];
+  /**
+   * An optional metavariable name for the option, which is used
+   * to indicate what value the option expects.
+   */
+  readonly metavar?: string;
+}
+/**
+ * A command term, which represents a subcommand in the command-line
+ * usage.
+ */ | {
+  /**
+   * The type of the term, which is always `"command"` for this term.
+   */
+  readonly type: "command";
+  /**
+   * The name of the command, which is used to identify it
+   * in the command-line usage.
+   */
+  readonly name: string;
+}
+/**
+ * An optional term, which represents an optional component
+ * in the command-line usage.
+ */ | {
+  /**
+   * The type of the term, which is always `"optional"` for this term.
+   */
+  readonly type: "optional";
+  /**
+   * The terms that are optional, which can be an argument, an option,
+   * a command, or another usage term.
+   */
+  readonly terms: Usage;
+}
+/**
+ * A term of multiple occurrences, which allows a term to be specified
+ * multiple times in the command-line usage.
+ */ | {
+  /**
+   * The type of the term, which is always `"multiple"` for this term.
+   */
+  readonly type: "multiple";
+  /**
+   * The terms that can occur multiple times, which can be an argument,
+   * an option, a command, or another usage term.
+   */
+  readonly terms: Usage;
+  /**
+   * The minimum number of times the term must occur.
+   */
+  readonly min: number;
+} |
+/**
+* An exclusive term, which represents a group of terms that are mutually
+* exclusive, meaning that only one of the terms in the group can be
+* specified at a time.
+*/
+{
+  /**
+   * The type of the term, which is always `"exclusive"` for this term.
+   */
+  readonly type: "exclusive";
+  /**
+   * The terms that are mutually exclusive, which can include
+   * arguments, options, commands, or other usage terms.
+   */
+  readonly terms: readonly Usage[];
+};
+/**
+ * Represents a command-line usage description, which is a sequence of
+ * {@link UsageTerm} objects.  This type is used to describe how a command-line
+ * parser expects its input to be structured, including the required and
+ * optional components, as well as any exclusive groups of terms.
+ */
+type Usage = readonly UsageTerm[];
+/**
+ * Options for formatting usage descriptions.
+ */
+interface UsageFormatOptions {
+  /**
+   * When `true`, expands commands in the usage description
+   * to multiple lines, showing each command on a new line.
+   * This is useful for commands with many subcommands, making it easier
+   * to read and understand the available commands.
+   * @default `false`
+   */
+  readonly expandCommands?: boolean;
+  /**
+   * When `true`, only shows the shortest option name for each option
+   * instead of showing all aliases separated by `/`.
+   * For example, `--verbose/-v` becomes just `-v`.
+   * @default `false`
+   */
+  readonly onlyShortestOptions?: boolean;
+  /**
+   * When `true`, applies ANSI color codes to the output for better readability.
+   * Different elements (options, arguments, commands, etc.) will be styled
+   * with different colors and formatting.
+   * @default `false`
+   */
+  readonly colors?: boolean;
+  /**
+   * The maximum width of the formatted output.  If specified, the output
+   * will be wrapped to fit within this width, breaking lines as necessary.
+   * If not specified, the output will not be wrapped.
+   * @default `undefined`
+   */
+  readonly maxWidth?: number;
+}
+/**
+ * Formats a usage description into a human-readable string representation
+ * suitable for command-line help text.
+ *
+ * This function converts a structured {@link Usage} description into a
+ * formatted string that follows common CLI conventions. It supports various
+ * formatting options including colors and compact option display.
+ * @param programName The name of the program or command for which the usage
+ *                    description is being formatted. This is typically the
+ *                    name of the executable or script that the user will run.
+ * @param usage The usage description to format, consisting of an array
+ *              of usage terms representing the command-line structure.
+ * @param options Optional formatting options to customize the output.
+ *                See {@link UsageFormatOptions} for available options.
+ * @returns A formatted string representation of the usage description.
+ */
+declare function formatUsage(programName: string, usage: Usage, options?: UsageFormatOptions): string;
+/**
+ * Normalizes a usage description by flattening nested exclusive terms,
+ * sorting terms for better readability, and ensuring consistent structure
+ * throughout the usage tree.
+ *
+ * This function performs two main operations:
+ *
+ * 1. *Flattening*: Recursively processes all usage terms and merges any
+ *    nested exclusive terms into their parent exclusive term to avoid
+ *    redundant nesting. For example, an exclusive term containing another
+ *    exclusive term will have its nested terms flattened into the parent.
+ *
+ * 2. *Sorting*: Reorders terms to improve readability by placing:
+ *    - Commands (subcommands) first
+ *    - Options and other terms in the middle
+ *    - Positional arguments last (including optional/multiple wrappers around
+ *      arguments)
+ *
+ * The sorting logic also recognizes when optional or multiple terms contain
+ * positional arguments and treats them as arguments for sorting purposes.
+ *
+ * @param usage The usage description to normalize.
+ * @returns A normalized usage description with flattened exclusive terms
+ *          and terms sorted for optimal readability.
+ */
+declare function normalizeUsage(usage: Usage): Usage;
+/**
+ * Options for formatting a single {@link UsageTerm}.
+ */
+interface UsageTermFormatOptions extends UsageFormatOptions {
+  /**
+   * A string that separates multiple option names in the formatted output.
+   * @default `"/"`
+   */
+  readonly optionsSeparator?: string;
+}
+/**
+ * Formats a single {@link UsageTerm} into a string representation
+ * suitable for command-line help text.
+ * @param term The usage term to format, which can be an argument,
+ *             option, command, optional term, exclusive term, or multiple term.
+ * @param options Optional formatting options to customize the output.
+ *                See {@link UsageTermFormatOptions} for available options.
+ * @returns A formatted string representation of the usage term.
+ */
+declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
+//#endregion
+export { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage };