@optique/core 0.5.0-dev.79 → 0.5.0-dev.82

package/dist/primitives.d.cts

@@ -0,0 +1,274 @@
+import { Message } from "./message.cjs";
+import { OptionName } from "./usage.cjs";
+import { ValueParser, ValueParserResult } from "./valueparser.cjs";
+import { Parser } from "./parser.cjs";
+
+//#region src/primitives.d.ts
+
+/**
+ * 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;
+  /**
+   * 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);
+}
+/**
+ * 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 flag} parser.
+ */
+interface FlagOptions {
+  /**
+   * The description of the flag, which can be used for help messages.
+   */
+  readonly description?: Message;
+  /**
+   * 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);
+}
+/**
+ * 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 [...readonly OptionName[], FlagOptions] | readonly OptionName[]): Parser<true, ValueParserResult<true> | undefined>;
+/**
+ * Options for the {@link argument} parser.
+ */
+interface ArgumentOptions {
+  /**
+   * The description of the argument, which can be used for help messages.
+   */
+  readonly description?: Message;
+  /**
+   * 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 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>;
+/**
+ * Options for the {@link command} parser.
+ * @since 0.5.0
+ */
+interface CommandOptions {
+  /**
+   * A description of the command, used for documentation.
+   */
+  readonly description?: Message;
+  /**
+   * 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.
+   */
+  readonly notMatched?: Message | ((expected: string, actual: string | null) => 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 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>>;
+//#endregion
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option };

package/dist/primitives.d.ts

@@ -0,0 +1,274 @@
+import { Message } from "./message.js";
+import { OptionName } from "./usage.js";
+import { ValueParser, ValueParserResult } from "./valueparser.js";
+import { Parser } from "./parser.js";
+
+//#region src/primitives.d.ts
+
+/**
+ * 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;
+  /**
+   * 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);
+}
+/**
+ * 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 flag} parser.
+ */
+interface FlagOptions {
+  /**
+   * The description of the flag, which can be used for help messages.
+   */
+  readonly description?: Message;
+  /**
+   * 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);
+}
+/**
+ * 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 [...readonly OptionName[], FlagOptions] | readonly OptionName[]): Parser<true, ValueParserResult<true> | undefined>;
+/**
+ * Options for the {@link argument} parser.
+ */
+interface ArgumentOptions {
+  /**
+   * The description of the argument, which can be used for help messages.
+   */
+  readonly description?: Message;
+  /**
+   * 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 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>;
+/**
+ * Options for the {@link command} parser.
+ * @since 0.5.0
+ */
+interface CommandOptions {
+  /**
+   * A description of the command, used for documentation.
+   */
+  readonly description?: Message;
+  /**
+   * 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.
+   */
+  readonly notMatched?: Message | ((expected: string, actual: string | null) => 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 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>>;
+//#endregion
+export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, OptionErrorOptions, OptionOptions, argument, command, constant, flag, option };