@optique/core 1.0.0-dev.1452 → 1.0.0-dev.1458

package/dist/doc.cjs

@@ -2,6 +2,20 @@ const require_message = require('./message.cjs');
 const require_usage = require('./usage.cjs');
 
 //#region src/doc.ts
+/**
+* Returns whether a doc entry's term is hidden from documentation.
+* Only term types with a `hidden` field (argument, option, command,
+* passthrough) are checked; other types always return `false`.
+*
+* @param entry The doc entry to check.
+* @returns `true` if the entry should be hidden from documentation.
+* @since 1.0.0
+*/
+function isDocEntryHidden(entry) {
+	const term = entry.term;
+	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return require_usage.isDocHidden(term.hidden);
+	return false;
+}
 function getDocEntryKey(entry) {
 	const term = entry.term;
 	switch (term.type) {
@@ -13,21 +27,25 @@ function getDocEntryKey(entry) {
 }
 /**
 * Removes duplicate {@link DocEntry} values that share the same surface
-* syntax (same term type and identifying names).  When duplicates exist,
-* the first occurrence is kept and later ones are discarded.
+* syntax (same term type and identifying names).  Doc-hidden entries are
+* filtered out first so they cannot influence the ordering of visible
+* entries.  Among the remaining visible entries, the first occurrence is
+* kept and later duplicates are discarded.
 *
 * Positional argument entries are never deduplicated because they are
 * distinguished by position, not by metavar, and {@link DocEntry} does
 * not carry position information.
 *
 * @param entries The entries to deduplicate.
-* @returns A new array with duplicates removed, preserving insertion order.
+* @returns A new array with hidden entries removed and duplicates
+*   collapsed, preserving insertion order of visible entries.
 * @since 1.0.0
 */
 function deduplicateDocEntries(entries) {
 	const seen = /* @__PURE__ */ new Set();
 	const result = [];
 	for (const entry of entries) {
+		if (isDocEntryHidden(entry)) continue;
 		if (entry.term.type === "argument") {
 			result.push(entry);
 			continue;
@@ -52,18 +70,22 @@ function deduplicateDocEntries(entries) {
 function deduplicateDocFragments(fragments) {
 	const untitledSeen = /* @__PURE__ */ new Set();
 	const titledSectionMap = /* @__PURE__ */ new Map();
+	const titledSectionPositioned = /* @__PURE__ */ new Set();
 	const slots = [];
-	for (const fragment of fragments) if (fragment.type === "entry") if (fragment.term.type === "argument") slots.push(fragment);
-	else {
-		const key = getDocEntryKey(fragment);
-		if (!untitledSeen.has(key)) {
-			untitledSeen.add(key);
-			slots.push(fragment);
+	for (const fragment of fragments) if (fragment.type === "entry") {
+		if (isDocEntryHidden(fragment)) continue;
+		if (fragment.term.type === "argument") slots.push(fragment);
+		else {
+			const key = getDocEntryKey(fragment);
+			if (!untitledSeen.has(key)) {
+				untitledSeen.add(key);
+				slots.push(fragment);
+			}
 		}
-	}
-	else if (fragment.title == null) {
+	} else if (fragment.title == null) {
 		const dedupedEntries = [];
 		for (const entry of fragment.entries) {
+			if (isDocEntryHidden(entry)) continue;
 			if (entry.term.type === "argument") {
 				dedupedEntries.push(entry);
 				continue;
@@ -80,8 +102,9 @@ function deduplicateDocFragments(fragments) {
 			entries: dedupedEntries
 		});
 	} else {
-		if (!titledSectionMap.has(fragment.title)) {
-			titledSectionMap.set(fragment.title, []);
+		if (!titledSectionMap.has(fragment.title)) titledSectionMap.set(fragment.title, []);
+		if (!titledSectionPositioned.has(fragment.title) && fragment.entries.some((e) => !isDocEntryHidden(e))) {
+			titledSectionPositioned.add(fragment.title);
 			slots.push(fragment.title);
 		}
 		titledSectionMap.get(fragment.title).push(...fragment.entries);
@@ -442,4 +465,5 @@ function lastLineVisibleLength(text$1) {
 exports.cloneDocEntry = cloneDocEntry;
 exports.deduplicateDocEntries = deduplicateDocEntries;
 exports.deduplicateDocFragments = deduplicateDocFragments;
-exports.formatDocPage = formatDocPage;
+exports.formatDocPage = formatDocPage;
+exports.isDocEntryHidden = isDocEntryHidden;

package/dist/doc.d.cts

@@ -103,17 +103,30 @@ interface DocFragments {
    */
   readonly footer?: Message;
 }
+/**
+ * Returns whether a doc entry's term is hidden from documentation.
+ * Only term types with a `hidden` field (argument, option, command,
+ * passthrough) are checked; other types always return `false`.
+ *
+ * @param entry The doc entry to check.
+ * @returns `true` if the entry should be hidden from documentation.
+ * @since 1.0.0
+ */
+declare function isDocEntryHidden(entry: DocEntry): boolean;
 /**
  * Removes duplicate {@link DocEntry} values that share the same surface
- * syntax (same term type and identifying names).  When duplicates exist,
- * the first occurrence is kept and later ones are discarded.
+ * syntax (same term type and identifying names).  Doc-hidden entries are
+ * filtered out first so they cannot influence the ordering of visible
+ * entries.  Among the remaining visible entries, the first occurrence is
+ * kept and later duplicates are discarded.
  *
  * Positional argument entries are never deduplicated because they are
  * distinguished by position, not by metavar, and {@link DocEntry} does
  * not carry position information.
  *
  * @param entries The entries to deduplicate.
- * @returns A new array with duplicates removed, preserving insertion order.
+ * @returns A new array with hidden entries removed and duplicates
+ *   collapsed, preserving insertion order of visible entries.
  * @since 1.0.0
  */
 declare function deduplicateDocEntries(entries: readonly DocEntry[]): DocEntry[];
@@ -325,4 +338,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden };

package/dist/doc.d.ts

@@ -103,17 +103,30 @@ interface DocFragments {
    */
   readonly footer?: Message;
 }
+/**
+ * Returns whether a doc entry's term is hidden from documentation.
+ * Only term types with a `hidden` field (argument, option, command,
+ * passthrough) are checked; other types always return `false`.
+ *
+ * @param entry The doc entry to check.
+ * @returns `true` if the entry should be hidden from documentation.
+ * @since 1.0.0
+ */
+declare function isDocEntryHidden(entry: DocEntry): boolean;
 /**
  * Removes duplicate {@link DocEntry} values that share the same surface
- * syntax (same term type and identifying names).  When duplicates exist,
- * the first occurrence is kept and later ones are discarded.
+ * syntax (same term type and identifying names).  Doc-hidden entries are
+ * filtered out first so they cannot influence the ordering of visible
+ * entries.  Among the remaining visible entries, the first occurrence is
+ * kept and later duplicates are discarded.
  *
  * Positional argument entries are never deduplicated because they are
  * distinguished by position, not by metavar, and {@link DocEntry} does
  * not carry position information.
  *
  * @param entries The entries to deduplicate.
- * @returns A new array with duplicates removed, preserving insertion order.
+ * @returns A new array with hidden entries removed and duplicates
+ *   collapsed, preserving insertion order of visible entries.
  * @since 1.0.0
  */
 declare function deduplicateDocEntries(entries: readonly DocEntry[]): DocEntry[];
@@ -325,4 +338,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden };

package/dist/doc.js

@@ -1,7 +1,21 @@
 import { cloneMessage, formatMessage, text } from "./message.js";
-import { cloneUsageTerm, formatUsage, formatUsageTerm } from "./usage.js";
+import { cloneUsageTerm, formatUsage, formatUsageTerm, isDocHidden } from "./usage.js";
 
 //#region src/doc.ts
+/**
+* Returns whether a doc entry's term is hidden from documentation.
+* Only term types with a `hidden` field (argument, option, command,
+* passthrough) are checked; other types always return `false`.
+*
+* @param entry The doc entry to check.
+* @returns `true` if the entry should be hidden from documentation.
+* @since 1.0.0
+*/
+function isDocEntryHidden(entry) {
+	const term = entry.term;
+	if (term.type === "argument" || term.type === "option" || term.type === "command" || term.type === "passthrough") return isDocHidden(term.hidden);
+	return false;
+}
 function getDocEntryKey(entry) {
 	const term = entry.term;
 	switch (term.type) {
@@ -13,21 +27,25 @@ function getDocEntryKey(entry) {
 }
 /**
 * Removes duplicate {@link DocEntry} values that share the same surface
-* syntax (same term type and identifying names).  When duplicates exist,
-* the first occurrence is kept and later ones are discarded.
+* syntax (same term type and identifying names).  Doc-hidden entries are
+* filtered out first so they cannot influence the ordering of visible
+* entries.  Among the remaining visible entries, the first occurrence is
+* kept and later duplicates are discarded.
 *
 * Positional argument entries are never deduplicated because they are
 * distinguished by position, not by metavar, and {@link DocEntry} does
 * not carry position information.
 *
 * @param entries The entries to deduplicate.
-* @returns A new array with duplicates removed, preserving insertion order.
+* @returns A new array with hidden entries removed and duplicates
+*   collapsed, preserving insertion order of visible entries.
 * @since 1.0.0
 */
 function deduplicateDocEntries(entries) {
 	const seen = /* @__PURE__ */ new Set();
 	const result = [];
 	for (const entry of entries) {
+		if (isDocEntryHidden(entry)) continue;
 		if (entry.term.type === "argument") {
 			result.push(entry);
 			continue;
@@ -52,18 +70,22 @@ function deduplicateDocEntries(entries) {
 function deduplicateDocFragments(fragments) {
 	const untitledSeen = /* @__PURE__ */ new Set();
 	const titledSectionMap = /* @__PURE__ */ new Map();
+	const titledSectionPositioned = /* @__PURE__ */ new Set();
 	const slots = [];
-	for (const fragment of fragments) if (fragment.type === "entry") if (fragment.term.type === "argument") slots.push(fragment);
-	else {
-		const key = getDocEntryKey(fragment);
-		if (!untitledSeen.has(key)) {
-			untitledSeen.add(key);
-			slots.push(fragment);
+	for (const fragment of fragments) if (fragment.type === "entry") {
+		if (isDocEntryHidden(fragment)) continue;
+		if (fragment.term.type === "argument") slots.push(fragment);
+		else {
+			const key = getDocEntryKey(fragment);
+			if (!untitledSeen.has(key)) {
+				untitledSeen.add(key);
+				slots.push(fragment);
+			}
 		}
-	}
-	else if (fragment.title == null) {
+	} else if (fragment.title == null) {
 		const dedupedEntries = [];
 		for (const entry of fragment.entries) {
+			if (isDocEntryHidden(entry)) continue;
 			if (entry.term.type === "argument") {
 				dedupedEntries.push(entry);
 				continue;
@@ -80,8 +102,9 @@ function deduplicateDocFragments(fragments) {
 			entries: dedupedEntries
 		});
 	} else {
-		if (!titledSectionMap.has(fragment.title)) {
-			titledSectionMap.set(fragment.title, []);
+		if (!titledSectionMap.has(fragment.title)) titledSectionMap.set(fragment.title, []);
+		if (!titledSectionPositioned.has(fragment.title) && fragment.entries.some((e) => !isDocEntryHidden(e))) {
+			titledSectionPositioned.add(fragment.title);
 			slots.push(fragment.title);
 		}
 		titledSectionMap.get(fragment.title).push(...fragment.entries);
@@ -439,4 +462,4 @@ function lastLineVisibleLength(text$1) {
 }
 
 //#endregion
-export { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage };
+export { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden };

package/dist/index.cjs

@@ -79,6 +79,7 @@ exports.isDeferredParseState = require_dependency.isDeferredParseState;
 exports.isDependencySource = require_dependency.isDependencySource;
 exports.isDependencySourceState = require_dependency.isDependencySourceState;
 exports.isDerivedValueParser = require_dependency.isDerivedValueParser;
+exports.isDocEntryHidden = require_doc.isDocEntryHidden;
 exports.isDocHidden = require_usage.isDocHidden;
 exports.isNonEmptyString = require_nonempty.isNonEmptyString;
 exports.isPendingDependencySourceState = require_dependency.isPendingDependencySourceState;

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./anno
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage } from "./doc.cjs";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.cjs";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./anno
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage } from "./doc.js";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -3,7 +3,7 @@ import { commandLine, envVar, formatMessage, lineBreak, link, message, metavar,
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
 import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
-import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage } from "./doc.js";
+import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
@@ -12,4 +12,4 @@ import { argument, command, constant, fail, flag, option, passThrough } from "./
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, deduplicateDocEntries, deduplicateDocFragments, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/parser.cjs

@@ -385,28 +385,33 @@ function buildDocPage(parser, context, args) {
 	let untitledSection = null;
 	const titledSectionMap = /* @__PURE__ */ new Map();
 	for (const fragment of fragments) if (fragment.type === "entry") {
+		if (require_doc.isDocEntryHidden(fragment)) continue;
 		if (untitledSection == null) {
 			untitledSection = { entries: [] };
 			buildingSections.push(untitledSection);
 		}
 		untitledSection.entries.push(require_doc.cloneDocEntry(fragment));
-	} else if (fragment.type === "section") if (fragment.title == null) {
-		if (untitledSection == null) {
-			untitledSection = { entries: [] };
-			buildingSections.push(untitledSection);
-		}
-		untitledSection.entries.push(...fragment.entries.map(require_doc.cloneDocEntry));
-	} else {
-		let section = titledSectionMap.get(fragment.title);
-		if (section == null) {
-			section = {
-				title: fragment.title,
-				entries: []
-			};
-			titledSectionMap.set(fragment.title, section);
-			buildingSections.push(section);
+	} else if (fragment.type === "section") {
+		const visible = fragment.entries.filter((e) => !require_doc.isDocEntryHidden(e));
+		if (visible.length === 0) continue;
+		if (fragment.title == null) {
+			if (untitledSection == null) {
+				untitledSection = { entries: [] };
+				buildingSections.push(untitledSection);
+			}
+			untitledSection.entries.push(...visible.map(require_doc.cloneDocEntry));
+		} else {
+			let section = titledSectionMap.get(fragment.title);
+			if (section == null) {
+				section = {
+					title: fragment.title,
+					entries: []
+				};
+				titledSectionMap.set(fragment.title, section);
+				buildingSections.push(section);
+			}
+			section.entries.push(...visible.map(require_doc.cloneDocEntry));
 		}
-		section.entries.push(...fragment.entries.map(require_doc.cloneDocEntry));
 	}
 	const sections = buildingSections;
 	const usage = require_usage.cloneUsage(require_usage.normalizeUsage(parser.usage));

package/dist/parser.js

@@ -2,7 +2,7 @@ import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotatio
 import { cloneMessage, message } from "./message.js";
 import { dispatchByMode } from "./mode-dispatch.js";
 import { cloneUsage, normalizeUsage } from "./usage.js";
-import { cloneDocEntry } from "./doc.js";
+import { cloneDocEntry, isDocEntryHidden } from "./doc.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
@@ -385,28 +385,33 @@ function buildDocPage(parser, context, args) {
 	let untitledSection = null;
 	const titledSectionMap = /* @__PURE__ */ new Map();
 	for (const fragment of fragments) if (fragment.type === "entry") {
+		if (isDocEntryHidden(fragment)) continue;
 		if (untitledSection == null) {
 			untitledSection = { entries: [] };
 			buildingSections.push(untitledSection);
 		}
 		untitledSection.entries.push(cloneDocEntry(fragment));
-	} else if (fragment.type === "section") if (fragment.title == null) {
-		if (untitledSection == null) {
-			untitledSection = { entries: [] };
-			buildingSections.push(untitledSection);
-		}
-		untitledSection.entries.push(...fragment.entries.map(cloneDocEntry));
-	} else {
-		let section = titledSectionMap.get(fragment.title);
-		if (section == null) {
-			section = {
-				title: fragment.title,
-				entries: []
-			};
-			titledSectionMap.set(fragment.title, section);
-			buildingSections.push(section);
+	} else if (fragment.type === "section") {
+		const visible = fragment.entries.filter((e) => !isDocEntryHidden(e));
+		if (visible.length === 0) continue;
+		if (fragment.title == null) {
+			if (untitledSection == null) {
+				untitledSection = { entries: [] };
+				buildingSections.push(untitledSection);
+			}
+			untitledSection.entries.push(...visible.map(cloneDocEntry));
+		} else {
+			let section = titledSectionMap.get(fragment.title);
+			if (section == null) {
+				section = {
+					title: fragment.title,
+					entries: []
+				};
+				titledSectionMap.set(fragment.title, section);
+				buildingSections.push(section);
+			}
+			section.entries.push(...visible.map(cloneDocEntry));
 		}
-		section.entries.push(...fragment.entries.map(cloneDocEntry));
 	}
 	const sections = buildingSections;
 	const usage = cloneUsage(normalizeUsage(parser.usage));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1452+b060cbd3",
+  "version": "1.0.0-dev.1458+3f4a79f6",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",