@optique/core/dist/usage.d.ts

Type-safe combinatorial command-line interface parser

//#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 };