/**
 * # Parser Monad and Basic Combinators
 *
 * This module defines the basic types and combinators for the parser monad.
 * To learn about monadic parsers refer to the list of literature in the
 * [Wikipedia page](https://en.wikipedia.org/wiki/Parser_combinator).
 */
import * as inp from "./input";
import * as pr from "./result";
import * as lex from "./lexer";
import * as ref from "./ref";
/**
 *
 * ## Parsing Function
 *
 * `Parse<T, S>` type represents a parsing function whics takes a
 * `ParserInput<S>` stream as an argument and returns a `ParseResult<T>` object.
 * The type of value to be parsed and the type of terminals in the input stream
 * are given as type parameters `T` and `S`.
 */
export type Parse<T, S> = (input: inp.ParserInput<S>) => pr.ParseResult<T>;
/**
 * ## Parser Class
 *
 * The central type in the Parzec library is the `Parser<T, S>` class. It wraps
 * a parsing function and provides the core combinators to combine parsers in
 * various ways.
 */
export declare class Parser<T, S> {
    readonly parse: Parse<T, S>;
    /**
     * Constructor wraps the parsing function.
     */
    constructor(parse: Parse<T, S>);
    /**
     * The monadic bind that corresponds to Haskell's `>>=` operator. Runs
     * `this` parser, and if it succeeds, feeds its result to the `binder`
     * function that returns a new Parser. This is the basic operation that is
     * used in other combinators to glue parsers together.
     */
    bind<U>(binder: (value: T) => Parser<U, S>): Parser<U, S>;
    /**
     * The sequence operator. Runs `this` parser, and if it succeeds, runs the
     * `other` parser ignoring the result of `this` one.
     */
    seq<U>(other: Parser<U, S>): Parser<U, S>;
    /**
     * Map result of the parser to another value. This function implements a
     * [_functor_](https://en.wikipedia.org/wiki/Functor) which is a superclass
     * of monad.
     */
    map<U>(mapper: (value: T) => U): Parser<U, S>;
    /**
     * ## Conditional Parsing
     *
     * The ordered choice operation. Creates a parser that first runs `this`
     * parser, and if that fails, runs the `other` one. Corresponds to the `/`
     * operation in [PEG grammars](https://en.wikipedia.org/wiki/Parsing_expression_grammar).
     */
    or<U>(other: Parser<U, S>): Parser<T | U, S>;
    /**
     * Parse an optional value, if the parser fails then the default value is
     * returned.
     */
    optional(defaultValue: T): Parser<T, S>;
    /**
     * Parse an optional reference value, if the parser fails then null is
     * returned.
     */
    optionalRef(): Parser<T | null, S>;
    /**
     * Runs parser and checks that it succeeds and that the result it returns
     * satisfies a given predicate.
     */
    where(predicate: (value: T) => boolean): Parser<T, S>;
    /**
     * ## Parsing Multiple Items
     *
     * Creates a parser that will run `this` parser zero or more times. The
     * results of the input parser are added to an array.
     */
    zeroOrMore(): Parser<T[], S>;
    /**
     * Creates a parser that runs `this` parser one or more times.
     */
    oneOrMore(): Parser<T[], S>;
    /**
     * Parsing succeeds if `this` parser succeeds from `min` to `max` times.
     */
    occurrences(min: number, max: number): Parser<T[], S>;
    /**
     * ## Lookahead & Backtracking
     *
     * Check that `this` parser succeeds without consuming any input.
     * Corresponds to the `&` operator in PEG grammars.
     */
    and(): Parser<T, S>;
    /**
     * Check that `this` parser fails without consuming any input. Corresponds
     * to the `!` operator in PEG grammars.
     */
    not(): Parser<T, S>;
    /**
     * Bactrack to the current input position, even if the given parser fails
     * and has advanced the input position. Normally we do not bactrack when a
     * parser has advanced in the input. Doing so would loose the position where
     * the parsing failed and make error messages more vague. Sometimes,
     * however, we need more input lookahead. In these cases, you can use the
     * backtrack operation to retry the next rule.
     */
    backtrack(): Parser<T, S>;
    /**
     * ## Error Reporting and Debugging
     *
     * Give a human-readable name to the "thing" that the given parser matches.
     * This name is reported as expected value, if the parsing fails.
     */
    expect(expected: string): Parser<T, S>;
    /**
     * Attach debugging information to a parser. To trace which rules are
     * triggered during parsing, you can add debugging info to any parser. This
     * combinator produces a hierarchical tree of parser invocations which
     * includes information about input symbol and its position. If debugging
     * is disabled, this function does nothing.
     */
    trace(ruleName: string): Parser<T, S>;
}
/**
 * ## Debugging Options
 *
 * The following object contains the global settings that control the parser
 * reporting.
 */
export declare const parserDebug: {
    /**
     * When `debugging` flag is on parsers count the number of rules evaluated
     * during their operation. The `rulesEvaluated` field contains this
     * information.
     */
    debugging: boolean;
    rulesEvaluated: number;
    /**
     * If errorMessages flag is turned off, the expected information will not be
     * available in parse errors. This speeds up the parsing nominally.
     */
    errorMessages: boolean;
    /**
     * The current indentation level in the debugging output is stored in this
     * field.
     */
    indentation: number;
    /**
     * Indent the debug output by one level.
     */
    indent(): void;
    /**
     * Unndent the debug output by one level.
     */
    unindent(): void;
    /**
     * Write a string to the debug output.
     */
    write(text: string): void;
};
/**
 * ## Main Functions
 *
 * Attempt to parse an input with a given parser. Takes a Parser and a
 * ParserInput as arguments and return a ParseResult.
 */
export declare function tryParse<T, S>(parser: Parser<T, S>, input: inp.ParserInput<S>): pr.ParseResult<T>;
/**
 * Parse an input using a given parser, or throw an exception, if parsing fails.
 */
export declare function parse<T, S>(parser: Parser<T, S>, input: inp.ParserInput<S>): T;
/**
 * ## Monadic Returns
 *
 * Create a parser that always succeeds and returns the given value without
 * consuming any input. This function implements the monadic return, that is,
 * it lifts a value to the parser monad.
 */
export declare function mret<T, S>(value: T): Parser<T, S>;
/**
 * Create a parser that always fails. The terminals reported as
 * found or expected are given as an argument.
 */
export declare function fail<T, S>(found: string, ...expected: string[]): Parser<T, S>;
/**
 * ## Parsing Terminals
 *
 * Creates a parser that reads one terminal from the input and returns it, if it
 * satisfies the given predicate; otherwise the parser fails.
 */
export declare function satisfy<T>(predicate: (value: T) => boolean): Parser<T, T>;
/**
 * Creates a parser that reads one terminal from the input and returns it, if it
 * does **not** satisfy a given predicate.
 */
export declare function notSatisfy<T>(predicate: (value: T) => boolean): Parser<T, T>;
/**
 * Any of the given parsers must succeed. The operation is the same
 * as the `or` combinator generalized to arbitrary number of choices.
 */
export declare function any<T, S>(...parsers: Parser<T, S>[]): Parser<T, S>;
/**
 * Peek next symbol in the input stream without changing the position.
 */
export declare function peek<S>(): Parser<S, S>;
/**
 * Select a parser to be used based on the next symbol in the input. This
 * function is an alternative to the the "any" combinator. It reduces
 * backtracking when the parser to be applied can be deduced from the next
 * symbol.
 */
export declare function choose<T, S>(selector: (input: S) => Parser<T, S>): Parser<T, S>;
/**
 * ## Getting Current Position
 *
 * A parser that returns the current position of the input. This is useful
 * when binding parsers together and you want to know the position where you
 * currently are. The position can be also used for backtracking.
 */
export declare function position<S>(): Parser<number, S>;
/**
 * ## User-Managed State
 *
 * Get the current satellite state stored in the input.
 */
export declare function getState<T, S>(): Parser<T, S>;
/**
 * Set the current satellite state stored in the input. The new state
 * is not given explicitly. Rather, a funcion which returns the new
 * state is specified.
 */
export declare function setState<T, S>(newValue: () => T): Parser<T, S>;
/**
 * Mutate the satellite state stored in the input. The mutation is done
 * with a function given as an argument.
 */
export declare function mutateState<T, S>(mutate: (state: T) => void): Parser<T, S>;
/**
 * Check that the current state matches a predicate. If not, the result parser
 * fails.
 */
export declare function checkState<T, S>(predicate: (state: T) => boolean): Parser<T, S>;
/**
 * Clean up the current state after a parser has been executed. The clean-up
 * function is run regardless of whether the parser succeeds or fails.
 */
export declare function cleanupState<T, U, S>(parser: Parser<T, S>, cleanup: (state: U) => void): Parser<T, S>;
/**
 * ## Defining Mutually Recursive Parsers
 *
 * Often grammar rules are mutually recursive, which means that there is no way
 * to write them in an order where all the dependent rules are defined. In these
 * occasions, you can just create a _reference_ to a parser and set its
 * implementation later. To refer to the parser that is not yet defined, you can
 * use this function.
 */
export declare function forwardRef<T, S>(parser: ref.Ref<Parser<T, S>>): Parser<T, S>;
/**
 * ## General Parsers
 *
 * The catch-all parser that will match any symbol read from the input.
 */
export declare function anything<T>(): Parser<T, T>;
/**
 * Parser that succeeds if the symbol read from the input is equal (===) to
 * given parameter; otherwise parsing fails.
 */
export declare function is<T>(value: T): Parser<T, T>;
/**
 * Parse a specific token from the lexer input stream.
 */
export declare function token<T>(token: T): Parser<lex.Token<T>, lex.Token<T>>;
/**
 * Helper function to create a terminal parser.
 */
export declare function terminal<T>(tok: T, name: string): Parser<lex.Token<T>, lex.Token<T>>;