@optique/core 0.1.0-dev.1

package/dist/parser.d.cts

@@ -0,0 +1,580 @@
+import { Message } from "./message.cjs";
+import { OptionName, Usage } from "./usage.cjs";
+import { DocFragments, DocPage } from "./doc.cjs";
+import { ValueParser, ValueParserResult } from "./valueparser.cjs";
+
+//#region src/parser.d.ts
+
+/**
+ * Parser interface for command-line argument parsing.
+ * @template TValue The type of the value returned by the parser.
+ * @template TState The type of the state used during parsing.
+ */
+interface Parser<TValue, TState> {
+  /**
+   * A type tag for the result value of this parser, used for type inference.
+   * Usually this is an empty array at runtime, but it does not matter
+   * what it contains.
+   * @internal
+   */
+  readonly $valueType: readonly TValue[];
+  /**
+   * A type tag for the state of this parser, used for type inference.
+   * Usually this is an empty array at runtime, but it does not matter
+   * what it contains.
+   * @internal
+   */
+  readonly $stateType: readonly TState[];
+  /**
+   * The priority of this parser, which determines the order in which
+   * parsers are applied when multiple parsers are available.  The greater
+   * the number, the higher the priority.
+   */
+  readonly priority: number;
+  /**
+   * The usage information for this parser, which describes how
+   * to use it in command-line interfaces.
+   */
+  readonly usage: Usage;
+  /**
+   * The initial state for this parser.  This is used to initialize the
+   * state when parsing starts.
+   */
+  readonly initialState: TState;
+  /**
+   * Parses the input context and returns a result indicating
+   * whether the parsing was successful or not.
+   * @param context The context of the parser, which includes the input buffer
+   *                and the current state.
+   * @returns A result object indicating success or failure.
+   */
+  parse(context: ParserContext<TState>): ParserResult<TState>;
+  /**
+   * Transforms a {@link TState} into a {@link TValue}, if applicable.
+   * If the transformation is not applicable, it should return
+   * a `ValueParserResult` with `success: false` and an appropriate error
+   * message.
+   * @param state The current state of the parser, which may contain accumulated
+   *              data or context needed to produce the final value.
+   * @returns A result object indicating success or failure of
+   *          the transformation.  If successful, it should contain
+   *          the parsed value of type {@link TValue}.  If not applicable,
+   *          it should return an error message.
+   */
+  complete(state: TState): ValueParserResult<TValue>;
+  /**
+   * Generates a documentation fragment for this parser, which can be used
+   * to describe the parser's usage, description, and default value.
+   * @param state The current state of the parser, which may contain
+   *              accumulated data or context needed to produce
+   *              the documentation.
+   * @param defaultValue An optional default value that can be used
+   *                     to provide a default value in the documentation.
+   * @returns {@link DocFragments} object containing documentation
+   *          fragments for this parser.
+   */
+  getDocFragments(state: TState, defaultValue?: TValue): DocFragments;
+}
+/**
+ * The context of the parser, which includes the input buffer and the state.
+ * @template TState The type of the state used during parsing.
+ */
+interface ParserContext<TState> {
+  /**
+   * The array of input strings that the parser is currently processing.
+   */
+  readonly buffer: readonly string[];
+  /**
+   * The current state of the parser, which is used to track
+   * the progress of parsing and any accumulated data.
+   */
+  readonly state: TState;
+  /**
+   * A flag indicating whether no more options should be parsed and instead
+   * the remaining input should be treated as positional arguments.
+   * This is typically set when the parser encounters a `--` in the input,
+   * which is a common convention in command-line interfaces to indicate
+   * that no further options should be processed.
+   */
+  readonly optionsTerminated: boolean;
+}
+/**
+ * A discriminated union type representing the result of a parser operation.
+ * It can either indicate a successful parse with the next state and context,
+ * or a failure with an error message.
+ * @template TState The type of the state after parsing.  It should match with
+ *           the `TState` type of the {@link Parser} interface.
+ */
+type ParserResult<TState> = {
+  /**
+   * Indicates that the parsing operation was successful.
+   */
+  readonly success: true;
+  /**
+   * The next context after parsing, which includes the updated input buffer.
+   */
+  readonly next: ParserContext<TState>;
+  /**
+   * The input elements consumed by the parser during this operation.
+   */
+  readonly consumed: readonly string[];
+} | {
+  /**
+   * Indicates that the parsing operation failed.
+   */
+  readonly success: false;
+  /**
+   * The number of the consumed input elements.
+   */
+  readonly consumed: number;
+  /**
+   * The error message describing why the parsing failed.
+   */
+  readonly error: Message;
+};
+/**
+ * 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<T, T>;
+/**
+ * Options for the {@link option} parser.
+ */
+interface OptionOptions {
+  /**
+   * The description of the option, which can be used for help messages.
+   */
+  readonly description?: Message;
+}
+/**
+ * Creates a parser for various styles of command-line options that take an
+ * argument value, such as `--option=value`, `-o value`, or `/option:value`.
+ * @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<T>(...args: readonly [...readonly OptionName[], ValueParser<T>]): Parser<T, ValueParserResult<T> | undefined>;
+/**
+ * Creates a parser for various styles of command-line options that take an
+ * argument value, such as `--option=value`, `-o value`, or `/option:value`.
+ * @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<T>(...args: readonly [...readonly OptionName[], ValueParser<T>, OptionOptions]): Parser<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[]): Parser<boolean, ValueParserResult<boolean> | undefined>;
+/**
+ * Creates a parser for various styles of command-line options that take an
+ * argument value, such as `--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 [...readonly OptionName[], OptionOptions]): Parser<boolean, ValueParserResult<boolean> | undefined>;
+/**
+ * Options for the {@link argument} parser.
+ */
+interface ArgumentOptions {
+  /**
+   * The description of the argument, which can be used for help messages.
+   */
+  readonly description?: 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 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<T>(valueParser: ValueParser<T>, options?: ArgumentOptions): Parser<T, ValueParserResult<T> | undefined>;
+/**
+ * Creates a parser that makes another parser optional, allowing it to succeed
+ * without consuming input if the wrapped parser fails to match.
+ * If the wrapped parser succeeds, this returns its value.
+ * If the wrapped parser fails, this returns `undefined` without consuming input.
+ * @template TValue The type of the value returned by the wrapped parser.
+ * @template TState The type of the state used by the wrapped parser.
+ * @param parser The {@link Parser} to make optional.
+ * @returns A {@link Parser} that produces either the result of the wrapped parser
+ *          or `undefined` if the wrapped parser fails to match.
+ */
+declare function optional<TValue, TState>(parser: Parser<TValue, TState>): Parser<TValue | undefined, [TState] | undefined>;
+/**
+ * Creates a parser that makes another parser use a default value when it fails
+ * to match or consume input. This is similar to {@link optional}, but instead
+ * of returning `undefined` when the wrapped parser doesn't match, it returns
+ * a specified default value.
+ * @template TValue The type of the value returned by the wrapped parser.
+ * @template TState The type of the state used by the wrapped parser.
+ * @param parser The {@link Parser} to wrap with default behavior.
+ * @param defaultValue The default value to return when the wrapped parser
+ *                     doesn't match or consume input. Can be a value of type
+ *                     {@link TValue} or a function that returns such a value.
+ * @returns A {@link Parser} that produces either the result of the wrapped parser
+ *          or the default value if the wrapped parser fails to match.
+ */
+declare function withDefault<TValue, TState>(parser: Parser<TValue, TState>, defaultValue: TValue | (() => TValue)): Parser<TValue, [TState] | undefined>;
+/**
+ * Options for the {@link multiple} parser.
+ */
+interface MultipleOptions {
+  /**
+   * The minimum number of occurrences required for the parser to succeed.
+   * If the number of occurrences is less than this value,
+   * the parser will fail with an error.
+   * @default `0`
+   */
+  readonly min?: number;
+  /**
+   * The maximum number of occurrences allowed for the parser.
+   * If the number of occurrences exceeds this value,
+   * the parser will fail with an error.
+   * @default `Infinity`
+   */
+  readonly max?: number;
+}
+/**
+ * Creates a parser that allows multiple occurrences of a given parser.
+ * This parser can be used to parse multiple values of the same type,
+ * such as multiple command-line arguments or options.
+ * @template TValue The type of the value that the parser produces.
+ * @template TState The type of the state used by the parser.
+ * @param parser The {@link Parser} to apply multiple times.
+ * @param options Optional configuration for the parser,
+ *                allowing you to specify the minimum and maximum number of
+ *                occurrences allowed.
+ * @returns A {@link Parser} that produces an array of values
+ *          of type {@link TValue} and an array of states
+ *          of type {@link TState}.
+ */
+declare function multiple<TValue, TState>(parser: Parser<TValue, TState>, options?: MultipleOptions): Parser<readonly TValue[], readonly TState[]>;
+/**
+ * Creates a parser that combines multiple parsers into a single object parser.
+ * Each parser in the object is applied to parse different parts of the input,
+ * and the results are combined into an object with the same structure.
+ * @template T A record type where each value is a {@link Parser}.
+ * @param parsers An object containing named parsers that will be combined
+ *                into a single object parser.
+ * @returns A {@link Parser} that produces an object with the same keys as
+ *          the input, where each value is the result of the corresponding
+ *          parser.
+ */
+declare function object<T extends {
+  readonly [key: string | symbol]: Parser<unknown, unknown>;
+}>(parsers: T): Parser<{ readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
+/**
+ * Creates a labeled parser that combines multiple parsers into a single
+ * object parser with an associated label for documentation or error reporting.
+ * @template T A record type where each value is a {@link Parser}.
+ * @param label A descriptive label for this parser group, used for
+ *              documentation and error messages.
+ * @param parsers An object containing named parsers that will be combined
+ *                into a single object parser.
+ * @returns A {@link Parser} that produces an object with the same keys as
+ *          the input, where each value is the result of the corresponding
+ *          parser.
+ */
+declare function object<T extends {
+  readonly [key: string | symbol]: Parser<unknown, unknown>;
+}>(label: string, parsers: T): Parser<{ readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
+/**
+ * Creates a parser that combines multiple parsers into a sequential tuple parser.
+ * The parsers are applied in the order they appear in the array, and all must
+ * succeed for the tuple parser to succeed.
+ * @template T A readonly array type where each element is a {@link Parser}.
+ * @param parsers An array of parsers that will be applied sequentially
+ *                to create a tuple of their results.
+ * @returns A {@link Parser} that produces a readonly tuple with the same length
+ *          as the input array, where each element is the result of the
+ *          corresponding parser.
+ */
+declare function tuple<T extends readonly Parser<unknown, unknown>[]>(parsers: T): Parser<{ readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
+/**
+ * Creates a labeled parser that combines multiple parsers into a sequential
+ * tuple parser with an associated label for documentation or error reporting.
+ * @template T A readonly array type where each element is a {@link Parser}.
+ * @param label A descriptive label for this parser group, used for
+ *              documentation and error messages.
+ * @param parsers An array of parsers that will be applied sequentially
+ *                to create a tuple of their results.
+ * @returns A {@link Parser} that produces a readonly tuple with the same length
+ *          as the input array, where each element is the result of the
+ *          corresponding parser.
+ */
+declare function tuple<T extends readonly Parser<unknown, unknown>[]>(label: string, parsers: T): Parser<{ readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
+/**
+ * Creates a parser that combines two mutually exclusive parsers into one.
+ * The resulting parser will try each of the provided parsers in order,
+ * and return the result of the first successful parser.
+ * @template TA The type of the value returned by the first parser.
+ * @template TB The type of the value returned by the second parser.
+ * @template TStateA The type of the state used by the first parser.
+ * @template TStateB The type of the state used by the second parser.
+ * @param a The first {@link Parser} to try.
+ * @param b The second {@link Parser} to try.
+ * @returns A {@link Parser} that tries to parse using the provided parsers
+ *          in order, returning the result of the first successful parser.
+ */
+declare function or<TA, TB, TStateA, TStateB>(a: Parser<TA, TStateA>, b: Parser<TB, TStateB>): Parser<TA | TB, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>]>;
+/**
+ * Creates a parser that combines three mutually exclusive parsers into one.
+ * The resulting parser will try each of the provided parsers in order,
+ * and return the result of the first successful parser.
+ * @template TA The type of the value returned by the first parser.
+ * @template TB The type of the value returned by the second parser.
+ * @template TC The type of the value returned by the third parser.
+ * @template TStateA The type of the state used by the first parser.
+ * @template TStateB The type of the state used by the second parser.
+ * @template TStateC The type of the state used by the third parser.
+ * @param a The first {@link Parser} to try.
+ * @param b The second {@link Parser} to try.
+ * @param c The third {@link Parser} to try.
+ * @return A {@link Parser} that tries to parse using the provided parsers
+ *         in order, returning the result of the first successful parser.
+ */
+declare function or<TA, TB, TC, TStateA, TStateB, TStateC>(a: Parser<TA, TStateA>, b: Parser<TB, TStateB>, c: Parser<TC, TStateC>): Parser<TA | TB | TC, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>]>;
+/**
+ * Creates a parser that combines four mutually exclusive parsers into one.
+ * The resulting parser will try each of the provided parsers in order,
+ * and return the result of the first successful parser.
+ * @template TA The type of the value returned by the first parser.
+ * @template TB The type of the value returned by the second parser.
+ * @template TC The type of the value returned by the third parser.
+ * @template TD The type of the value returned by the fourth parser.
+ * @template TStateA The type of the state used by the first parser.
+ * @template TStateB The type of the state used by the second parser.
+ * @template TStateC The type of the state used by the third parser.
+ * @template TStateD The type of the state used by the fourth parser.
+ * @param a The first {@link Parser} to try.
+ * @param b The second {@link Parser} to try.
+ * @param c The third {@link Parser} to try.
+ * @param d The fourth {@link Parser} to try.
+ * @return A {@link Parser} that tries to parse using the provided parsers
+ *         in order, returning the result of the first successful parser.
+ */
+declare function or<TA, TB, TC, TD, TStateA, TStateB, TStateC, TStateD>(a: Parser<TA, TStateA>, b: Parser<TB, TStateB>, c: Parser<TC, TStateC>, d: Parser<TD, TStateD>): Parser<TA | TB | TC | TD, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>] | [3, ParserResult<TStateD>]>;
+/**
+ * Creates a parser that combines five mutually exclusive parsers into one.
+ * The resulting parser will try each of the provided parsers in order,
+ * and return the result of the first successful parser.
+ * @template TA The type of the value returned by the first parser.
+ * @template TB The type of the value returned by the second parser.
+ * @template TC The type of the value returned by the third parser.
+ * @template TD The type of the value returned by the fourth parser.
+ * @template TE The type of the value returned by the fifth parser.
+ * @template TStateA The type of the state used by the first parser.
+ * @template TStateB The type of the state used by the second parser.
+ * @template TStateC The type of the state used by the third parser.
+ * @template TStateD The type of the state used by the fourth parser.
+ * @template TStateE The type of the state used by the fifth parser.
+ * @param a The first {@link Parser} to try.
+ * @param b The second {@link Parser} to try.
+ * @param c The third {@link Parser} to try.
+ * @param d The fourth {@link Parser} to try.
+ * @param e The fifth {@link Parser} to try.
+ * @return A {@link Parser} that tries to parse using the provided parsers
+ *         in order, returning the result of the first successful parser.
+ */
+declare function or<TA, TB, TC, TD, TE, TStateA, TStateB, TStateC, TStateD, TStateE>(a: Parser<TA, TStateA>, b: Parser<TB, TStateB>, c: Parser<TC, TStateC>, d: Parser<TD, TStateD>, e: Parser<TE, TStateE>): Parser<TA | TB | TC | TD | TE, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>] | [3, ParserResult<TStateD>] | [4, ParserResult<TStateE>]>;
+/**
+ * Merges multiple {@link object} parsers into a single {@link object} parser.
+ * It is useful for combining multiple {@link object} parsers so that
+ * the unified parser produces a single object containing all the values
+ * from the individual parsers while separating the fields into multiple
+ * groups.
+ * @template TA The type of the first parser.
+ * @template TB The type of the second parser.
+ * @param a The first {@link object} parser to merge.
+ * @param b The second {@link object} parser to merge.
+ * @return A new {@link object} parser that combines the values and states
+ *         of the two parsers into a single object.
+ */
+declare function merge<TA extends Parser<Record<string | symbol, unknown>, Record<string | symbol, unknown>>, TB extends Parser<Record<string | symbol, unknown>, Record<string | symbol, unknown>>>(a: TA, b: TB): Parser<{ readonly [K in keyof TA["$valueType"][number]]: TA["$valueType"][number][K] extends (infer U) ? U : never } & { readonly [K in keyof TB["$valueType"][number]]: TB["$valueType"][number][K] extends (infer U2) ? U2 : never }, { readonly [K in keyof TA]: unknown } & { readonly [K in keyof TB]: unknown }>;
+/**
+ * Merges multiple {@link object} parsers into a single {@link object} parser.
+ * It is useful for combining multiple {@link object} parsers so that
+ * the unified parser produces a single object containing all the values
+ * from the individual parsers while separating the fields into multiple
+ * groups.
+ * @template TA The type of the first parser.
+ * @template TB The type of the second parser.
+ * @template TC The type of the third parser.
+ * @param a The first {@link object} parser to merge.
+ * @param b The second {@link object} parser to merge.
+ * @param c The third {@link object} parser to merge.
+ * @return A new {@link object} parser that combines the values and states
+ *         of the two parsers into a single object.
+ */
+declare function merge<TA extends Parser<Record<string | symbol, unknown>, Record<string | symbol, unknown>>, TB extends Parser<Record<string | symbol, unknown>, Record<string | symbol, unknown>>, TC extends Parser<Record<string | symbol, unknown>, Record<string | symbol, unknown>>>(a: TA, b: TB, c: TC): Parser<{ readonly [K in keyof TA["$valueType"][number]]: TA["$valueType"][number][K] extends (infer U) ? U : never } & { readonly [K in keyof TB["$valueType"][number]]: TB["$valueType"][number][K] extends (infer U2) ? U2 : never } & { readonly [K in keyof TC["$valueType"][number]]: TC["$valueType"][number][K] extends (infer U3) ? U3 : never }, { readonly [K in keyof TA]: unknown } & { readonly [K in keyof TB]: unknown } & { readonly [K in keyof TC]: unknown }>;
+/**
+ * Merges multiple {@link object} parsers into a single {@link object} parser.
+ * It is useful for combining multiple {@link object} parsers so that
+ * the unified parser produces a single object containing all the values
+ * from the individual parsers while separating the fields into multiple
+ * groups.
+ * @template TA The type of the first parser.
+ * @template TB The type of the second parser.
+ * @template TC The type of the third parser.
+ * @template TD The type of the fourth parser.
+ * @param a The first {@link object} parser to merge.
+ * @param b The second {@link object} parser to merge.
+ * @param c The third {@link object} parser to merge.
+ * @param d The fourth {@link object} parser to merge.
+ * @return A new {@link object} parser that combines the values and states
+ *         of the two parsers into a single object.
+ */
+declare function merge<TA extends Parser<Record<string | symbol, unknown>, Record<string | symbol, unknown>>, TB extends Parser<Record<string | symbol, unknown>, Record<string | symbol, unknown>>, TC extends Parser<Record<string | symbol, unknown>, Record<string | symbol, unknown>>, TD extends Parser<Record<string | symbol, unknown>, Record<string | symbol, unknown>>>(a: TA, b: TB, c: TC, d: TD): Parser<{ readonly [K in keyof TA["$valueType"][number]]: TA["$valueType"][number][K] extends (infer U) ? U : never } & { readonly [K in keyof TB["$valueType"][number]]: TB["$valueType"][number][K] extends (infer U2) ? U2 : never } & { readonly [K in keyof TC["$valueType"][number]]: TC["$valueType"][number][K] extends (infer U3) ? U3 : never } & { readonly [K in keyof TD["$valueType"][number]]: TD["$valueType"][number][K] extends (infer U4) ? U4 : never }, { readonly [K in keyof TA]: unknown } & { readonly [K in keyof TB]: unknown } & { readonly [K in keyof TC]: unknown } & { readonly [K in keyof TD]: unknown }>;
+/**
+ * Merges multiple {@link object} parsers into a single {@link object} parser.
+ * It is useful for combining multiple {@link object} parsers so that
+ * the unified parser produces a single object containing all the values
+ * from the individual parsers while separating the fields into multiple
+ * groups.
+ * @template TA The type of the first parser.
+ * @template TB The type of the second parser.
+ * @template TC The type of the third parser.
+ * @template TD The type of the fourth parser.
+ * @template TE The type of the fifth parser.
+ * @param a The first {@link object} parser to merge.
+ * @param b The second {@link object} parser to merge.
+ * @param c The third {@link object} parser to merge.
+ * @param d The fourth {@link object} parser to merge.
+ * @param e The fifth {@link object} parser to merge.
+ * @return A new {@link object} parser that combines the values and states
+ *         of the two parsers into a single object.
+ */
+declare function merge<TA extends Parser<Record<string | symbol, unknown>, Record<string | symbol, unknown>>, TB extends Parser<Record<string | symbol, unknown>, Record<string | symbol, unknown>>, TC extends Parser<Record<string | symbol, unknown>, Record<string | symbol, unknown>>, TD extends Parser<Record<string | symbol, unknown>, Record<string | symbol, unknown>>, TE extends Parser<Record<string | symbol, unknown>, Record<string | symbol, unknown>>>(a: TA, b: TB, c: TC, d: TD, e: TE): Parser<{ readonly [K in keyof TA["$valueType"][number]]: TA["$valueType"][number][K] extends (infer U) ? U : never } & { readonly [K in keyof TB["$valueType"][number]]: TB["$valueType"][number][K] extends (infer U2) ? U2 : never } & { readonly [K in keyof TC["$valueType"][number]]: TC["$valueType"][number][K] extends (infer U3) ? U3 : never } & { readonly [K in keyof TD["$valueType"][number]]: TD["$valueType"][number][K] extends (infer U4) ? U4 : never } & { readonly [K in keyof TE["$valueType"][number]]: TE["$valueType"][number][K] extends (infer U5) ? U5 : never }, { readonly [K in keyof TA]: unknown } & { readonly [K in keyof TB]: unknown } & { readonly [K in keyof TC]: unknown } & { readonly [K in keyof TD]: unknown } & { readonly [K in keyof TE]: unknown }>;
+/**
+ * Options for the {@link command} parser.
+ */
+interface CommandOptions {
+  /**
+   * A description of the command, used for documentation.
+   */
+  readonly description?: 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 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.
+ */
+declare function command<T, TState>(name: string, parser: Parser<T, TState>, options?: CommandOptions): Parser<T, CommandState<TState>>;
+/**
+ * Infers the result value type of a {@link Parser}.
+ * @template T The {@link Parser} to infer the result value type from.
+ */
+type InferValue<T extends Parser<unknown, unknown>> = T["$valueType"][number];
+/**
+ * The result type of a whole parser operation, which can either be a successful
+ * result with a value of type `T`, or a failure with an error message.
+ * @template T The type of the value produced by the parser.
+ */
+type Result<T> = {
+  /**
+   * Indicates that the parsing operation was successful.
+   */
+  success: true;
+  /**
+   * The successfully parsed value of type {@link T}.
+   * This is the final result of the parsing operation after all parsers
+   * have been applied and completed.
+   */
+  value: T;
+} | {
+  /**
+   * Indicates that the parsing operation failed.
+   */
+  success: false;
+  /**
+   * The error message describing why the parsing failed.
+   */
+  error: Message;
+};
+/**
+ * Parses an array of command-line arguments using the provided combined parser.
+ * This function processes the input arguments, applying the parser to each
+ * argument until all arguments are consumed or an error occurs.
+ * @template T The type of the value produced by the parser.
+ * @param parser The combined {@link Parser} to use for parsing the input
+ *               arguments.
+ * @param args The array of command-line arguments to parse.  Usually this is
+ *             `process.argv.slice(2)` in Node.js or `Deno.args` in Deno.
+ * @returns A {@link Result} object indicating whether the parsing was
+ *          successful or not.  If successful, it contains the parsed value of
+ *          type `T`.  If not, it contains an error message describing the
+ *          failure.
+ */
+declare function parse<T>(parser: Parser<T, unknown>, args: readonly string[]): Result<T>;
+/**
+ * Generates a documentation page for a parser based on its current state after
+ * attempting to parse the provided arguments. This function is useful for
+ * creating help documentation that reflects the current parsing context.
+ *
+ * The function works by:
+ * 1. Attempting to parse the provided arguments to determine the current state
+ * 2. Generating documentation fragments from the parser's current state
+ * 3. Organizing fragments into entries and sections
+ * 4. Resolving command usage terms based on parsed arguments
+ *
+ * @param parser The parser to generate documentation for
+ * @param args Optional array of command-line arguments that have been parsed
+ *             so far. Defaults to an empty array. This is used to determine
+ *             the current parsing context and generate contextual documentation.
+ * @returns A {@link DocPage} containing usage information, sections, and
+ *          optional description, or `undefined` if no documentation can be
+ *          generated.
+ *
+ * @example
+ * ```typescript
+ * const parser = object({
+ *   verbose: option("-v", "--verbose"),
+ *   port: option("-p", "--port", integer())
+ * });
+ *
+ * // Get documentation for the root parser
+ * const rootDoc = getDocPage(parser);
+ *
+ * // Get documentation after parsing some arguments
+ * const contextDoc = getDocPage(parser, ["-v"]);
+ * ```
+ */
+declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
+//#endregion
+export { ArgumentOptions, CommandOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, constant, getDocPage, merge, multiple, object, option, optional, or, parse, tuple, withDefault };