@optique/core 0.10.7 → 1.0.0-dev.1116

package/dist/usage.cjs

@@ -1,6 +1,38 @@
 
 //#region src/usage.ts
 /**
+* Returns whether the term should be hidden from usage output.
+*/
+function isUsageHidden(hidden) {
+	return hidden === true || hidden === "usage" || hidden === "help";
+}
+/**
+* Returns whether the term should be hidden from documentation output.
+*/
+function isDocHidden(hidden) {
+	return hidden === true || hidden === "doc" || hidden === "help";
+}
+/**
+* Returns whether the term should be hidden from suggestion/error candidates.
+*/
+function isSuggestionHidden(hidden) {
+	return hidden === true;
+}
+/**
+* Merges two hidden visibility settings by taking the union of restrictions.
+*/
+function mergeHidden(a, b) {
+	if (a == null) return b;
+	if (b == null) return a;
+	if (a === true || b === true) return true;
+	if (a === false) return b;
+	if (b === false) return a;
+	if (a === b) return a;
+	if (a === "help" || b === "help") return "help";
+	if ((a === "usage" || a === "doc") && (b === "usage" || b === "doc")) return "help";
+	return a;
+}
+/**
 * Extracts all option names from a usage description.
 *
 * This function recursively traverses a {@link Usage} tree and collects all
@@ -25,7 +57,7 @@ function extractOptionNames(usage) {
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "option") {
-			if (term.hidden) continue;
+			if (isSuggestionHidden(term.hidden)) continue;
 			for (const name of term.names) names.add(name);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -58,7 +90,7 @@ function extractCommandNames(usage) {
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "command") {
-			if (term.hidden) continue;
+			if (isSuggestionHidden(term.hidden)) continue;
 			names.add(term.name);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -92,7 +124,7 @@ function extractArgumentMetavars(usage) {
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "argument") {
-			if (term.hidden) continue;
+			if (isSuggestionHidden(term.hidden)) continue;
 			metavars.add(term.metavar);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -117,14 +149,14 @@ function extractArgumentMetavars(usage) {
 * @returns A formatted string representation of the usage description.
 */
 function formatUsage(programName, usage, options = {}) {
-	usage = normalizeUsage(usage);
+	usage = normalizeUsage(filterUsageForDisplay(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) {
 				const firstTerm = command[0];
-				if (firstTerm?.type === "command" && firstTerm.hidden) continue;
+				if (firstTerm?.type === "command" && isUsageHidden(firstTerm.hidden)) continue;
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}
@@ -205,9 +237,47 @@ function normalizeUsageTerm(term) {
 		};
 	} else return term;
 }
+function filterUsageForDisplay(usage) {
+	const terms = [];
+	for (const term of usage) {
+		if ((term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") && isUsageHidden(term.hidden)) continue;
+		if (term.type === "optional") {
+			const filtered = filterUsageForDisplay(term.terms);
+			if (filtered.length > 0) terms.push({
+				type: "optional",
+				terms: filtered
+			});
+			continue;
+		}
+		if (term.type === "multiple") {
+			const filtered = filterUsageForDisplay(term.terms);
+			if (filtered.length > 0) terms.push({
+				type: "multiple",
+				terms: filtered,
+				min: term.min
+			});
+			continue;
+		}
+		if (term.type === "exclusive") {
+			const filteredBranches = term.terms.map((branch) => {
+				const first = branch[0];
+				if (first?.type === "command" && isUsageHidden(first.hidden)) return [];
+				return filterUsageForDisplay(branch);
+			}).filter((branch) => branch.length > 0);
+			if (filteredBranches.length > 0) terms.push({
+				type: "exclusive",
+				terms: filteredBranches
+			});
+			continue;
+		}
+		terms.push(term);
+	}
+	return terms;
+}
 function* formatUsageTerms(terms, options) {
 	let i = 0;
 	for (const t of terms) {
+		if ("hidden" in t && (t.type === "argument" || t.type === "option" || t.type === "command" || t.type === "passthrough") && isUsageHidden(t.hidden)) continue;
 		if (i > 0) yield {
 			text: " ",
 			width: 1
@@ -226,9 +296,11 @@ function* formatUsageTerms(terms, options) {
 * @returns A formatted string representation of the usage term.
 */
 function formatUsageTerm(term, options = {}) {
+	const visibleTerms = filterUsageForDisplay([term]);
+	if (visibleTerms.length < 1) return "";
 	let lineWidth = 0;
 	let output = "";
-	for (const { text, width } of formatUsageTermInternal(term, options)) {
+	for (const { text, width } of formatUsageTermInternal(visibleTerms[0], options)) {
 		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
 			output += "\n";
 			lineWidth = 0;
@@ -347,6 +419,12 @@ function* formatUsageTermInternal(term, options) {
 			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
 			width: 5
 		};
+	} else if (term.type === "ellipsis") {
+		const text = "...";
+		yield {
+			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
+			width: 3
+		};
 	} else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
 }
 
@@ -356,4 +434,8 @@ exports.extractCommandNames = extractCommandNames;
 exports.extractOptionNames = extractOptionNames;
 exports.formatUsage = formatUsage;
 exports.formatUsageTerm = formatUsageTerm;
+exports.isDocHidden = isDocHidden;
+exports.isSuggestionHidden = isSuggestionHidden;
+exports.isUsageHidden = isUsageHidden;
+exports.mergeHidden = mergeHidden;
 exports.normalizeUsage = normalizeUsage;

package/dist/usage.d.cts

@@ -12,6 +12,31 @@ import { NonEmptyString } from "./nonempty.cjs";
  * - Plus-prefixed options (`+o`)
  */
 type OptionName = `--${string}` | `-${string}` | `/${string}` | `+${string}`;
+/**
+ * Visibility control for parser terms.
+ *
+ * - `true`: hidden from usage, documentation, and suggestions
+ * - `"usage"`: hidden from usage only
+ * - `"doc"`: hidden from documentation only
+ * - `"help"`: hidden from usage and documentation, but shown in suggestions
+ */
+type HiddenVisibility = boolean | "usage" | "doc" | "help";
+/**
+ * Returns whether the term should be hidden from usage output.
+ */
+declare function isUsageHidden(hidden?: HiddenVisibility): boolean;
+/**
+ * Returns whether the term should be hidden from documentation output.
+ */
+declare function isDocHidden(hidden?: HiddenVisibility): boolean;
+/**
+ * Returns whether the term should be hidden from suggestion/error candidates.
+ */
+declare function isSuggestionHidden(hidden?: HiddenVisibility): boolean;
+/**
+ * Merges two hidden visibility settings by taking the union of restrictions.
+ */
+declare function mergeHidden(a?: HiddenVisibility, b?: HiddenVisibility): HiddenVisibility | undefined;
 /**
  * Represents a single term in a command-line usage description.
  */
@@ -31,11 +56,10 @@ type UsageTerm =
    */
   readonly metavar: NonEmptyString;
   /**
-   * When `true`, hides the argument from help text, shell completion
-   * suggestions, and error suggestions.
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * An option term, which represents a command-line option that can
@@ -56,11 +80,10 @@ type UsageTerm =
    */
   readonly metavar?: NonEmptyString;
   /**
-   * When `true`, hides the option from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions.
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * A command term, which represents a subcommand in the command-line
@@ -76,11 +99,16 @@ type UsageTerm =
    */
   readonly name: string;
   /**
-   * When `true`, hides the command from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions.
+   * Optional usage line override for this command's own help page.
+   * This affects help/documentation rendering only.
+   * @since 1.0.0
+   */
+  readonly usageLine?: Usage | ((defaultUsageLine: Usage) => Usage);
+  /**
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * An optional term, which represents an optional component
@@ -155,11 +183,21 @@ type UsageTerm =
    */
   readonly type: "passthrough";
   /**
-   * When `true`, hides the pass-through from help text and shell
-   * completion suggestions.
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
+}
+/**
+ * An ellipsis term, which represents a summary placeholder in usage output.
+ * Unlike {@link passthrough}, this term has no parsing semantics and is used
+ * only for display.
+ * @since 1.0.0
+ */ | {
+  /**
+   * The type of the term, which is always `"ellipsis"` for this term.
+   */
+  readonly type: "ellipsis";
 };
 /**
  * Represents a command-line usage description, which is a sequence of
@@ -330,4 +368,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };
+export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.d.ts

@@ -12,6 +12,31 @@ import { NonEmptyString } from "./nonempty.js";
  * - Plus-prefixed options (`+o`)
  */
 type OptionName = `--${string}` | `-${string}` | `/${string}` | `+${string}`;
+/**
+ * Visibility control for parser terms.
+ *
+ * - `true`: hidden from usage, documentation, and suggestions
+ * - `"usage"`: hidden from usage only
+ * - `"doc"`: hidden from documentation only
+ * - `"help"`: hidden from usage and documentation, but shown in suggestions
+ */
+type HiddenVisibility = boolean | "usage" | "doc" | "help";
+/**
+ * Returns whether the term should be hidden from usage output.
+ */
+declare function isUsageHidden(hidden?: HiddenVisibility): boolean;
+/**
+ * Returns whether the term should be hidden from documentation output.
+ */
+declare function isDocHidden(hidden?: HiddenVisibility): boolean;
+/**
+ * Returns whether the term should be hidden from suggestion/error candidates.
+ */
+declare function isSuggestionHidden(hidden?: HiddenVisibility): boolean;
+/**
+ * Merges two hidden visibility settings by taking the union of restrictions.
+ */
+declare function mergeHidden(a?: HiddenVisibility, b?: HiddenVisibility): HiddenVisibility | undefined;
 /**
  * Represents a single term in a command-line usage description.
  */
@@ -31,11 +56,10 @@ type UsageTerm =
    */
   readonly metavar: NonEmptyString;
   /**
-   * When `true`, hides the argument from help text, shell completion
-   * suggestions, and error suggestions.
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * An option term, which represents a command-line option that can
@@ -56,11 +80,10 @@ type UsageTerm =
    */
   readonly metavar?: NonEmptyString;
   /**
-   * When `true`, hides the option from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions.
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * A command term, which represents a subcommand in the command-line
@@ -76,11 +99,16 @@ type UsageTerm =
    */
   readonly name: string;
   /**
-   * When `true`, hides the command from help text, shell completion
-   * suggestions, and "Did you mean?" error suggestions.
+   * Optional usage line override for this command's own help page.
+   * This affects help/documentation rendering only.
+   * @since 1.0.0
+   */
+  readonly usageLine?: Usage | ((defaultUsageLine: Usage) => Usage);
+  /**
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
 }
 /**
  * An optional term, which represents an optional component
@@ -155,11 +183,21 @@ type UsageTerm =
    */
   readonly type: "passthrough";
   /**
-   * When `true`, hides the pass-through from help text and shell
-   * completion suggestions.
+   * Visibility controls for this term.
    * @since 0.9.0
    */
-  readonly hidden?: boolean;
+  readonly hidden?: HiddenVisibility;
+}
+/**
+ * An ellipsis term, which represents a summary placeholder in usage output.
+ * Unlike {@link passthrough}, this term has no parsing semantics and is used
+ * only for display.
+ * @since 1.0.0
+ */ | {
+  /**
+   * The type of the term, which is always `"ellipsis"` for this term.
+   */
+  readonly type: "ellipsis";
 };
 /**
  * Represents a command-line usage description, which is a sequence of
@@ -330,4 +368,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };
+export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.js

@@ -1,5 +1,37 @@
 //#region src/usage.ts
 /**
+* Returns whether the term should be hidden from usage output.
+*/
+function isUsageHidden(hidden) {
+	return hidden === true || hidden === "usage" || hidden === "help";
+}
+/**
+* Returns whether the term should be hidden from documentation output.
+*/
+function isDocHidden(hidden) {
+	return hidden === true || hidden === "doc" || hidden === "help";
+}
+/**
+* Returns whether the term should be hidden from suggestion/error candidates.
+*/
+function isSuggestionHidden(hidden) {
+	return hidden === true;
+}
+/**
+* Merges two hidden visibility settings by taking the union of restrictions.
+*/
+function mergeHidden(a, b) {
+	if (a == null) return b;
+	if (b == null) return a;
+	if (a === true || b === true) return true;
+	if (a === false) return b;
+	if (b === false) return a;
+	if (a === b) return a;
+	if (a === "help" || b === "help") return "help";
+	if ((a === "usage" || a === "doc") && (b === "usage" || b === "doc")) return "help";
+	return a;
+}
+/**
 * Extracts all option names from a usage description.
 *
 * This function recursively traverses a {@link Usage} tree and collects all
@@ -24,7 +56,7 @@ function extractOptionNames(usage) {
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "option") {
-			if (term.hidden) continue;
+			if (isSuggestionHidden(term.hidden)) continue;
 			for (const name of term.names) names.add(name);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -57,7 +89,7 @@ function extractCommandNames(usage) {
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "command") {
-			if (term.hidden) continue;
+			if (isSuggestionHidden(term.hidden)) continue;
 			names.add(term.name);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -91,7 +123,7 @@ function extractArgumentMetavars(usage) {
 	function traverseUsage(terms) {
 		if (!terms || !Array.isArray(terms)) return;
 		for (const term of terms) if (term.type === "argument") {
-			if (term.hidden) continue;
+			if (isSuggestionHidden(term.hidden)) continue;
 			metavars.add(term.metavar);
 		} else if (term.type === "optional" || term.type === "multiple") traverseUsage(term.terms);
 		else if (term.type === "exclusive") for (const exclusiveUsage of term.terms) traverseUsage(exclusiveUsage);
@@ -116,14 +148,14 @@ function extractArgumentMetavars(usage) {
 * @returns A formatted string representation of the usage description.
 */
 function formatUsage(programName, usage, options = {}) {
-	usage = normalizeUsage(usage);
+	usage = normalizeUsage(filterUsageForDisplay(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) {
 				const firstTerm = command[0];
-				if (firstTerm?.type === "command" && firstTerm.hidden) continue;
+				if (firstTerm?.type === "command" && isUsageHidden(firstTerm.hidden)) continue;
 				if (usage.length > 1) command = [...usage.slice(0, -1), ...command];
 				lines.push(formatUsage(programName, command, options));
 			}
@@ -204,9 +236,47 @@ function normalizeUsageTerm(term) {
 		};
 	} else return term;
 }
+function filterUsageForDisplay(usage) {
+	const terms = [];
+	for (const term of usage) {
+		if ((term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") && isUsageHidden(term.hidden)) continue;
+		if (term.type === "optional") {
+			const filtered = filterUsageForDisplay(term.terms);
+			if (filtered.length > 0) terms.push({
+				type: "optional",
+				terms: filtered
+			});
+			continue;
+		}
+		if (term.type === "multiple") {
+			const filtered = filterUsageForDisplay(term.terms);
+			if (filtered.length > 0) terms.push({
+				type: "multiple",
+				terms: filtered,
+				min: term.min
+			});
+			continue;
+		}
+		if (term.type === "exclusive") {
+			const filteredBranches = term.terms.map((branch) => {
+				const first = branch[0];
+				if (first?.type === "command" && isUsageHidden(first.hidden)) return [];
+				return filterUsageForDisplay(branch);
+			}).filter((branch) => branch.length > 0);
+			if (filteredBranches.length > 0) terms.push({
+				type: "exclusive",
+				terms: filteredBranches
+			});
+			continue;
+		}
+		terms.push(term);
+	}
+	return terms;
+}
 function* formatUsageTerms(terms, options) {
 	let i = 0;
 	for (const t of terms) {
+		if ("hidden" in t && (t.type === "argument" || t.type === "option" || t.type === "command" || t.type === "passthrough") && isUsageHidden(t.hidden)) continue;
 		if (i > 0) yield {
 			text: " ",
 			width: 1
@@ -225,9 +295,11 @@ function* formatUsageTerms(terms, options) {
 * @returns A formatted string representation of the usage term.
 */
 function formatUsageTerm(term, options = {}) {
+	const visibleTerms = filterUsageForDisplay([term]);
+	if (visibleTerms.length < 1) return "";
 	let lineWidth = 0;
 	let output = "";
-	for (const { text, width } of formatUsageTermInternal(term, options)) {
+	for (const { text, width } of formatUsageTermInternal(visibleTerms[0], options)) {
 		if (options.maxWidth != null && lineWidth + width > options.maxWidth) {
 			output += "\n";
 			lineWidth = 0;
@@ -346,8 +418,14 @@ function* formatUsageTermInternal(term, options) {
 			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
 			width: 5
 		};
+	} else if (term.type === "ellipsis") {
+		const text = "...";
+		yield {
+			text: options?.colors ? `\x1b[2m${text}\x1b[0m` : text,
+			width: 3
+		};
 	} else throw new TypeError(`Unknown usage term type: ${term["type"]}.`);
 }
 
 //#endregion
-export { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, normalizeUsage };
+export { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };