The type of automaton states.

States are numbered.

The type of tokens. These can be thought of as real tokens, that is, tokens returned by the lexer. They carry a semantic value. This type does not include the error pseudo-token.

The type of terminal symbols. These can be thought of as integer codes. They do not carry a semantic value. This type does include the error pseudo-token.

The type of nonterminal symbols.

The type of semantic values.

A token is conceptually a pair of a (non-error) terminal symbol and a semantic value. The function token2terminal is the first the pair projection.

A token is conceptually a pair of a (non-error) terminal symbol and a semantic value. The function token2value is the second the pair projection.

The terminal symbol associated with the error token.

The semantic value associated with the error token.

foreach_terminal iterates over all terminal symbols.

The type of productions.

production_index maps a production to its integer index.

find_production maps a production index to a production. Its argument must be a valid index; use with care.

If a state s has a default reduction on production prod, then, upon entering s, the automaton should reduce prod without consulting the lookahead token.

default_reduction s determines whether the state s has a default reduction. Instead of returning a value of a sum type -- say, either DefRed prod or NoDefRed -- it accepts two continuations, and invokes just one of them.

An LR automaton can normally take three kinds of actions: shift, reduce, or fail. (Acceptance is a particular case of reduction: it consists in reducing a start production.)

There are two variants of the shift action. shift/discard s instructs the automaton to discard the current token, request a new one from the lexer, and move to state s. shift/nodiscard s instructs it to move to state s without requesting a new token. This instruction should be used when s has a default reduction on #.

The function action provides access to the automaton's action table. It maps a pair of a state and a terminal symbol to an action.

Instead of returning a value of a sum type -- one of shift/discard, shift/nodiscard, reduce, or fail -- this function accepts three continuations, and invokes just one them.

The parameters of the function action are as follows:

• the first two parameters, a state and a terminal symbol, are used to look up the action table;

• the next parameter is the semantic value associated with the above terminal symbol; it is not used, only passed along to the shift continuation, as explained below;

• the shift continuation expects an environment; a flag that tells whether to discard the current token; the terminal symbol that is being shifted; its semantic value; and the target state of the transition;

• the reduce continuation expects an environment and a production;

• the fail continuation expects an environment;

• the last parameter is the environment; it is not used, only passed along to the selected continuation.

maybe_shift_t s t determines whether there exists a transition out of the state s, labeled with the terminal symbol t, to some state s'. If so, it returns Some s'. Otherwise, it returns None.

may_reduce_prod s t prod determines whether in the state s, with lookahead symbol t, the automaton reduces production prod. This test accounts for the possible existence of a default reduction.

The function goto_nt provides access to the automaton's goto table. It maps a pair of a state s and a nonterminal symbol nt to a state. The function call goto_nt s nt is permitted ONLY if the state s has an outgoing transition labeled nt. Otherwise, its result is undefined.

The function goto_prod also provides access to the goto table. It maps a pair of a production prod and a state s to a state. The call goto_prod prod s is permitted ONLY if the state s has an outgoing transition labeled with the nonterminal symbol lhs prod.

The function maybe_goto_nt serves the same purpose as goto_nt. Compared to goto_nt, it involves an additional dynamic check, so it CAN be called even the state s has no outgoing transition labeled nt.

lhs prod returns the left-hand side of production prod, a nonterminal symbol.

is_start prod tells whether the production prod is a start production.

A semantic action can raise the exception Error.

By convention, a semantic action is responsible for:

1. fetching whatever semantic values and positions it needs off the stack;

2. popping an appropriate number of cells off the stack, as dictated by the length of the right-hand side of the production;

3. computing a new semantic value, as well as new start and end positions;

4. pushing a new stack cell, which contains the three values computed in step 3;

5. returning the new stack computed in steps 2 and 4.

The function semantic_action maps a production to its semantic action.

may_reduce state prod tests whether the state state is capable of reducing the production prod. This function is currently costly and is not used by the core LR engine. It is used in the implementation of certain functions, such as force_reduction, which allow the engine to be driven programmatically.

If the flag log is false, then the logging functions are not called. If it is true, then they are called.

The logging hooks required by the LR engine.