/** Represents some range in the source input we are parsing or parsed. */
type Span = [start: number, end: number];
/** Parsers of this type always succeed, e.g. `many` and `sepBy`. */
interface SucceedingParser<T> {
    parse(input: string, pos: number): Success<T>;
}
/** Parsers of this type always fail. */
interface FailingParser {
    parse(input: string, pos: number): Failure;
}
/** Parsers of this type may fail. */
interface UnsafeParser<T> {
    parse(input: string, pos: number): Result<T>;
}
/** Parser interface that all parsers and combinators consume and resolve to. */
type Parser<T> = FailingParser | SucceedingParser<T> | UnsafeParser<T>;
/** Represents failed execution. */
type Failure = {
    readonly isOk: false;
    readonly span: Span;
    readonly pos: number;
    readonly expected: string;
};
/** Represents successful execution. */
type Success<T> = {
    readonly isOk: true;
    readonly span: Span;
    readonly pos: number;
    readonly value: T;
};
/** Interface describing the result of parsers and combinators execution. */
type Result<T> = Success<T> | Failure;

/** @internal */
type UnionToIntersection<U> = (U extends never ? never : (arg: U) => never) extends (arg: infer I) => void ? I : never;
/** @internal */
type UnionToTuplePreserving<T> = UnionToIntersection<T extends never ? never : (t: T) => T> extends (_: never) => infer W ? [...UnionToTuplePreserving<Exclude<T, W>>, W] : [];
/** @internal */
type UnwrapParserTuple<T> = T extends [Parser<infer Head>, ...infer Tail] ? [Head, ...UnwrapParserTuple<Tail>] : [];
/** @internal */
type TupleToUnion<T> = T extends [infer Head, ...infer Rest] ? Head | TupleToUnion<Rest> : never;
/**
 * Given a tuple of `Parser<T>`s, recursively extracts inner `T`s into a tuple.
 *
 * @example
 *
 * ```ts
 * type U = [Parser<string>, Parser<number>, Parser<boolean>]
 * type R = ToTuple<U> // type R = [string, number, boolean]
 * ```
 */
type ToTuple<T> = T extends [Parser<infer Head>, ...infer Tail] ? [Head, ...ToTuple<Tail>] : [];
/**
 * Given a an array or a tuple of `Parser<T>`s, recursively extracts inner `T`s into a tuple or array.
 *
 * @example
 *
 * ```ts
 * type U = [Parser<string>, Parser<number>, Parser<boolean>]
 * type R = ToTuple<U> // type R = [string, number, boolean]
 *
 * type A = Parser<Array<string>>
 * type T = ToTupleOrArray<A> // type T = string[]
 * ```
 */
type ToTupleOrArray<T> = T extends Array<Parser<infer Inner>> ? Inner extends unknown ? T extends [Parser<infer Head>, ...infer Tail] ? [Head, ...ToTuple<Tail>] : Inner[] : [] : [];
/**
 * Given a tuple of `Parser<T>`s, recursively extracts inner `T`s into a union.
 *
 * @example
 *
 * ```ts
 * type U = [Parser<string>, Parser<number>, Parser<boolean>]
 * type R = ToUnion<U> // type R = string | number | boolean
 *
 * type U = Array<Parser<number>>
 * type R = ToUnion<U> // type R = number
 * ```
 */
type ToUnion<T> = T extends Array<Parser<infer Inner>> ? Inner : T extends [Parser<infer Head>, ...infer Tail] ? Head | ToUnion<Tail> : never;
/**
 * Given a union of `Parser<T>`s, recursively extracts their inner `T`s into a tuple.
 *
 * @example
 *
 * ```ts
 * type U = Parser<string> | Parser<number> | Parser<boolean>
 * type R = UnwrapUnion<U> // type R = [string, number, boolean]
 * ```
 */
type UnwrapUnion<T> = UnwrapParserTuple<UnionToTuplePreserving<T>>;
/**
 * Given a union of `Parser<T>`s, folds it into a single`Parser` with a union of inner `T`s.
 * In other words, it folds `Parser<T1> | Parser<T2> | ...` into `Parser<T1 | T2 | ...>`.
 *
 * Note: Technically, the result will be `SafeParser<T1 | T2 | ...> | UnsafeParser<T1 | T2 | ...>`,
 * but no worries, it's the definition of the `Parser<T>`.
 *
 * @example
 *
 * ```ts
 * type U = Parser<string> | Parser<number> | Parser<boolean>
 * type R = ToParser<U> // type R = Parser<string | number | boolean>
 * ```
 */
type ToParser<T> = UnwrapUnion<T> extends infer R ? Parser<TupleToUnion<R>> : Parser<unknown>;

/**
 * Applies `parser` without consuming any input. It doesn't care if `parser` succeeds or fails, it
 * won't consume any input.
 *
 * @param parser - Parser to apply
 *
 * @returns Result of `parser`
 */
declare function attempt<T>(parser: Parser<T>): Parser<T>;

/** @internal */
type Fn<L, R> = (left: L, right: R) => L;
/**
 * Parses *zero* or more occurrences of `parser`, separated by `op` (in [EBNF] notation:
 * `parser (op parser)*`). Returns a value obtained by a recursive left-associative application of
 * `fn` to the values returned by `op` and `parser`.
 *
 * This combinator is particularly useful for eliminating left recursion, which typically occurs in
 * expression grammars.
 *
 * [EBNF]: https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form
 *
 * @param parser - Parser to apply
 * @param op - Separating parser
 * @param fn - Left-associative function to apply to the values returned by `op` and `parser`
 *
 * @returns Value from `fn`
 */
declare function chainl<T, L extends T, R>(parser: Parser<L>, op: Parser<R>, fn: Fn<T, R>): Parser<T>;

/**
 * Applies `ps` parsers in order until one of them succeeds.
 *
 * @param ps - Parsers to apply
 *
 * @returns Value of the succeeding parser
 */
declare function choice<T extends Array<Parser<unknown>>>(...ps: T): Parser<ToUnion<T>>;

/**
 * Replaces `parser`'s error message with `expected`.
 *
 * @param parser - Parser of which error message should be replaced
 * @param expected - New error message
 *
 * @returns Unchanged `parser`'s result or failure with new error message
 */
declare function error<T>(parser: Parser<T>, expected: string): Parser<T>;

/**
 * Applies `parser` without consuming any input. If `parser` fails and consumes some input, so does
 * `lookahead`.
 *
 * @param parser - Parser to apply
 *
 * @returns Result of `parser`
 */
declare function lookahead<T>(parser: Parser<T>): Parser<T>;

/**
 * Applies `parser` *zero* or more times, collecting its results. Never fails.
 *
 * @param parser - Parser to apply
 *
 * @returns Array of the returned values of `parser`
 */
declare function many<T>(parser: Parser<T>): SucceedingParser<Array<T>>;
/**
 * Applies `parser` *one* or more times, collecting its results.
 *
 * @param parser - Parser to apply
 *
 * @returns Array of the returned values of `parser`
 */
declare function many1<T>(parser: Parser<T>): Parser<Array<T>>;

/**
 * Applies `fn` to the `parser`'s result.
 *
 * @param parser - Parser to apply
 * @param fn - Function to apply to `parser`'s result
 *
 * @returns Result of `fn`
 */
declare function map<T, R>(parser: Parser<T>, fn: (value: T, span: Span) => R): Parser<R>;
/**
 * Maps the `parser`'s result to a constant `value`.
 *
 * @param parser - Parser to apply
 * @param value - Value to map `parser`'s result to
 *
 * @returns `value`
 */
declare function mapTo<T, R>(parser: Parser<T>, value: R): Parser<R>;

/**
 * Applies `parser`. Only fails if `parser` fails.
 *
 * @param parser - Parser to apply
 *
 * @returns Result of `parser` or `null`
 */
declare function optional<T>(parser: Parser<T>): Parser<T | null>;

/**
 * Parses *zero* or more occurrences of `parser`, separated by `sep`. Never fails.
 *
 * @param parser - Parser to apply
 * @param sep - Separating parser
 *
 * @returns List of values (without separator) returned by `parser`
 */
declare function sepBy<T, S>(parser: Parser<T>, sep: Parser<S>): Parser<Array<T>>;
/**
 * Parses *one* or more occurrences of `parser`, separated by `sep`.
 *
 * @param parser - Parser to apply
 * @param sep - Separating parser
 *
 * @returns List of values (without separator) returned by `parser`
 */
declare function sepBy1<T, S>(parser: Parser<T>, sep: Parser<S>): Parser<Array<T>>;

/**
 * Applies `ps` parsers in order, until *all* of them succeed.
 *
 * @param ps - Parsers to apply
 *
 * @returns Tuple of values returned by `ps` parsers
 */
declare function sequence<T extends Array<Parser<unknown>>>(...ps: T): Parser<ToTuple<T>>;
declare function sequence<T extends Array<Parser<unknown>>>(...ps: T): Parser<ToTupleOrArray<T>>;

/**
 * Takes exactly **two** parsers and applies them in order, returning the result of the leftmost
 * `p1` parser.
 *
 * @param p1 - First parser to apply
 * @param p2 - Second parser to apply
 *
 * @returns Result of the leftmost `p1` parser
 */
declare function takeLeft<T1, T2>(p1: Parser<T1>, p2: Parser<T2>): Parser<T1>;
/**
 * Takes exactly **three** parsers and applies them in order, returning the result of the `p2`
 * parser in the middle.
 *
 * @param p1 - First parser to apply
 * @param p2 - Second parser to apply
 * @param p3 - Third parser to apply
 *
 * @returns Result of the `p2` parser in the middle
 */
declare function takeMid<T1, T2, T3>(p1: Parser<T1>, p2: Parser<T2>, p3: Parser<T3>): Parser<T2>;
/**
 * Takes exactly **two** parsers and applies them in order, returning the result of the rightmost
 * `p2` parser.
 *
 * @param p1 - First parser to apply
 * @param p2 - Second parser to apply
 *
 * @returns Result of the rightmost `p2` parser
 */
declare function takeRight<T1, T2>(p1: Parser<T1>, p2: Parser<T2>): Parser<T2>;
/**
 * Takes exactly **three** parsers and applies them in order, returning a tuple of the results of
 * `p1` and `p3` parsers.
 *
 * @param p1 - First parser to apply
 * @param p2 - Second parser to apply
 * @param p3 - Third parser to apply
 *
 * @returns Results of `p1` and `p3` parsers as a tuple
 */
declare function takeSides<T1, T2, T3>(p1: Parser<T1>, p2: Parser<T2>, p3: Parser<T3>): Parser<[T1, T3]>;

/**
 * Applies source `parser`, collects its output, and stops after `terminator` parser succeeds.
 *
 * @param parser - Parser to apply
 * @param terminator - Terminating parser to stop after
 *
 * @returns Tuple of values collected by `parser` and `terminator`
 */
declare function takeUntil<T, S>(parser: Parser<T>, terminator: Parser<S>): Parser<[Array<T>, S]>;
/**
 * Applies source `parser`, ignores its output, and stops after `terminator` parser succeeds.
 *
 * @param parser - Parser to apply
 * @param terminator - Terminating parser to stop after
 *
 * @returns Value of `terminator` parser
 */
declare function skipUntil<T, S>(parser: Parser<T>, terminator: Parser<S>): Parser<S>;

/**
 * Context provided to a callback for producing conditional/chained parser.
 *
 * @internal
 */
interface Context<T> {
    value: T;
    input: string;
    pos: number;
}
/**
 * Creates chained, context-aware `parser`, that may depend on the output of the `context` parser.
 *
 * @param context - Source (context) parser
 * @param parser - Function that returns a new parser
 *
 * @returns New parser
 */
declare function when<T, R extends Parser<unknown>>(context: Parser<T>, parser: (ctx: Context<T>) => R): ToParser<R>;

export { attempt, chainl, choice, error, lookahead, many, many1, map, mapTo, optional, sepBy, sepBy1, sequence, skipUntil, takeLeft, takeMid, takeRight, takeSides, takeUntil, when };