public Class ParserATNSimulator

Add an edge to the DFA, if possible. This method calls addDFAState to ensure the to state is present in the DFA. If from is null, or if t is outside the range of edges that can be represented in the DFA tables, this method returns without adding the edge to the DFA.

If to is null, this method returns null. Otherwise, this method returns the DFAState returned by calling addDFAState for the to state.

Parameters

dfa:DFA

The DFA

from:DFAState

The source state for the edge

t:int

The input symbol

to:DFAState

The target state for the edge

Returns:DFAState

If to is null, this method returns null; otherwise this method returns the result of calling addDFAState on to

Add state D to the DFA if it is not already present, and return the actual instance stored in the DFA. If a state equivalent to D is already in the DFA, the existing state is returned. Otherwise this method returns D after adding it to the DFA.

If D is ERROR, this method returns ERROR and does not change the DFA.

Parameters

dfa:DFA

The dfa

D:DFAState

The DFA state to add

Returns:DFAState

The state stored in the DFA. This will be either the existing state if D is already in the DFA, or D itself if the state was not already present.

This method transforms the start state computed by computeStartState to the special start state used by a precedence DFA for a particular precedence value. The transformation process applies the following changes to the start state's configuration set.

1. Evaluate the precedence predicates for each configuration using SemanticContext#evalPrecedence.
2. When ATNConfig#isPrecedenceFilterSuppressed is false, remove all configurations which predict an alternative greater than 1, for which another configuration that predicts alternative 1 is in the same ATN state with the same prediction context. This transformation is valid for the following reasons:
   • The closure block cannot contain any epsilon transitions which bypass the body of the closure, so all states reachable via alternative 1 are part of the precedence alternatives of the transformed left-recursive rule.
   • The "primary" portion of a left recursive rule cannot contain an epsilon transition, so the only way an alternative other than 1 can exist in a state that is also reachable via alternative 1 is by nesting calls to the left-recursive rule, with the outer calls not being at the preferred precedence level. The ATNConfig#isPrecedenceFilterSuppressed property marks ATN configurations which do not meet this condition, and therefore are not eligible for elimination during the filtering process.

The prediction context must be considered by this filter to address situations like the following.

grammar TA;
prog: statement* EOF;
statement: letterA | statement letterA 'b' ;
letterA: 'a';

If the above grammar, the ATN state immediately before the token reference 'a' in letterA is reachable from the left edge of both the primary and closure blocks of the left-recursive rule statement. The prediction context associated with each of these configurations distinguishes between them, and prevents the alternative which stepped out to prog (and then back in to statement from being eliminated by the filter.

Parameters

configs:ATNConfigSet

The configuration set computed by computeStartState as the start state for the DFA.

Returns:ATNConfigSet

The transformed configuration set representing the start state for a precedence DFA at a particular precedence level (determined by calling Parser#getPrecedence).

Implements first-edge (loop entry) elimination as an optimization during closure operations. See antlr/antlr4#1398. The optimization is to avoid adding the loop entry config when the exit path can only lead back to the same StarLoopEntryState after popping context at the rule end state (traversing only epsilon edges, so we're still in closure, in this same rule). We need to detect any state that can reach loop entry on epsilon w/o exiting rule. We don't have to look at FOLLOW links, just ensure that all stack tops for config refer to key states in LR rule. To verify we are in the right situation we must first check closure is at a StarLoopEntryState generated during LR removal. Then we check that each stack top of context is a return state from one of these cases: 1. 'not' expr, '(' type ')' expr. The return state points at loop entry state 2. expr op expr. The return state is the block end of internal block of (...)* 3. 'between' expr 'and' expr. The return state of 2nd expr reference. That state points at block end of internal block of (...)*. 4. expr '?' expr ':' expr. The return state points at block end, which points at loop entry state. If any is true for each stack top, then closure does not add a config to the current config set for edge[0], the loop entry branch. Conditions fail if any context for the current config is: a. empty (we'd fall out of expr to do a global FOLLOW which could even be to some weird spot in expr) or, b. lies outside of expr or, c. lies within expr but at a state not the BlockEndState generated during LR removal Do we need to evaluate predicates ever in closure for this case? No. Predicates, including precedence predicates, are only evaluated when computing a DFA start state. I.e., only before the lookahead (but not parser) consumes a token. There are no epsilon edges allowed in LR rule alt blocks or in the "primary" part (ID here). If closure is in StarLoopEntryState any lookahead operation will have consumed a token as there are no epsilon-paths that lead to StarLoopEntryState. We do not have to evaluate predicates therefore if we are in the generated StarLoopEntryState of a LR rule. Note that when making a prediction starting at that decision point, decision d=2, compute-start-state performs closure starting at edges[0], edges[1] emanating from StarLoopEntryState. That means it is not performing closure on StarLoopEntryState during compute-start-state. How do we know this always gives same prediction answer? Without predicates, loop entry and exit paths are ambiguous upon remaining input +b (in, say, a+b). Either paths lead to valid parses. Closure can lead to consuming + immediately or by falling out of this call to expr back into expr and loop back again to StarLoopEntryState to match +b. In this special case, we choose the more efficient path, which is to take the bypass path. The lookahead language has not changed because closure chooses one path over the other. Both paths lead to consuming the same remaining input during a lookahead operation. If the next token is an operator, lookahead will enter the choice block with operators. If it is not, lookahead will exit expr. Same as if closure had chosen to enter the choice block immediately. Closure is examining one config (some loopentrystate, some alt, context) which means it is considering exactly one alt. Closure always copies the same alt to any derived configs. How do we know this optimization doesn't mess up precedence in our parse trees? Looking through expr from left edge of stat only has to confirm that an input, say, a+b+c; begins with any valid interpretation of an expression. The precedence actually doesn't matter when making a decision in stat seeing through expr. It is only when parsing rule expr that we must use the precedence to get the right interpretation and, hence, parse tree.

Since

4.6

Do the actual work of walking epsilon edges

Compute a target state for an edge in the DFA, and attempt to add the computed state and corresponding edge to the DFA.

Parameters

dfa:DFA

The DFA

previousD:DFAState

The current DFA state

t:int

The next input symbol

Returns:DFAState

The computed target DFA state for the given input symbol t. If t does not lead to a valid DFA state, this method returns ERROR.

Look through a list of predicate/alt pairs, returning alts for the pairs that win. A NONE predicate indicates an alt containing an unpredicated config which behaves as "always true." If !complete then we stop at the first predicate that evaluates to true. This includes pairs with null predicates.

Evaluate a semantic context within a specific parser context.

This method might not be called for every semantic context evaluated during the prediction process. In particular, we currently do not evaluate the following but it may change in the future:

• Precedence predicates (represented by SemanticContext.PrecedencePredicate) are not currently evaluated through this method.
• Operator predicates (represented by SemanticContext.AND and SemanticContext.OR) are evaluated as a single semantic context, rather than evaluating the operands individually. Implementations which require evaluation results from individual predicates should override this method to explicitly handle evaluation of the operands within operator predicates.

Parameters

pred:SemanticContext

The semantic context to evaluate

parserCallStack:ParserRuleContext

The parser context in which to evaluate the semantic context

alt:int

The alternative which is guarded by pred

fullCtx:boolean

true if the evaluation is occurring during LL prediction; otherwise, false if the evaluation is occurring during SLL prediction

Since

4.3

Performs ATN simulation to compute a predicted alternative based upon the remaining input, but also updates the DFA cache to avoid having to traverse the ATN again for the same input sequence. There are some key conditions we're looking for after computing a new set of ATN configs (proposed DFA state): if the set is empty, there is no viable alternative for current symbol does the state uniquely predict an alternative? does the state have a conflict that would prevent us from putting it on the work list? We also have some key operations to do: add an edge from previous DFA state to potentially new DFA state, D, upon current symbol but only if adding to work list, which means in all cases except no viable alternative (and possibly non-greedy decisions?) collecting predicates and adding semantic context to DFA accept states adding rule context to context-sensitive DFA accept states consuming an input symbol reporting a conflict reporting an ambiguity reporting a context sensitivity reporting insufficient predicates cover these cases: dead end single alt single alt + preds conflict conflict + preds

Gets a BitSet containing the alternatives in configs which are part of one or more conflicting alternative subsets.

Parameters

configs:ATNConfigSet

The ATNConfigSet to analyze.

Returns:BitSet

The alternatives in configs which are part of one or more conflicting alternative subsets. If configs does not contain any conflicting subsets, this method returns an empty BitSet.

Sam pointed out a problem with the previous definition, v3, of ambiguous states. If we have another state associated with conflicting alternatives, we should keep going. For example, the following grammar s : (ID | ID ID?) ';' ; When the ATN simulation reaches the state before ';', it has a DFA state that looks like: [12|1|[], 6|2|[], 12|2|[]]. Naturally 12|1|[] and 12|2|[] conflict, but we cannot stop processing this node because alternative to has another way to continue, via [6|2|[]]. The key is that we have a single state that has config's only associated with a single alternative, 2, and crucially the state transitions among the configurations are all non-epsilon transitions. That means we don't consider any conflicts that include alternative 2. So, we ignore the conflict between alts 1 and 2. We ignore a set of conflicting alts when there is an intersection with an alternative associated with a single alt state in the state→config-list map. It's also the case that we might have two conflicting configurations but also a 3rd nonconflicting configuration for a different alternative: [1|1|[], 1|2|[], 8|3|[]]. This can come about from grammar: a : A | A | A B ; After matching input A, we reach the stop state for rule A, state 1. State 8 is the state right before B. Clearly alternatives 1 and 2 conflict and no amount of further lookahead will separate the two. However, alternative 3 will be able to continue and so we do not stop working on this state. In the previous example, we're concerned with states associated with the conflicting alternatives. Here alt 3 is not associated with the conflicting configs, but since we can continue looking for input reasonably, I don't declare the state done. We ignore a set of conflicting alts when we have an alternative that we still need to pursue.

Get an existing target state for an edge in the DFA. If the target state for the edge has not yet been computed or is otherwise not available, this method returns null.

Parameters

previousD:DFAState

The current DFA state

t:int

The next input symbol

Returns:DFAState

The existing target DFA state for the given input symbol t, or null if the target state for this edge is not already cached

This method is used to improve the localization of error messages by choosing an alternative rather than throwing a NoViableAltException in particular prediction scenarios where the ERROR state was reached during ATN simulation.

The default implementation of this method uses the following algorithm to identify an ATN configuration which successfully parsed the decision entry rule. Choosing such an alternative ensures that the ParserRuleContext returned by the calling rule will be complete and valid, and the syntax error will be reported later at a more localized location.

• If a syntactically valid path or paths reach the end of the decision rule and they are semantically valid if predicated, return the min associated alt.
• Else, if a semantically invalid but syntactically valid path exist or paths exist, return the minimum associated alt.
• Otherwise, return ATN#INVALID_ALT_NUMBER.

In some scenarios, the algorithm described above could predict an alternative which will result in a FailedPredicateException in the parser. Specifically, this could occur if the only configuration capable of successfully parsing to the end of the decision rule is blocked by a semantic predicate. By choosing this alternative within adaptivePredict instead of throwing a NoViableAltException, the resulting FailedPredicateException in the parser will identify the specific predicate which is preventing the parser from successfully parsing the decision rule, which helps developers identify and correct logic errors in semantic predicates.

Parameters

configs:ATNConfigSet

The ATN configurations which were valid immediately before the ERROR state was reached

outerContext:ParserRuleContext

The is the \gamma_0 initial parser context from the paper or the parser stack at the instant before prediction commences.

Returns:int

The value to return from adaptivePredict, or ATN#INVALID_ALT_NUMBER if a suitable alternative was not identified and adaptivePredict should report an error instead.

Return a configuration set containing only the configurations from configs which are in a RuleStopState. If all configurations in configs are already in a rule stop state, this method simply returns configs.

When lookToEndOfRule is true, this method uses ATN#nextTokens for each configuration in configs which is not already in a rule stop state to see if a rule stop state is reachable from the configuration via epsilon-only transitions.

Parameters

configs:ATNConfigSet

the configuration set to update

lookToEndOfRule:boolean

when true, this method checks for rule stop states reachable by epsilon-only transitions from each configuration in configs.

Returns:ATNConfigSet

configs if all configurations in configs are in a rule stop state, otherwise return a new configuration set containing only the configurations from configs which are in a rule stop state

If context sensitive parsing, we know it's ambiguity not conflict

Walk the list of configurations and split them according to those that have preds evaluating to true/false. If no pred, assume true pred and include in succeeded set. Returns Pair of sets. Create a new set so as not to alter the incoming parameter. Assumption: the input stream has been restored to the starting point prediction, which is where predicates need to evaluate.