/** 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>;

/** @internal */
interface Runnable$1<T> {
    with(input: string): Result<T>;
}
/**
 * Runs a parser with provided input.
 *
 * @param parser - Parser to run
 *
 * @returns Parser result
 */
declare function run<T>(parser: Parser<T>): Runnable$1<T>;

/** @internal */
interface Runnable<T> {
    with(input: string): Success<T>;
}
/** @internal */
type ErrorResult = Omit<Failure, 'isOk'>;
declare class ParserError extends Error {
    readonly name = "ParserError";
    readonly span: Span;
    readonly pos: number;
    constructor(res: ErrorResult);
}
/**
 * Runs a parser with provided input, throwing on failure.
 *
 * @param parser - Parser to run
 * @throws {@link ParserError} Parser error with `message` (`expected`) `span`, and `pos`
 *
 * @returns Parser result
 */
declare function tryRun<T>(parser: Parser<T>): Runnable<T>;

/**
 * This type extracts the return-types from the parser initializers.
 */
type Grammar<T> = {
    [P in keyof T]: T[P] extends () => unknown ? ReturnType<T[P]> : never;
};
/**
 * This type injects the initialized parser types into `this`, allowing for
 * type-safe self-contained and mutually recursive grammars.
 */
type GrammarInit<T> = T & ThisType<Grammar<T>>;
/**
 * This defines the input to the `grammar` function - the parser initializers.
 */
type GrammarType = {
    [name: string]: () => Parser<unknown>;
};
/**
 * This is a utility function to simplify the creation of a self-contained grammar.
 *
 * Similarly to `defer`, this allows for the creation of mutually recursive parsers,
 * but lets you define all of the component parsers within a single call.
 *
 * The function takes an object with parser initializers, and returns an object with
 * all of those parsers initialized. Within the parser initializers, use `this` to
 * reference other initialized parsers, as in the example below.
 *
 * The properties of the resulting object are just regular parsers - you can freely
 * destructure these, pass them around individually, or compose them with other
 * grammars, parsers or combinators as needed.
 *
 * @example
 *
 * ```typescript
 * interface NumberNode {
 *   type: 'number'
 *   value: number
 * }
 *
 * interface ListNode {
 *   type: 'list'
 *   value: Array<NumberNode | ListNode>
 * }
 *
 * const tupleGrammar = grammar({
 *   tupleNumber(): Parser<NumberNode> {
 *     return map(integer(), (value, span) => ({ type: 'number', span, value }))
 *   },
 *   tupleList(): Parser<ListNode> {
 *     return map(
 *       takeMid(
 *         string('('),
 *         sepBy(choice(this.tupleList, this.tupleNumber), string(',')),
 *         string(')')
 *       ),
 *       (value, span) => ({ type: 'list', span, value })
 *     )
 *   }
 * })
 *
 * const result = run(tupleGrammar.tupleList).with('(1,2,(3,4))')
 * ```
 */
declare function grammar<T extends GrammarType>(init: GrammarInit<T>): Grammar<T>;

/**
 * Parses any single character from the input and returns it. Fails at the end of input.
 *
 * @returns A single parsed character.
 */
declare function any(): Parser<string>;

/**
 * Intersection type to add a method for deferred parser definition.
 *
 * @internal
 */
type Deferred<T> = Parser<T> & {
    with(parser: Parser<T>): void;
};
/**
 * This is a special parser that has an additional `with` method, which should be used to define the
 * parser. This parser is tailored for creating mutually recursive parsers.
 *
 * @example
 *
 * ```typescript
 * interface NumberNode {
 *   type: 'number'
 *   value: number
 * }
 *
 * interface ListNode {
 *   type: 'list'
 *   value: Array<NumberNode | ListNode>
 * }
 *
 * // Here we create 'dummies'
 *
 * const TupleList = defer<ListNode>()
 * const TupleNumber = defer<NumberNode>()
 *
 * // And below we actually define parsers
 *
 * TupleNumber.with(
 *   map(
 *     int(),
 *     (value) => ({ type: 'number', value })
 *   )
 * )
 *
 * TupleList.with(
 *   map(
 *     takeMid(
 *       string('('),
 *       sepBy(choice(TupleList, TupleNumber), string(',')),
 *       string(')')
 *     ),
 *     (value) => ({ type: 'list', value })
 *   )
 * )
 *
 * console.log(
 *   run(TupleList).with('(1,2,(3,(4,5)))')
 * )
 * ```
 */
declare function defer<T>(): Deferred<T>;

/**
 * Only succeeds at the end of the input.
 *
 * @returns `null`
 */
declare function eof(): Parser<null>;

/**
 * Only succeeds at the end of the line, either `\n` or `\r\n`.
 *
 * @returns Matched line break character
 */
declare function eol(): Parser<string>;

/**
 * Parses a single alphabetical character. Unicode friendly.
 *
 * @returns Matched character.
 */
declare function letter(): Parser<string>;
/**
 * Parses a sequence of alphabetical characters. Unicode friendly.
 *
 * @returns Matched characters as a string.
 */
declare function letters(): Parser<string>;

/**
 * Ensures that none of the characters in the given string matches the current character.
 *
 * @param chars - A string of characters that current character should not match
 *
 * @returns Current character
 */
declare function noneOf(chars: string): Parser<string>;

/**
 * Simply resolves to `null`.
 *
 * @returns `null`.
 */
declare function nothing(): Parser<null>;

/**
 * Parses a hexadecimal number prefixed with `0x` or `0X`, e.g. `0xFF`, `0XFF`, `0xff`.
 *
 * @returns Parsed hexadecimal number as a decimal one
 */
declare function hex(): Parser<number>;
/**
 * Parses a binary number prefixed with `0b` or `0B`, e.g. `0b101`, `0B101`.
 *
 * @returns Parsed binary number as a decimal one
 */
declare function binary(): Parser<number>;
/**
 * Parses an octal number prefixed with `0o` or `0O`, e.g. `0o420`, `0O420`.
 *
 * @returns Parsed octal number as a decimal one
 */
declare function octal(): Parser<number>;
/**
 * Parses a positive whole number without leading zeros, e.g. `0`, `7`, `420`.
 *
 * @returns Parsed whole number
 */
declare function whole(): Parser<number>;
/**
 * Parses an integer number with an optional minus sign, e.g. `0`, `-7`, `420`.
 *
 * @returns Parsed integer number
 */
declare function integer(): Parser<number>;
/**
 * Parses a float number with an optional minus sign, e.g. `0.25`, `-7.90`, `4.20`.
 *
 * Note: It doesn't handle floats with exponent parts.
 *
 * @returns Parsed float number
 */
declare function float(): Parser<number>;

/**
 * Ensures that one of the characters in the given string matches the current character.
 *
 * @param chars - A string of characters that current character should match
 *
 * @returns Current character
 */
declare function oneOf(chars: string): Parser<string>;

/**
 * Parses a string that matches a provided `re` regular expression. Returns the matched string, or
 * fails with an `expected` message.
 *
 * The regular expression must obey two simple rules:
 *
 * - It *does* use `g` flag. Flags like u and i are allowed and can be added if needed.
 * - It *doesn't* use `^` and `$` to match at the beginning or at the end of the text.
 *
 * If `g` flag is missing, it will be automatically injected. It's still better to always provide it
 * to avoid small performance penalty and clearly document the intention.
 *
 * @param rs - Regular expression
 * @param expected - Error message if the regular expression does not match input
 *
 * @returns Matched string
 */
declare function regexp(rs: RegExp, expected: string): Parser<string>;

/**
 * Simply returns the unparsed input as a string. Never fails.
 *
 * @returns Rest of the input as a string
 */
declare function rest(): SucceedingParser<string>;

/**
 * Parses an *ASCII* string. For parsing Unicode strings, consider using `ustring`.
 *
 * @param match - String to parse
 *
 * @returns Parsed string
 */
declare function string(match: string): Parser<string>;
/**
 * Parses a Unicode string. For parsing ASCII-only strings, consider using `string`.
 *
 * @param match - String to parse
 *
 * @returns Parsed string
 */
declare function ustring(match: string): Parser<string>;

/**
 * Parses whitespace, either a single character or consecutive ones.
 *
 * @returns Matched whitespace character(s)
 */
declare function whitespace(): Parser<string>;

export { FailingParser, Failure, Grammar, GrammarInit, GrammarType, Parser, ParserError, Result, Span, SucceedingParser, Success, ToParser, ToTuple, ToTupleOrArray, ToUnion, TupleToUnion, UnionToIntersection, UnionToTuplePreserving, UnsafeParser, UnwrapParserTuple, UnwrapUnion, any, attempt, binary, chainl, choice, defer, eof, eol, error, float, grammar, hex, integer, letter, letters, lookahead, many, many1, map, mapTo, noneOf, nothing, octal, oneOf, optional, regexp, rest, run, sepBy, sepBy1, sequence, skipUntil, string, takeLeft, takeMid, takeRight, takeSides, takeUntil, tryRun, ustring, when, whitespace, whole };