/** 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 */
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 { Grammar, GrammarInit, GrammarType, ParserError, any, binary, defer, eof, eol, float, grammar, hex, integer, letter, letters, noneOf, nothing, octal, oneOf, regexp, rest, run, string, tryRun, ustring, whitespace, whole };