@optique/core 1.1.0-dev.2087 → 1.1.0-dev.2146

package/dist/constructs.d.cts

@@ -1065,6 +1065,28 @@ interface TupleOptions {
    */
   readonly allowDuplicates?: boolean;
 }
+/**
+ * Options for the {@link seq} parser.
+ * @since 1.1.0
+ */
+interface SeqOptions {
+  /**
+   * When `true`, allows duplicate option names even when they can be active
+   * at the same sequential position. By default (`false`), duplicate option
+   * names at the same position cause a construction-time error.
+   *
+   * @default `false`
+   * @since 1.1.0
+   */
+  readonly allowDuplicates?: boolean;
+}
+type SeqTailOptions = SeqOptions & {
+  readonly $valueType?: never;
+};
+interface SeqState {
+  readonly index: number;
+  readonly states: readonly unknown[];
+}
 /**
  * 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
@@ -1094,6 +1116,55 @@ declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]
  *         whitespace-only, or contains control characters.
  */
 declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]>(label: string, parsers: T, options?: TupleOptions): Parser<CombineTupleModes<T>, { 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 an ordered parser that applies child parsers in declaration order.
+ *
+ * Unlike {@link tuple}, which lets child parsers compete for a shared input
+ * buffer by priority, `seq()` keeps a cursor and only parses the current child.
+ * A child may be skipped when its {@link Parser.canSkip} predicate reports
+ * that it can complete without consuming more CLI input.
+ *
+ * @template T A readonly array type where each element is a {@link Parser}.
+ * @param parsers Parsers to apply in the order they are provided.
+ * @returns A parser that produces a readonly tuple of child values.
+ * @since 1.1.0
+ */
+declare function seq<const T extends readonly Parser<Mode, unknown, unknown>[]>(...parsers: T): Parser<CombineTupleModes<T>, { readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, SeqState>;
+/**
+ * Creates an ordered parser with a label for generated documentation.
+ *
+ * @template T A readonly array type where each element is a {@link Parser}.
+ * @param label A descriptive label for this parser group.
+ * @param parsers Parsers to apply in the order they are provided.
+ * @returns A parser that produces a readonly tuple of child values.
+ * @throws {TypeError} If the label is empty, whitespace-only, or contains
+ *         control characters.
+ * @since 1.1.0
+ */
+declare function seq<const T extends readonly Parser<Mode, unknown, unknown>[]>(label: string, ...parsers: T): Parser<CombineTupleModes<T>, { readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, SeqState>;
+/**
+ * Creates an ordered parser with options.
+ *
+ * @template T A readonly array type where each element is a {@link Parser}.
+ * @param parsers Parsers to apply in the order they are provided, followed by
+ *                {@link SeqOptions}.
+ * @returns A parser that produces a readonly tuple of child values.
+ * @since 1.1.0
+ */
+declare function seq<const T extends readonly Parser<Mode, unknown, unknown>[]>(...args: readonly [...T, SeqTailOptions]): Parser<CombineTupleModes<T>, { readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, SeqState>;
+/**
+ * Creates a labeled ordered parser with options.
+ *
+ * @template T A readonly array type where each element is a {@link Parser}.
+ * @param label A descriptive label for this parser group.
+ * @param args Parsers to apply in the order they are provided, followed by
+ *             {@link SeqOptions}.
+ * @returns A parser that produces a readonly tuple of child values.
+ * @throws {TypeError} If the label is empty, whitespace-only, or contains
+ *         control characters.
+ * @since 1.1.0
+ */
+declare function seq<const T extends readonly Parser<Mode, unknown, unknown>[]>(label: string, ...args: readonly [...T, SeqTailOptions]): Parser<CombineTupleModes<T>, { readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, SeqState>;
 /**
  * Helper type to check if all members of a union are object-like.
  * This allows merge() to work with parsers like withDefault() that produce union types.
@@ -1398,4 +1469,4 @@ declare function conditional<TDiscriminator extends string, TBranches extends {
  */
 declare function conditional<TDiscriminator extends string, TBranches extends { [K in TDiscriminator]: Parser<Mode, unknown, unknown> }, TDefault extends Parser<Mode, unknown, unknown>, TD extends Parser<Mode, TDiscriminator, unknown>>(discriminator: TD, branches: TBranches, defaultBranch: TDefault, options?: ConditionalOptions): Parser<CombineModes<readonly [ExtractMode<TD>, ExtractMode<TDefault>, ...{ [K in keyof TBranches]: ExtractMode<TBranches[K]> }[keyof TBranches][]]>, ConditionalResultWithDefault<TDiscriminator, TBranches, TDefault>, ConditionalState<TDiscriminator>>;
 //#endregion
-export { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple };
+export { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple };

package/dist/constructs.d.ts

@@ -1065,6 +1065,28 @@ interface TupleOptions {
    */
   readonly allowDuplicates?: boolean;
 }
+/**
+ * Options for the {@link seq} parser.
+ * @since 1.1.0
+ */
+interface SeqOptions {
+  /**
+   * When `true`, allows duplicate option names even when they can be active
+   * at the same sequential position. By default (`false`), duplicate option
+   * names at the same position cause a construction-time error.
+   *
+   * @default `false`
+   * @since 1.1.0
+   */
+  readonly allowDuplicates?: boolean;
+}
+type SeqTailOptions = SeqOptions & {
+  readonly $valueType?: never;
+};
+interface SeqState {
+  readonly index: number;
+  readonly states: readonly unknown[];
+}
 /**
  * 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
@@ -1094,6 +1116,55 @@ declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]
  *         whitespace-only, or contains control characters.
  */
 declare function tuple<const T extends readonly Parser<Mode, unknown, unknown>[]>(label: string, parsers: T, options?: TupleOptions): Parser<CombineTupleModes<T>, { 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 an ordered parser that applies child parsers in declaration order.
+ *
+ * Unlike {@link tuple}, which lets child parsers compete for a shared input
+ * buffer by priority, `seq()` keeps a cursor and only parses the current child.
+ * A child may be skipped when its {@link Parser.canSkip} predicate reports
+ * that it can complete without consuming more CLI input.
+ *
+ * @template T A readonly array type where each element is a {@link Parser}.
+ * @param parsers Parsers to apply in the order they are provided.
+ * @returns A parser that produces a readonly tuple of child values.
+ * @since 1.1.0
+ */
+declare function seq<const T extends readonly Parser<Mode, unknown, unknown>[]>(...parsers: T): Parser<CombineTupleModes<T>, { readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, SeqState>;
+/**
+ * Creates an ordered parser with a label for generated documentation.
+ *
+ * @template T A readonly array type where each element is a {@link Parser}.
+ * @param label A descriptive label for this parser group.
+ * @param parsers Parsers to apply in the order they are provided.
+ * @returns A parser that produces a readonly tuple of child values.
+ * @throws {TypeError} If the label is empty, whitespace-only, or contains
+ *         control characters.
+ * @since 1.1.0
+ */
+declare function seq<const T extends readonly Parser<Mode, unknown, unknown>[]>(label: string, ...parsers: T): Parser<CombineTupleModes<T>, { readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, SeqState>;
+/**
+ * Creates an ordered parser with options.
+ *
+ * @template T A readonly array type where each element is a {@link Parser}.
+ * @param parsers Parsers to apply in the order they are provided, followed by
+ *                {@link SeqOptions}.
+ * @returns A parser that produces a readonly tuple of child values.
+ * @since 1.1.0
+ */
+declare function seq<const T extends readonly Parser<Mode, unknown, unknown>[]>(...args: readonly [...T, SeqTailOptions]): Parser<CombineTupleModes<T>, { readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, SeqState>;
+/**
+ * Creates a labeled ordered parser with options.
+ *
+ * @template T A readonly array type where each element is a {@link Parser}.
+ * @param label A descriptive label for this parser group.
+ * @param args Parsers to apply in the order they are provided, followed by
+ *             {@link SeqOptions}.
+ * @returns A parser that produces a readonly tuple of child values.
+ * @throws {TypeError} If the label is empty, whitespace-only, or contains
+ *         control characters.
+ * @since 1.1.0
+ */
+declare function seq<const T extends readonly Parser<Mode, unknown, unknown>[]>(label: string, ...args: readonly [...T, SeqTailOptions]): Parser<CombineTupleModes<T>, { readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, SeqState>;
 /**
  * Helper type to check if all members of a union are object-like.
  * This allows merge() to work with parsers like withDefault() that produce union types.
@@ -1398,4 +1469,4 @@ declare function conditional<TDiscriminator extends string, TBranches extends {
  */
 declare function conditional<TDiscriminator extends string, TBranches extends { [K in TDiscriminator]: Parser<Mode, unknown, unknown> }, TDefault extends Parser<Mode, unknown, unknown>, TD extends Parser<Mode, TDiscriminator, unknown>>(discriminator: TD, branches: TBranches, defaultBranch: TDefault, options?: ConditionalOptions): Parser<CombineModes<readonly [ExtractMode<TD>, ExtractMode<TDefault>, ...{ [K in keyof TBranches]: ExtractMode<TBranches[K]> }[keyof TBranches][]]>, ConditionalResultWithDefault<TDiscriminator, TBranches, TDefault>, ConditionalState<TDiscriminator>>;
 //#endregion
-export { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple };
+export { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple };