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

Type-safe combinatorial command-line interface parser

//#region src/message.d.ts
/**
 * Represents a single term in a message, which can be a text, an option
 * name, a list of option names, a metavariable, a value, or a list of
 * consecutive values.
 */
type MessageTerm =
/**
 * A plain text term in the message.
 */
{
  /**
   * The type of the term, which is always `"text"` for plain text.
   */
  readonly type: "text";
  /**
   * The text content of the term.
   */
  readonly text: string;
}
/**
 * An option name term in the message, which can be a single
 * option name.  Although it is named option name, it can also
 * represent a subcommand.
 */ | {
  /**
   * The type of the term, which is `"optionName"` for a single option name.
   */
  readonly type: "optionName";
  /**
   * The name of the option, which can be a short or long option name.
   * For example, `"-f"` or `"--foo"`.
   */
  readonly optionName: string;
}
/**
 * A list of option names term in the message, which can be a
 * list of option names.
 */ | {
  /**
   * The type of the term, which is `"optionNames"` for a list of option
   * names.
   */
  readonly type: "optionNames";
  /**
   * The list of option names, which can include both short and long
   * option names.  For example, `["--foo", "--bar"]`.
   */
  readonly optionNames: readonly string[];
}
/**
 * A metavariable term in the message, which can be a single
 * metavariable.
 */ | {
  /**
   * The type of the term, which is `"metavar"` for a metavariable.
   */
  readonly type: "metavar";
  /**
   * The metavariable name, which is a string that represents
   * a variable in the message.  For example, `"VALUE"` or `"ARG"`.
   */
  readonly metavar: string;
}
/**
 * A value term in the message, which can be a single value.
 */ | {
  /**
   * The type of the term, which is `"value"` for a single value.
   */
  readonly type: "value";
  /**
   * The value, which can be any string representation of a value.
   * For example, `"42"` or `"hello"`.
   */
  readonly value: string;
}
/**
 * A list of values term in the message, which can be a
 * list of values.
 */ | {
  /**
   * The type of the term, which is `"values"` for a list of consecutive
   * values.
   */
  readonly type: "values";
  /**
   * The list of values, which can include multiple string
   * representations of consecutive values.  For example, `["42", "hello"]`.
   */
  readonly values: readonly string[];
};
/**
 * Type representing a message that can include styled/colored values.
 * This type is used to create structured messages that can be
 * displayed to the user with specific formatting.
 */
type Message = readonly MessageTerm[];
/**
 * Creates a structured message with template strings and values.
 *
 * This function allows creating messages where specific values can be
 * highlighted or styled differently when displayed to the user.
 *
 * @example
 * ```typescript
 * const error = message`Expected number between ${min} and ${max}, got ${value}`;
 * const concat = message`${optionName("--age")}: ${error}`;
 * ```
 *
 * @param message Template strings array (from template literal).
 * @param values Values to be interpolated into the template.
 * @returns A structured Message object.
 */
declare function message(message: TemplateStringsArray, ...values: readonly (MessageTerm | Message | string)[]): Message;
/**
 * Creates a {@link MessageTerm} for plain text.  Usually used for
 * dynamically generated messages.
 * @param text The plain text to be included in the message.
 * @returns A {@link MessageTerm} representing the plain text.
 */
declare function text(text: string): MessageTerm;
/**
 * Creates a {@link MessageTerm} for an option name.
 * @param name The name of the option, which can be a short or long option name.
 *             For example, `"-f"` or `"--foo"`.
 * @returns A {@link MessageTerm} representing the option name.
 */
declare function optionName(name: string): MessageTerm;
/**
 * Creates a {@link MessageTerm} for a list of option names.
 * @param names The list of option names, which can include both short and long
 *              option names. For example, `["--foo", "--bar"]`.
 * @returns A {@link MessageTerm} representing the list of option names.
 */
declare function optionNames(names: readonly string[]): MessageTerm;
/**
 * Creates a {@link MessageTerm} for a metavariable.
 * @param metavar The metavariable name, which is a string that represents
 *                a variable in the message. For example, `"VALUE"` or
 *                `"ARG"`.
 * @returns A {@link MessageTerm} representing the metavariable.
 */
declare function metavar(metavar: string): MessageTerm;
/**
 * Creates a {@link MessageTerm} for a single value.  However, you usually
 * don't need to use this function directly, as {@link message} string template
 * will automatically create a {@link MessageTerm} for a value when
 * you use a string in a template literal.
 * @param value The value, which can be any string representation of a value.
 *              For example, `"42"` or `"hello"`.
 * @returns A {@link MessageTerm} representing the value.
 */
declare function value(value: string): MessageTerm;
/**
 * Creates a {@link MessageTerm} for a list of consecutive values.
 * @param values The list of consecutive values, which can include multiple
 *               string representations of consecutive values.
 *               For example, `["42", "hello"]`.
 * @returns A {@link MessageTerm} representing the list of values.
 */
declare function values(values: readonly string[]): MessageTerm;
/**
 * Options for the {@link formatMessage} function.
 */
interface MessageFormatOptions {
  /**
   * Whether to use colors in the formatted message.  If `true`,
   * the formatted message will include ANSI escape codes for colors.
   * If `false`, the message will be plain text without colors.
   * @default `false`
   */
  readonly colors?: boolean;
  /**
   * Whether to use quotes around values in the formatted message.
   * If `true`, values will be wrapped in quotes (e.g., `"value"`).
   * If `false`, values will be displayed without quotes.
   * @default `true`
   */
  readonly quotes?: boolean;
  /**
   * The maximum width of the formatted message.  If specified,
   * the message will be wrapped to fit within this width.
   * If not specified, the message will not be wrapped.
   * @default `undefined`
   */
  readonly maxWidth?: number;
}
/**
 * Formats a {@link Message} into a human-readable string for
 * the terminal.
 * @param msg The message to format, which is an array of
 *              {@link MessageTerm} objects.
 * @param options Optional formatting options to customize the output.
 * @returns A formatted string representation of the message.
 */
declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
//#endregion
export { Message, MessageFormatOptions, MessageTerm, formatMessage, message, metavar, optionName, optionNames, text, value, values };