import { Message } from "./message.js";
import { HiddenVisibility, OptionName, Usage } from "./usage.js";
import { ValueParser, ValueParserResult } from "./valueparser.js";
import { Mode, Parser } from "./internal/parser.js";

//#region src/primitives.d.ts
/** @internal */
type OptionState<T> = ValueParserResult<T> | undefined;
/**
 * Creates a parser that always succeeds without consuming any input and
 * produces a constant value of the type {@link T}.
 * @template T The type of the constant value produced by the parser.
 */
declare function constant<const T>(value: T): Parser<"sync", T, T>;
/**
 * Creates a parser that always fails without consuming any input.
 *
 * This is the counterpart to {@link constant}: while `constant(value)` always
 * succeeds, `fail<T>()` always fails.  At the type level it is declared to
 * produce a value of type `T`, so it composes seamlessly with other parsers
 * that expect `Parser<"sync", T, …>`.
 *
 * The primary use case is as the inner parser for
 * `bindConfig(fail<T>(), { … })` when a value should *only* come from a
 * config file and has no corresponding CLI flag or argument.  Because `fail()`
 * always fails, `bindConfig` will always fall back to the config file (or the
 * supplied default).
 *
 * @template T The type of value this parser is declared to produce.
 * @returns A {@link Parser} that always fails at parse time and always fails at
 *          complete time.
 * @since 1.0.0
 */
declare function fail<T>(): Parser<"sync", T, undefined>;
/**
 * Options for the {@link option} parser.
 */
interface OptionOptions {
  /**
   * The description of the option, which can be used for help messages.
   */
  readonly description?: Message;
  /**
   * Controls option visibility:
   *
   * - `true`: hide from usage, docs, and suggestions
   * - `"usage"`: hide from usage only
   * - `"doc"`: hide from docs only
   * - `"help"`: hide from usage and docs, keep suggestions
   *
   * @since 0.9.0
   */
  readonly hidden?: HiddenVisibility;
  /**
   * Error message customization options.
   * @since 0.5.0
   */
  readonly errors?: OptionErrorOptions;
}
/**
 * Options for customizing error messages in the {@link option} parser.
 * @since 0.5.0
 */
interface OptionErrorOptions {
  /**
   * Custom error message when the option is missing (for required options).
   * Can be a static message or a function that receives the option names.
   */
  missing?: Message | ((optionNames: readonly string[]) => Message);
  /**
   * Custom error message when options are terminated (after `--`).
   */
  optionsTerminated?: Message;
  /**
   * Custom error message when input is empty but option is expected.
   */
  endOfInput?: Message;
  /**
   * Custom error message when option is used multiple times.
   * Can be a static message or a function that receives the token.
   */
  duplicate?: Message | ((token: string) => Message);
  /**
   * Custom error message when value parsing fails.
   * Can be a static message or a function that receives the error message.
   */
  invalidValue?: Message | ((error: Message) => Message);
  /**
   * Custom error message when a Boolean flag receives an unexpected value.
   * Can be a static message or a function that receives the value.
   */
  unexpectedValue?: Message | ((value: string) => Message);
  /**
   * Custom error message when no matching option is found.
   * Can be a static message or a function that receives:
   * - invalidOption: The invalid option name that was provided
   * - suggestions: Array of similar valid option names (can be empty)
   *
   * @since 0.7.0
   */
  noMatch?: Message | ((invalidOption: string, suggestions: readonly string[]) => Message);
}
/**
 * Creates a parser for various styles of command-line options that take an
 * argument value, such as `--option=value`, `-option=value`, `-o value`,
 * or `/option:value`.
 * @template M The execution mode of the parser.
 * @template T The type of value this parser produces.
 * @param args The {@link OptionName}s to parse, followed by
 *             a {@link ValueParser} that defines how to parse the value of
 *             the option.  If no value parser is provided, the option is
 *             treated as a boolean flag.
 * @returns A {@link Parser} that can parse the specified options and their
 *          values.
 */
declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>]): Parser<M, T, ValueParserResult<T> | undefined>;
/**
 * Creates a parser for various styles of command-line options that take an
 * argument value, such as `--option=value`, `-option=value`, `-o value`,
 * or `/option:value`.
 * @template M The execution mode of the parser.
 * @template T The type of value this parser produces.
 * @param args The {@link OptionName}s to parse, followed by
 *             a {@link ValueParser} that defines how to parse the value of
 *             the option, and an optional {@link OptionOptions} object
 *             that allows you to specify a description or other metadata.
 * @returns A {@link Parser} that can parse the specified options and their
 *          values.
 */
declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>, OptionOptions]): Parser<M, T, ValueParserResult<T> | undefined>;
/**
 * Creates a parser for various styles of command-line options that do not
 * take an argument value, such as `--option`, `-o`, or `/option`.
 * @param optionNames The {@link OptionName}s to parse.
 * @return A {@link Parser} that can parse the specified options as Boolean
 *         flags, producing `true` if the option is present.
 */
declare function option(...optionNames: readonly [OptionName, ...readonly OptionName[]]): Parser<"sync", boolean, ValueParserResult<boolean> | undefined>;
/**
 * Creates a parser for various styles of command-line options that take an
 * argument value, such as `--option=value`, `-option=value`, `-o value`,
 * or `/option:value`.
 * @param args The {@link OptionName}s to parse, followed by
 *             an optional {@link OptionOptions} object that allows you to
 *             specify a description or other metadata.
 * @returns A {@link Parser} that can parse the specified options and their
 *          values.
 */
declare function option(...args: readonly [OptionName, ...readonly OptionName[], OptionOptions]): Parser<"sync", boolean, ValueParserResult<boolean> | undefined>;
/**
 * Options for the {@link flag} parser.
 */
interface FlagOptions {
  /**
   * The description of the flag, which can be used for help messages.
   */
  readonly description?: Message;
  /**
   * Controls flag visibility:
   *
   * - `true`: hide from usage, docs, and suggestions
   * - `"usage"`: hide from usage only
   * - `"doc"`: hide from docs only
   * - `"help"`: hide from usage and docs, keep suggestions
   *
   * @since 0.9.0
   */
  readonly hidden?: HiddenVisibility;
  /**
   * Error message customization options.
   * @since 0.5.0
   */
  readonly errors?: FlagErrorOptions;
}
/**
 * Options for customizing error messages in the {@link flag} parser.
 * @since 0.5.0
 */
interface FlagErrorOptions {
  /**
   * Custom error message when the flag is missing (for required flags).
   * Can be a static message or a function that receives the option names.
   */
  missing?: Message | ((optionNames: readonly string[]) => Message);
  /**
   * Custom error message when options are terminated (after --).
   */
  optionsTerminated?: Message;
  /**
   * Custom error message when input is empty but flag is expected.
   */
  endOfInput?: Message;
  /**
   * Custom error message when flag is used multiple times.
   * Can be a static message or a function that receives the token.
   */
  duplicate?: Message | ((token: string) => Message);
  /**
   * Custom error message when no matching flag is found.
   * Can be a static message or a function that receives:
   * - invalidOption: The invalid option name that was provided
   * - suggestions: Array of similar valid option names (can be empty)
   *
   * @since 0.7.0
   */
  noMatch?: Message | ((invalidOption: string, suggestions: readonly string[]) => Message);
}
/**
 * Creates a parser for command-line flags that must be explicitly provided.
 * Unlike {@link option}, this parser fails if the flag is not present, making
 * it suitable for required boolean flags that don't have a meaningful default.
 *
 * The key difference from {@link option} is:
 * - {@link option} without a value parser: Returns `false` when not present
 * - {@link flag}: Fails parsing when not present, only produces `true`
 *
 * This is useful for dependent options where the presence of a flag changes
 * the shape of the result type.
 *
 * @param args The {@link OptionName}s to parse, followed by an optional
 *             {@link FlagOptions} object that allows you to specify
 *             a description or other metadata.
 * @returns A {@link Parser} that produces `true` when the flag is present
 *          and fails when it is not present.
 *
 * @example
 * ```typescript
 * // Basic flag usage
 * const parser = flag("-f", "--force");
 * // Succeeds with true: parse(parser, ["-f"])
 * // Fails: parse(parser, [])
 *
 * // With description
 * const verboseFlag = flag("-v", "--verbose", {
 *   description: "Enable verbose output"
 * });
 * ```
 */
declare function flag(...args: readonly [OptionName, ...readonly OptionName[], FlagOptions] | readonly [OptionName, ...readonly OptionName[]]): Parser<"sync", true, ValueParserResult<true> | undefined>;
/**
 * A non-empty list of option names, or a single option name.
 * @since 1.1.0
 */
type NegatableFlagNameList = OptionName | readonly [OptionName, ...readonly OptionName[]];
/**
 * Option names for the {@link negatableFlag} parser.
 * @since 1.1.0
 */
interface NegatableFlagNames {
  /**
   * Option names that produce `true`.
   */
  readonly positive: NegatableFlagNameList;
  /**
   * Option names that produce `false`.
   */
  readonly negative: NegatableFlagNameList;
}
/**
 * Options for the {@link negatableFlag} parser.
 * @since 1.1.0
 */
interface NegatableFlagOptions {
  /**
   * The description of the flag pair, which can be used for help messages.
   */
  readonly description?: Message;
  /**
   * Controls flag visibility:
   *
   * - `true`: hide from usage, docs, and suggestions
   * - `"usage"`: hide from usage only
   * - `"doc"`: hide from docs only
   * - `"help"`: hide from usage and docs, keep suggestions
   */
  readonly hidden?: HiddenVisibility;
  /**
   * Error message customization options.
   */
  readonly errors?: NegatableFlagErrorOptions;
}
/**
 * Options for customizing error messages in the {@link negatableFlag} parser.
 * @since 1.1.0
 */
interface NegatableFlagErrorOptions {
  /**
   * Custom error message when neither flag is provided.
   * Can be a static message or a function that receives the positive and
   * negative option names.
   */
  readonly missing?: Message | ((positiveNames: readonly string[], negativeNames: readonly string[]) => Message);
  /**
   * Custom error message when options are terminated (after --).
   */
  readonly optionsTerminated?: Message;
  /**
   * Custom error message when input is empty but a flag is expected.
   */
  readonly endOfInput?: Message;
  /**
   * Custom error message when the same polarity is used multiple times.
   */
  readonly duplicate?: Message | ((token: string) => Message);
  /**
   * Custom error message when both positive and negative flags are used.
   */
  readonly conflict?: Message | ((previousToken: string, token: string) => Message);
  /**
   * Custom error message when a flag receives an unexpected value.
   */
  readonly unexpectedValue?: Message | ((optionName: string, value: string) => Message);
  /**
   * Custom error message when no matching flag is found.
   */
  readonly noMatch?: Message | ((invalidOption: string, suggestions: readonly string[]) => Message);
}
/**
 * State stored by the {@link negatableFlag} parser.
 * @since 1.1.0
 */
interface NegatableFlagState {
  readonly value: boolean;
  readonly token: string;
}
/**
 * Creates a parser for a pair of command-line flags that explicitly enable or
 * disable a Boolean value.
 *
 * The positive names produce `true`; the negative names produce `false`.
 * Unlike {@link option}, this parser fails when neither side is present,
 * matching {@link flag} semantics. Wrap it in {@link optional} for a
 * tri-state override or {@link withDefault} for a concrete fallback.
 *
 * @param names The positive and negative option names to parse.
 * @param options Optional metadata and error customization.
 * @returns A {@link Parser} that produces `true` for positive names and
 *          `false` for negative names.
 * @throws {TypeError} If any option name is invalid, duplicated within one
 *         side, or shared by the positive and negative sides.
 * @since 1.1.0
 */
declare function negatableFlag(names: NegatableFlagNames, options?: NegatableFlagOptions): Parser<"sync", boolean, NegatableFlagState | undefined>;
/**
 * Options for the {@link argument} parser.
 */
interface ArgumentOptions {
  /**
   * The description of the argument, which can be used for help messages.
   */
  readonly description?: Message;
  /**
   * Controls argument visibility:
   *
   * - `true`: hide from usage, docs, and suggestions
   * - `"usage"`: hide from usage only
   * - `"doc"`: hide from docs only
   * - `"help"`: hide from usage and docs, keep suggestions
   *
   * @since 0.9.0
   */
  readonly hidden?: HiddenVisibility;
  /**
   * Error message customization options.
   * @since 0.5.0
   */
  readonly errors?: ArgumentErrorOptions;
}
/**
 * Options for customizing error messages in the {@link argument} parser.
 * @since 0.5.0
 */
interface ArgumentErrorOptions {
  /**
   * Custom error message when input is empty but argument is expected.
   */
  endOfInput?: Message;
  /**
   * Custom error message when value parsing fails.
   * Can be a static message or a function that receives the error message.
   */
  invalidValue?: Message | ((error: Message) => Message);
  /**
   * Custom error message when argument is used multiple times.
   * Can be a static message or a function that receives the metavar.
   */
  multiple?: Message | ((metavar: string) => Message);
}
/**
 * Creates a parser that expects a single argument value.
 * This parser is typically used for positional arguments
 * that are not options or flags.
 * @template M The execution mode of the parser.
 * @template T The type of the value produced by the parser.
 * @param valueParser The {@link ValueParser} that defines how to parse
 *                    the argument value.
 * @param options Optional configuration for the argument parser,
 *                allowing you to specify a description or other metadata.
 * @returns A {@link Parser} that expects a single argument value and produces
 *          the parsed value of type {@link T}.
 */
declare function argument<M extends Mode, T>(valueParser: ValueParser<M, T>, options?: ArgumentOptions): Parser<M, T, ValueParserResult<T> | undefined>;
/**
 * Options for the {@link command} parser.
 * @since 0.5.0
 */
interface CommandOptions {
  /**
   * A brief description of the command, shown in command lists.
   * If provided along with {@link description}, this will be used in
   * command listings (e.g., `myapp help`), while {@link description}
   * will be used for detailed help (e.g., `myapp help subcommand` or
   * `myapp subcommand --help`).
   * @since 0.6.0
   */
  readonly brief?: Message;
  /**
   * A description of the command, used for documentation.
   */
  readonly description?: Message;
  /**
   * A footer message that appears at the bottom of the command's help text.
   * Useful for showing examples, notes, or additional information.
   * @since 0.6.0
   */
  readonly footer?: Message;
  /**
   * Usage line override for this command's own help page.
   *
   * This option customizes the usage tail shown when rendering help for this
   * command itself (e.g., `myapp config --help`). It does not change parsing
   * behavior or shell completion.
   *
   * - `Usage`: Replaces the default usage tail.
   * - `(defaultUsageLine) => Usage`: Computes the usage tail from the default.
   *
   * @since 1.0.0
   */
  readonly usageLine?: Usage | ((defaultUsageLine: Usage) => Usage);
  /**
   * Controls command visibility:
   *
   * - `true`: hide from usage, docs, and suggestions
   * - `"usage"`: hide from usage only
   * - `"doc"`: hide from docs only
   * - `"help"`: hide from usage and docs, keep suggestions
   *
   * @since 0.9.0
   */
  readonly hidden?: HiddenVisibility;
  /**
   * Additional names that invoke this command.
   *
   * Aliases are functional at runtime and are suggested by shell completion,
   * but are hidden from usage and documentation output.  The `name` parameter
   * passed to {@link command} remains the canonical display name.
   *
   * @since 1.1.0
   */
  readonly aliases?: readonly [string, ...string[]];
  /**
   * Error messages customization.
   * @since 0.5.0
   */
  readonly errors?: CommandErrorOptions;
}
/**
 * Options for customizing error messages in the {@link command} parser.
 * @since 0.5.0
 */
interface CommandErrorOptions {
  /**
   * Error message when command is expected but not found.
   * Since version 0.7.0, the function signature now includes suggestions:
   * - expected: The expected command name
   * - actual: The actual input (or null if no input)
   * - suggestions: Array of similar valid command names (can be empty)
   */
  readonly notMatched?: Message | ((expected: string, actual: string | null, suggestions?: readonly string[]) => Message);
  /**
   * Error message when command was not matched during completion.
   */
  readonly notFound?: Message;
  /**
   * Error message for invalid command state.
   */
  readonly invalidState?: Message;
}
/**
 * The state type for the {@link command} parser.
 * @template TState The type of the inner parser's state.
 */
type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState];
/**
 * Creates a parser that matches a specific subcommand name and then applies
 * an inner parser to the remaining arguments.
 * This is useful for building CLI tools with subcommands like git, npm, etc.
 * @template M The execution mode of the parser.
 * @template T The type of the value returned by the inner parser.
 * @template TState The type of the state used by the inner parser.
 * @param name The subcommand name to match (e.g., `"show"`, `"edit"`).
 * @param parser The {@link Parser} to apply after the command is matched.
 * @param options Optional configuration for the command parser, such as
 *                a description for documentation.
 * @returns A {@link Parser} that matches the command name and delegates
 *          to the inner parser for the remaining arguments.
 * @throws {TypeError} If `name` is empty, whitespace-only, contains
 *         embedded whitespace, or contains control characters.
 */
declare function command<M extends Mode, T, TState>(name: string, parser: Parser<M, T, TState>, options?: CommandOptions): Parser<M, T, CommandState<TState>>;
/**
 * Format options for how {@link passThrough} captures options.
 * @since 0.8.0
 */
type PassThroughFormat = "equalsOnly" | "nextToken" | "greedy";
/**
 * Options for the {@link passThrough} parser.
 * @since 0.8.0
 */
interface PassThroughOptions {
  /**
   * How to capture option values:
   *
   * - `"equalsOnly"`: Only capture `--opt=val` format (default, safest).
   *   Values with spaces (`--opt val`) are not captured.
   *
   * - `"nextToken"`: Capture `--opt` and its value as separate tokens
   *   (`--opt val`). The next token is captured if it doesn't start with `-`.
   *
   * - `"greedy"`: Capture *all* remaining tokens from first unrecognized token.
   *   This is useful for wrapper/proxy tools that pass everything through.
   *
   * @default `"equalsOnly"`
   */
  readonly format?: PassThroughFormat;
  /**
   * A description of what pass-through options are used for.
   */
  readonly description?: Message;
  /**
   * Controls pass-through visibility:
   *
   * - `true`: hide from usage, docs, and suggestions
   * - `"usage"`: hide from usage only
   * - `"doc"`: hide from docs only
   * - `"help"`: hide from usage and docs, keep suggestions
   *
   * @since 0.9.0
   */
  readonly hidden?: HiddenVisibility;
}
/**
 * Creates a parser that collects unrecognized options and passes them through.
 * This is useful for building wrapper CLI tools that need to forward unknown
 * options to an underlying tool.
 *
 * **Important**: This parser intentionally weakens Optique's strict parsing
 * philosophy where "all input must be recognized." The benefit is enabling
 * legitimate wrapper/proxy tool patterns, but the trade-off is that typos
 * in pass-through options won't be caught.
 *
 * @param options Configuration for how to capture options.
 * @returns A {@link Parser} that captures unrecognized options as an array
 *          of strings.
 *
 * @example
 * ```typescript
 * // Default format: only captures --opt=val
 * const parser = object({
 *   debug: option("--debug"),
 *   extra: passThrough(),
 * });
 *
 * // mycli --debug --foo=bar --baz=qux
 * // → { debug: true, extra: ["--foo=bar", "--baz=qux"] }
 *
 * // nextToken format: captures --opt val pairs
 * const parser = object({
 *   debug: option("--debug"),
 *   extra: passThrough({ format: "nextToken" }),
 * });
 *
 * // mycli --debug --foo bar
 * // → { debug: true, extra: ["--foo", "bar"] }
 *
 * // greedy format: captures all remaining tokens
 * const parser = command("exec", object({
 *   container: argument(string()),
 *   args: passThrough({ format: "greedy" }),
 * }));
 *
 * // myproxy exec mycontainer --verbose -it bash
 * // → { container: "mycontainer", args: ["--verbose", "-it", "bash"] }
 * ```
 *
 * @since 0.8.0
 */
declare function passThrough(options?: PassThroughOptions): Parser<"sync", readonly string[], readonly string[]>;
//#endregion
export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough };