import { NonEmptyString } from "./nonempty.js";

//#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`)
 *
 * Each prefix must be followed by at least one character, so bare prefixes
 * like `"-"`, `"/"`, or `"+"` are rejected at compile time.  Due to
 * TypeScript template literal limitations, `"--"` still matches the
 * `-${NonEmptyString}` branch and is only rejected at runtime by the
 * `option()` and `flag()` validators.
 */
type OptionName = `--${NonEmptyString}` | `-${NonEmptyString}` | `/${NonEmptyString}` | `+${NonEmptyString}`;
/**
 * 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.
 */
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: NonEmptyString;
  /**
   * Visibility controls for this term.
   * @since 0.9.0
   */
  readonly hidden?: HiddenVisibility;
}
/**
 * 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?: NonEmptyString;
  /**
   * Visibility controls for this term.
   * @since 0.9.0
   */
  readonly hidden?: HiddenVisibility;
}
/**
 * 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;
  /**
   * Additional command names that invoke the same parser.
   * These aliases participate in parsing, completion, and typo
   * suggestions, but are not rendered in usage or documentation output.
   * @since 1.1.0
   */
  readonly aliases?: readonly string[];
  /**
   * Additional command names that invoke the same parser but are not
   * rendered or suggested.  They are still available to parsers and
   * suggestion matchers so alias typos can resolve to the canonical command.
   * @since 1.1.0
   */
  readonly hiddenAliases?: readonly string[];
  /**
   * 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?: HiddenVisibility;
}
/**
 * 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[];
}
/**
 * A sequence term, which preserves the declaration order of its child
 * terms through usage normalization.
 *
 * This is used by ordered parser combinators where argument/command/option
 * order is part of the accepted grammar.
 * @since 1.1.0
 */ | {
  /**
   * The type of the term, which is always `"sequence"` for this term.
   */
  readonly type: "sequence";
  /**
   * Terms that must be displayed in the given order.
   */
  readonly terms: Usage;
}
/**
 * A literal term, which represents a fixed string value in the command-line
 * usage. Unlike metavars which are placeholders for user-provided values,
 * literals represent exact strings that must be typed as-is.
 * @since 0.8.0
 */ | {
  /**
   * The type of the term, which is always `"literal"` for this term.
   */
  readonly type: "literal";
  /**
   * The literal value that must be provided exactly as written.
   */
  readonly value: string;
  /**
   * When `true`, this literal was derived from an option's metavar by
   * `appendLiteralToUsage()` in `conditional()` and represents an option
   * value, not a standalone positional token.
   * {@link extractLeadingLiteralValues} and the `skipOptionValueLiterals`
   * mode of `branchConsumesToken()` use this to distinguish option values
   * from real positional literals.  {@link extractLeadingOptionNames} and
   * {@link extractLeadingCommandNames} intentionally still treat these
   * literals as positional gates.
   * @since 1.0.0
   */
  readonly optionValue?: boolean;
}
/**
 * A pass-through term, which represents unrecognized options that are
 * collected and passed through to an underlying tool or command.
 * @since 0.8.0
 */ | {
  /**
   * The type of the term, which is always `"passthrough"` for this term.
   */
  readonly type: "passthrough";
  /**
   * Visibility controls for this term.
   * @since 0.9.0
   */
  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
 * {@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[];
/**
 * Extracts all option names from a usage description.
 *
 * This function recursively traverses a {@link Usage} tree and collects all
 * option names defined within it, including those nested inside optional,
 * multiple, and exclusive terms.
 *
 * @param usage The usage description to extract option names from.
 * @param includeHidden Whether to include fully hidden options (`hidden: true`)
 *   in the result.  Defaults to `false`.
 * @returns A set containing all option names found in the usage description.
 *
 * @example
 * ```typescript
 * const usage: Usage = [
 *   { type: "option", names: ["--verbose", "-v"] },
 *   { type: "option", names: ["--quiet", "-q"] },
 * ];
 * const names = extractOptionNames(usage);
 * // names = Set(["--verbose", "-v", "--quiet", "-q"])
 * ```
 */
declare function extractOptionNames(usage: Usage, includeHidden?: boolean): Set<string>;
/**
 * Extracts all command names from a Usage array.
 *
 * This function recursively traverses the usage structure and collects
 * all command names, similar to {@link extractOptionNames}.
 *
 * @param usage The usage structure to extract command names from.
 * @param includeHidden Whether to include fully hidden commands
 *   (`hidden: true`) in the result.  Defaults to `false`.
 * @returns A set of all command names found in the usage structure.
 *
 * @example
 * ```typescript
 * const usage: Usage = [
 *   { type: "command", name: "build" },
 *   { type: "command", name: "test" },
 * ];
 * const names = extractCommandNames(usage);
 * // names = Set(["build", "test"])
 * ```
 * @since 0.7.0
 */
declare function extractCommandNames(usage: Usage, includeHidden?: boolean): Set<string>;
/**
 * Extracts all literal values from a usage description.
 *
 * This function recursively traverses the usage tree and collects all
 * `literal` term values.  Literal values represent fixed strings that
 * the user must type (e.g., conditional discriminator values like
 * `"server"` in `conditional(option("--mode", string()), { server: ... })`).
 *
 * @param usage The usage description to extract literal values from.
 * @returns A set of all literal values found in the usage description.
 * @since 1.0.0
 */
declare function extractLiteralValues(usage: Usage): Set<string>;
/**
 * Extracts all argument metavars from a Usage array.
 *
 * This function recursively traverses the usage structure and collects
 * all argument metavariable names, similar to {@link extractOptionNames}
 * and {@link extractCommandNames}.
 *
 * @param usage The usage structure to extract argument metavars from.
 * @returns A Set of all argument metavars found in the usage structure.
 *
 * @example
 * ```typescript
 * const usage: Usage = [
 *   { type: "argument", metavar: "FILE" },
 *   { type: "argument", metavar: "OUTPUT" },
 * ];
 * const metavars = extractArgumentMetavars(usage);
 * // metavars = Set(["FILE", "OUTPUT"])
 * ```
 * @since 0.9.0
 */
declare function extractArgumentMetavars(usage: Usage): Set<string>;
/**
 * 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.
 * @throws {TypeError} If `programName` is not a string, is empty,
 *         whitespace-only, or contains control characters.
 */
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 three main operations:
 *
 * 1. *Stripping*: Removes degenerate terms that would render as empty or
 *    malformed output, such as options with no names, commands with empty
 *    names, arguments with empty metavars, and container terms (`optional`,
 *    `multiple`, `exclusive`) whose top-level terms array is empty after
 *    recursive normalization.  Exclusive branches representing valid
 *    zero-token alternatives (e.g., `conditional()` default branches or
 *    `optional(constant(...))`) and empty-value literals are preserved.
 *    Only branches that become empty because all their content was
 *    malformed are removed.
 *
 * 2. *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.
 *    Similarly, nested optional terms are collapsed:
 *    `optional(optional(X))` becomes `optional(X)` when the outer optional
 *    contains only a single inner optional term.
 *
 * 3. *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 degenerate terms removed,
 *          nested exclusive and optional terms flattened, and remaining
 *          terms sorted for optimal readability.
 */
declare function normalizeUsage(usage: Usage): Usage;
/**
 * Creates a deep clone of a single {@link UsageTerm}.  Recursive term
 * variants (`optional`, `multiple`, `exclusive`) are cloned recursively.
 * For `command` terms, a function-valued `usageLine` is preserved by
 * reference (functions are stateless callbacks), while an array-valued
 * `usageLine` is deep-cloned.
 *
 * @param term The usage term to clone.
 * @returns A structurally equal but referentially distinct copy.
 * @since 1.0.0
 */
declare function cloneUsageTerm(term: UsageTerm): UsageTerm;
/**
 * Creates a deep clone of a {@link Usage} array and all of its terms.
 *
 * @param usage The usage array to clone.
 * @returns A mutable array of deeply cloned usage terms.
 * @since 1.0.0
 */
declare function cloneUsage(usage: Usage): UsageTerm[];
/**
 * 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;
  /**
   * The rendering context, which determines which hidden visibility values
   * cause terms to be filtered out.
   *
   * - `"usage"` (default): filters terms hidden from usage output
   * - `"doc"`: filters terms hidden from documentation output
   * @default `"usage"`
   * @since 1.0.0
   */
  readonly context?: "usage" | "doc";
}
/**
 * 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 { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };