Package org.antlr.v4.runtime.atn

Class ParserATNSimulator

java.lang.Object
org.antlr.v4.runtime.atn.ATNSimulator
org.antlr.v4.runtime.atn.ParserATNSimulator
Direct Known Subclasses:
ProfilingATNSimulator
public class ParserATNSimulator extends ATNSimulator
The embodiment of the adaptive LL(*), ALL(*), parsing strategy.

The basic complexity of the adaptive strategy makes it harder to understand. We begin with ATN simulation to build paths in a DFA. Subsequent prediction requests go through the DFA first. If they reach a state without an edge for the current symbol, the algorithm fails over to the ATN simulation to complete the DFA path for the current input (until it finds a conflict state or uniquely predicting state).

All of that is done without using the outer context because we want to create a DFA that is not dependent upon the rule invocation stack when we do a prediction. One DFA works in all contexts. We avoid using context not necessarily because it's slower, although it can be, but because of the DFA caching problem. The closure routine only considers the rule invocation stack created during prediction beginning in the decision rule. For example, if prediction occurs without invoking another rule's ATN, there are no context stacks in the configurations. When lack of context leads to a conflict, we don't know if it's an ambiguity or a weakness in the strong LL(*) parsing strategy (versus full LL(*)).

When SLL yields a configuration set with conflict, we rewind the input and retry the ATN simulation, this time using full outer context without adding to the DFA. Configuration context stacks will be the full invocation stacks from the start rule. If we get a conflict using full context, then we can definitively say we have a true ambiguity for that input sequence. If we don't get a conflict, it implies that the decision is sensitive to the outer context. (It is not context-sensitive in the sense of context-sensitive grammars.)

The next time we reach this DFA state with an SLL conflict, through DFA simulation, we will again retry the ATN simulation using full context mode. This is slow because we can't save the results and have to "interpret" the ATN each time we get that input.

CACHING FULL CONTEXT PREDICTIONS

We could cache results from full context to predicted alternative easily and that saves a lot of time but doesn't work in presence of predicates. The set of visible predicates from the ATN start state changes depending on the context, because closure can fall off the end of a rule. I tried to cache tuples (stack context, semantic context, predicted alt) but it was slower than interpreting and much more complicated. Also required a huge amount of memory. The goal is not to create the world's fastest parser anyway. I'd like to keep this algorithm simple. By launching multiple threads, we can improve the speed of parsing across a large number of files.

There is no strict ordering between the amount of input used by SLL vs LL, which makes it really hard to build a cache for full context. Let's say that we have input A B C that leads to an SLL conflict with full context X. That implies that using X we might only use A B but we could also use A B C D to resolve conflict. Input A B C D could predict alternative 1 in one position in the input and A B C E could predict alternative 2 in another position in input. The conflicting SLL configurations could still be non-unique in the full context prediction, which would lead us to requiring more input than the original A B C. To make a prediction cache work, we have to track the exact input used during the previous prediction. That amounts to a cache that maps X to a specific DFA for that context.

Something should be done for left-recursive expression predictions. They are likely LL(1) + pred eval. Easier to do the whole SLL unless error and retry with full LL thing Sam does.

AVOIDING FULL CONTEXT PREDICTION

We avoid doing full context retry when the outer context is empty, we did not dip into the outer context by falling off the end of the decision state rule, or when we force SLL mode.

As an example of the not dip into outer context case, consider as super constructor calls versus function calls. One grammar might look like this:

 ctorBody
   : '{' superCall? stat* '}'
   ;

Or, you might see something like

 stat
   : superCall ';'
   | expression ';'
   | ...
   ;

In both cases I believe that no closure operations will dip into the outer context. In the first case ctorBody in the worst case will stop at the '}'. In the 2nd case it should stop at the ';'. Both cases should stay within the entry rule and not dip into the outer context.

PREDICATES

Predicates are always evaluated if present in either SLL or LL both. SLL and LL simulation deals with predicates differently. SLL collects predicates as it performs closure operations like ANTLR v3 did. It delays predicate evaluation until it reaches and accept state. This allows us to cache the SLL ATN simulation whereas, if we had evaluated predicates on-the-fly during closure, the DFA state configuration sets would be different and we couldn't build up a suitable DFA.

When building a DFA accept state during ATN simulation, we evaluate any predicates and return the sole semantically valid alternative. If there is more than 1 alternative, we report an ambiguity. If there are 0 alternatives, we throw an exception. Alternatives without predicates act like they have true predicates. The simple way to think about it is to strip away all alternatives with false predicates and choose the minimum alternative that remains.

When we start in the DFA and reach an accept state that's predicated, we test those and return the minimum semantically viable alternative. If no alternatives are viable, we throw an exception.

During full LL ATN simulation, closure always evaluates predicates and on-the-fly. This is crucial to reducing the configuration set size during closure. It hits a landmine when parsing with the Java grammar, for example, without this on-the-fly evaluation.

SHARING DFA

All instances of the same parser share the same decision DFAs through a static field. Each instance gets its own ATN simulator but they share the same ATN.decisionToDFA field. They also share a PredictionContextCache object that makes sure that all PredictionContext objects are shared among the DFA states. This makes a big size difference.

THREAD SAFETY

The ParserATNSimulator locks on the ATN.decisionToDFA field when it adds a new DFA object to that array. addDFAEdge(org.antlr.v4.runtime.dfa.DFA, org.antlr.v4.runtime.dfa.DFAState, int, org.antlr.v4.runtime.misc.IntegerList, org.antlr.v4.runtime.atn.ATNConfigSet, org.antlr.v4.runtime.atn.PredictionContextCache) locks on the DFA for the current decision when setting the DFAState.edges field. addDFAState(org.antlr.v4.runtime.dfa.DFA, org.antlr.v4.runtime.atn.ATNConfigSet, org.antlr.v4.runtime.atn.PredictionContextCache) locks on the DFA for the current decision when looking up a DFA state to see if it already exists. We must make sure that all requests to add DFA states that are equivalent result in the same shared DFA object. This is because lots of threads will be trying to update the DFA at once. The addDFAState(org.antlr.v4.runtime.dfa.DFA, org.antlr.v4.runtime.atn.ATNConfigSet, org.antlr.v4.runtime.atn.PredictionContextCache) method also locks inside the DFA lock but this time on the shared context cache when it rebuilds the configurations' PredictionContext objects using cached subgraphs/nodes. No other locking occurs, even during DFA simulation. This is safe as long as we can guarantee that all threads referencing s.edge[t] get the same physical target DFAState, or null. Once into the DFA, the DFA simulation does not reference the DFA.states map. It follows the DFAState.edges field to new targets. The DFA simulator will either find DFAState.edges to be null, to be non-null and dfa.edges[t] null, or dfa.edges[t] to be non-null. The addDFAEdge(org.antlr.v4.runtime.dfa.DFA, org.antlr.v4.runtime.dfa.DFAState, int, org.antlr.v4.runtime.misc.IntegerList, org.antlr.v4.runtime.atn.ATNConfigSet, org.antlr.v4.runtime.atn.PredictionContextCache) method could be racing to set the field but in either case the DFA simulator works; if null, and requests ATN simulation. It could also race trying to get dfa.edges[t], but either way it will work because it's not doing a test and set operation.

Starting with SLL then failing to combined SLL/LL (Two-Stage Parsing)

Sam pointed out that if SLL does not give a syntax error, then there is no point in doing full LL, which is slower. We only have to try LL if we get a syntax error. For maximum speed, Sam starts the parser set to pure SLL mode with the BailErrorStrategy:

 parser.getInterpreter().setPredictionMode(PredictionMode.SLL);
 parser.setErrorHandler(new BailErrorStrategy());

If it does not get a syntax error, then we're done. If it does get a syntax error, we need to retry with the combined SLL/LL strategy.

The reason this works is as follows. If there are no SLL conflicts, then the grammar is SLL (at least for that input set). If there is an SLL conflict, the full LL analysis must yield a set of viable alternatives which is a subset of the alternatives reported by SLL. If the LL set is a singleton, then the grammar is LL but not SLL. If the LL set is the same size as the SLL set, the decision is SLL. If the LL set has size > 1, then that decision is truly ambiguous on the current input. If the LL set is smaller, then the SLL conflict resolution might choose an alternative that the full LL would rule out as a possibility based upon better context information. If that's the case, then the SLL parse will definitely get an error because the full LL analysis says it's not viable. If SLL conflict resolution chooses an alternative within the LL set, them both SLL and LL would choose the same alternative because they both choose the minimum of multiple conflicting alternatives.

Let's say we have a set of SLL conflicting alternatives {1, 2, 3} and a smaller LL set called s. If s is {2, 3}, then SLL parsing will get an error because SLL will pursue alternative 1. If s is {1, 2} or {1, 3} then both SLL and LL will choose the same alternative because alternative one is the minimum of either set. If s is {2} or {3} then SLL will get a syntax error. If s is {1} then SLL will succeed.

Of course, if the input is invalid, then we will get an error for sure in both SLL and LL parsing. Erroneous input will therefore require 2 passes over the input.

  • Field Details

    • debug

      public static final boolean debug
      See Also:

    • dfa_debug

      public static final boolean dfa_debug
      See Also:

    • retry_debug

      public static final boolean retry_debug
      See Also:

    • predictionMode

      @NotNull private PredictionMode predictionMode

    • force_global_context

      public boolean force_global_context

    • always_try_local_context

      public boolean always_try_local_context

    • enable_global_context_dfa

      public boolean enable_global_context_dfa
      Determines whether the DFA is used for full-context predictions. When true, the DFA stores transition information for both full-context and SLL parsing; otherwise, the DFA only stores SLL transition information.

      For some grammars, enabling the full-context DFA can result in a substantial performance improvement. However, this improvement typically comes at the expense of memory used for storing the cached DFA states, configuration sets, and prediction contexts.

      The default value is false.

    • optimize_unique_closure

      public boolean optimize_unique_closure

    • optimize_ll1

      public boolean optimize_ll1

    • optimize_hidden_conflicted_configs

      @Deprecated public boolean optimize_hidden_conflicted_configs
      Deprecated.
      This flag is not currently used by the ATN simulator.

    • optimize_tail_calls

      public boolean optimize_tail_calls

    • tail_call_preserves_sll

      public boolean tail_call_preserves_sll

    • treat_sllk1_conflict_as_ambiguity

      public boolean treat_sllk1_conflict_as_ambiguity

    • parser

      @Nullable protected final Parser parser

    • subclassObservesDfaEdge

      private final boolean subclassObservesDfaEdge
      A subclass that overrides getExistingTargetState(org.antlr.v4.runtime.dfa.DFAState, int) (the profiler) must see full-context DFA edges. The base class reuses the edge it already loaded. One class test at construction, not per edge.

    • reportAmbiguities

      public boolean reportAmbiguities
      When true, ambiguous alternatives are reported when they are encountered within execATN(org.antlr.v4.runtime.dfa.DFA, org.antlr.v4.runtime.TokenStream, int, org.antlr.v4.runtime.atn.SimulatorState). When false, these messages are suppressed. The default is false.

      When messages about ambiguous alternatives are not required, setting this to false enables additional internal optimizations which may lose this information.

    • userWantsCtxSensitive

      protected boolean userWantsCtxSensitive
      By default we do full context-sensitive LL(*) parsing not Strong LL(*) parsing. If we fail with Strong LL(*) we try full LL(*). That means we rewind and use context information when closure operations fall off the end of the rule that holds the decision were evaluating.

    • dfa

      private DFA dfa

    • epsilonClosure

      private final EpsilonClosure epsilonClosure
      Epsilon-closure engine for this simulator. Package-private access for EpsilonClosure; not part of the public API.

    • reachComputation

      private final ReachComputation reachComputation
      Reach / target-state engine: retained config sets and the edge computation for computeTargetState(org.antlr.v4.runtime.dfa.DFA, org.antlr.v4.runtime.dfa.DFAState, org.antlr.v4.runtime.ParserRuleContext, int, boolean, org.antlr.v4.runtime.atn.PredictionContextCache). Package-private; not part of the public API.

    • retainedContextCache

      private final PredictionContextCache retainedContextCache
      Retained prediction-context cache for ATN simulation. Cleared at the start of each execATN/computeStartState use so one simulator thread reuses map capacity without retaining stale contexts across predictions. Never shared across threads.

    • retainedPrecedenceAlt1

      private final ClearableIntObjectHashMap<PredictionContext> retainedPrecedenceAlt1
      Retained alt-1 context index for applyPrecedenceFilter(org.antlr.v4.runtime.atn.ATNConfigSet, org.antlr.v4.runtime.ParserRuleContext, org.antlr.v4.runtime.atn.PredictionContextCache). Empty clear is O(1); capacity is kept across precedence-DFA starts. Storage is a package-private primitive map (no third-party type on any public/protected signature).

    • STATE_ALT_SORT_COMPARATOR

      private static final Comparator<ATNConfig> STATE_ALT_SORT_COMPARATOR

  • Constructor Details

  • Method Details

    • getDfaForClosure

      @Nullable final DFA getDfaForClosure()
      Current DFA under construction during prediction, if any. Package-private for EpsilonClosure precedence-filter suppression.

    • epsilonClosure

      @NotNull final EpsilonClosure epsilonClosure()
      Package-private access to the epsilon-closure engine (same-package tests).

    • getPredictionMode

      @NotNull public final PredictionMode getPredictionMode()

    • setPredictionMode

      public final void setPredictionMode(@NotNull PredictionMode predictionMode)

    • reset

      public void reset()
      Specified by:
      reset in class ATNSimulator

    • adaptivePredict

      public int adaptivePredict(@NotNull TokenStream input, int decision, @Nullable ParserRuleContext outerContext)

    • adaptivePredict

      public int adaptivePredict(@NotNull TokenStream input, int decision, @Nullable ParserRuleContext outerContext, boolean useContext)

    • tryLL1Prediction

      private int tryLL1Prediction(TokenStream input, int decision)
      Single-token LL(1) cache probe against the dense ATN.ll1Dense table (no hash, no boxing). Subclass writes through ATN.LL1Table still update ATN.ll1Cache; the hot path never touches it.
      Returns:
      predicted alternative, or ATN.INVALID_ALT_NUMBER on miss

    • tryPrecedenceLL1

      private int tryPrecedenceLL1(TokenStream input, DFA dfa)
      Precedence LL(1) probe. The alternative depends on the parser's current precedence as well as LA(1), so it does not share ATN.ll1Dense.
      Returns:
      predicted alternative, or ATN.INVALID_ALT_NUMBER on miss

    • getStartState

      protected SimulatorState getStartState(@NotNull DFA dfa, @NotNull TokenStream input, @NotNull ParserRuleContext outerContext, boolean useContext)
      Local- or full-context DFA start, or null if it is not yet built. Returns a new SimulatorState (or null); never a recycled instance.

    • snapshotStartState

      protected boolean snapshotStartState()
      Whether adaptivePredict(org.antlr.v4.runtime.TokenStream, int, org.antlr.v4.runtime.ParserRuleContext) must call getStartState(org.antlr.v4.runtime.dfa.DFA, org.antlr.v4.runtime.TokenStream, org.antlr.v4.runtime.ParserRuleContext, boolean) so a subclass can observe the start snapshot. Production returns false and inlines the warm SLL DFA start.

    • execDFA

      protected int execDFA(@NotNull DFA dfa, @NotNull TokenStream input, int startIndex, @NotNull SimulatorState state)

    • execDFA

      private int execDFA(@NotNull DFA dfa, @NotNull TokenStream input, int startIndex, @NotNull ParserRuleContext outerContext, @NotNull DFAState s0, boolean useContext, ParserRuleContext remainingOuterContext)
      DFA walk. Private so the warm SLL path can pass locals without a SimulatorState allocation; the protected overload unpacks one.

    • isAcceptState

      protected boolean isAcceptState(DFAState state, boolean useContext)
      Determines if a particular DFA state should be treated as an accept state for the current prediction mode. In addition to the useContext parameter, the getPredictionMode() method provides the prediction mode controlling the prediction algorithm as a whole.

      The default implementation simply returns the value of DFAState.isAcceptState() except for conflict states when useContext is true and getPredictionMode() is PredictionMode.LL_EXACT_AMBIG_DETECTION. In that case, only conflict states where ATNConfigSet.isExactConflict() is true are considered accept states.

      Parameters:
      state - The DFA state to check.
      useContext - true if the prediction algorithm is currently considering the full parser context; otherwise, false if the algorithm is currently performing a local context prediction.
      Returns:
      true if the specified state is an accept state; otherwise, false.

    • execATN

      protected int execATN(@NotNull DFA dfa, @NotNull TokenStream input, int startIndex, @NotNull SimulatorState initialState)
      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? if in non-greedy decision is there a config at a rule stop state? 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 We should isolate those operations, which are side-effecting, to the main work loop. We can isolate lots of code into other functions, but they should be side effect free. They can return package that indicates whether we should report something, whether we need to add a DFA edge, whether we need to augment accept state with semantic context or rule invocation context. Actually, it seems like we always add predicates if they exist, so that can simply be done in the main loop for any accept state creation or modification request. cover these cases: dead end single alt single alt + preds conflict conflict + preds TODO: greedy + those

    • repeatedEof

      private static boolean repeatedEof(ArrayList<DFAState> states, ArrayList<ParserRuleContext> contexts, DFAState state, ParserRuleContext ctx, boolean useContext)
      Returns:
      true when this EOF step repeats a state the walk has already seen with the same remaining outer context. Full-context prediction reuses one DFA state after a context pop; that pop is progress, so the context object is part of the key. SLL passes useContext false and any repeat of the state is a cycle. Identity, not stateNumber: outermost states stay at -1 when the global-context DFA is disabled, and addDFAState then returns a new object on every reach. Those compare equal by configuration set.

    • handleNoViableAlt

      protected int handleNoViableAlt(@NotNull TokenStream input, int startIndex, @NotNull SimulatorState previous)
      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 ATNSimulator.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 no configuration in configs reached the end of the decision rule, return ATN.INVALID_ALT_NUMBER.
      • If all configurations in configs which reached the end of the decision rule predict the same alternative, return that alternative.
      • If the configurations in configs which reached the end of the decision rule predict multiple alternatives (call this S), choose an alternative in the following order.
        1. Filter the configurations in configs to only those configurations which remain viable after evaluating semantic predicates. If the set of these filtered configurations which also reached the end of the decision rule is not empty, return the minimum alternative represented in this set.
        2. Otherwise, choose the minimum alternative in S.

      In some scenarios, the algorithm described above could predict an alternative which will result in a FailedPredicateException in 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(org.antlr.v4.runtime.TokenStream, int, org.antlr.v4.runtime.ParserRuleContext) 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:
      input - The input TokenStream
      startIndex - The start index for the current prediction, which is the input index where any semantic context in configs should be evaluated
      previous - The ATN simulation state immediately before the ATNSimulator.ERROR state was reached
      Returns:
      The value to return from adaptivePredict(org.antlr.v4.runtime.TokenStream, int, org.antlr.v4.runtime.ParserRuleContext), or ATN.INVALID_ALT_NUMBER if a suitable alternative was not identified and adaptivePredict(org.antlr.v4.runtime.TokenStream, int, org.antlr.v4.runtime.ParserRuleContext) should report an error instead.

    • findFirstValidAltUsingPredicates

      private Integer findFirstValidAltUsingPredicates(TokenStream input, int startIndex, SimulatorState previous, BitSet alts, SemanticContext[] altToPred)

    • computeReachSet

      protected SimulatorState computeReachSet(DFA dfa, SimulatorState previous, int t, PredictionContextCache contextCache)

    • getExistingTargetState

      @Nullable protected DFAState getExistingTargetState(@NotNull DFAState s, int t)
      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:
      s - The current DFA state
      t - The next input symbol
      Returns:
      The existing target DFA state for the given input symbol t, or null if the target state for this edge is not already cached

    • computeTargetState

      @NotNull protected Tuple2<DFAState,ParserRuleContext> computeTargetState(@NotNull DFA dfa, @NotNull DFAState s, ParserRuleContext remainingGlobalContext, int t, boolean useContext, PredictionContextCache contextCache)
      Compute a target state for an edge in the DFA, and attempt to add the computed state and corresponding edge to the DFA.

      Delegates to package-private ReachComputation, which owns the retained reach / intermediate sets and the full-context config view.

      Parameters:
      dfa - the DFA owning this decision
      s - the current DFA state
      remainingGlobalContext - remaining full context, or null
      t - the next input symbol
      useContext - whether full-context prediction is active
      contextCache - prediction-context cache for this simulation
      Returns:
      The computed target DFA state for the given input symbol t. If t does not lead to a valid DFA state, this method returns ATNSimulator.ERROR.

    • retainedReachConfigs

      @NotNull final ReachConfigSource retainedReachConfigs()
      Retained ReachConfigSource after construction. Same-package tests may observe rewrite-list identity across full-context edges.

    • removeAllConfigsNotInRuleStopState

      @NotNull protected ATNConfigSet removeAllConfigsNotInRuleStopState(@NotNull ATNConfigSet configs, PredictionContextCache contextCache)
      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.
      Parameters:
      configs - the configuration set to update
      contextCache - the PredictionContext cache
      Returns:
      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

    • computeStartState

      @NotNull protected SimulatorState computeStartState(DFA dfa, ParserRuleContext globalContext, boolean useContext)

    • applyPrecedenceFilter

      @NotNull protected ATNConfigSet applyPrecedenceFilter(@NotNull ATNConfigSet configs, ParserRuleContext globalContext, PredictionContextCache contextCache)
      This method transforms the start state computed by computeStartState(org.antlr.v4.runtime.dfa.DFA, org.antlr.v4.runtime.ParserRuleContext, boolean) 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(org.antlr.v4.runtime.Recognizer<?, ?>, org.antlr.v4.runtime.RuleContext).
      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.

      Alt-1 prediction contexts are indexed by ATN state number in a retained primitive int-keyed map (implementation detail of this method only) so filtering of higher alternatives avoids Integer boxing on each state-number lookup. The protected signature uses only JDK and ANTLR types.

      Parameters:
      configs - The configuration set computed by computeStartState(org.antlr.v4.runtime.dfa.DFA, org.antlr.v4.runtime.ParserRuleContext, boolean) as the start state for the DFA.
      Returns:
      The transformed configuration set representing the start state for a precedence DFA at a particular precedence level (determined by calling Parser.getPrecedence()).

    • obtainContextCache

      @NotNull private PredictionContextCache obtainContextCache()
      Returns the retained prediction-context cache after clearing it. One simulator owns the cache for the duration of a single ATN simulation.

    • getReachableTarget

      @Nullable protected ATNState getReachableTarget(@NotNull ATNConfig source, @NotNull Transition trans, int ttype)

    • predicateDFAState

      protected DFAState.PredPrediction[] predicateDFAState(DFAState D, ATNConfigSet configs, int nalts)
      collect and set D's semantic context

    • getPredsForAmbigAlts

      protected SemanticContext[] getPredsForAmbigAlts(@NotNull BitSet ambigAlts, @NotNull ATNConfigSet configs, int nalts)

    • getPredicatePredictions

      protected DFAState.PredPrediction[] getPredicatePredictions(BitSet ambigAlts, SemanticContext[] altToPred)

    • evalSemanticContext

      protected BitSet evalSemanticContext(@NotNull DFAState.PredPrediction[] predPredictions, ParserRuleContext outerContext, boolean complete)
      Look through a list of predicate/alt pairs, returning alts for the pairs that win. A null predicate indicates an alt containing an unpredicated config which behaves as "always true."

    • evalSemanticContext

      protected boolean evalSemanticContext(@NotNull SemanticContext pred, ParserRuleContext parserCallStack, int alt)
      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 - The semantic context to evaluate
      parserCallStack - The parser context in which to evaluate the semantic context
      alt - The alternative which is guarded by pred
      Since:
      4.3

    • closure

      protected void closure(ATNConfigSet sourceConfigs, @NotNull ATNConfigSet configs, boolean collectPredicates, boolean hasMoreContext, @Nullable PredictionContextCache contextCache, boolean treatEofAsEpsilon)
      Compute the epsilon closure of every configuration in sourceConfigs, adding the resulting non-epsilon (or EOF-as-epsilon) configurations to configs.

      Delegates to EpsilonClosure for busy-set sizing, predicate vs BFS control split, and double-buffered intermediate layers. Subclasses may override this method or the recursive single-config closure(ATNConfig, ...) entry point.

      Parameters:
      sourceConfigs - configurations from which to start the closure
      configs - destination set that receives closed configurations
      collectPredicates - whether semantic predicates should be collected into configuration semantic contexts (start-state construction) or ignored for DFA edge computation
      hasMoreContext - whether outer/global context remains available when a configuration falls off the end of a rule
      contextCache - prediction-context cache for the current prediction, or null to use PredictionContextCache.UNCACHED
      treatEofAsEpsilon - whether EOF-matching atom/range/set transitions should be treated as epsilon edges

    • closure

      protected void closure(@NotNull ATNConfig config, @NotNull ATNConfigSet configs, @Nullable ATNConfigSet intermediate, @NotNull Set<ATNConfig> closureBusy, boolean collectPredicates, boolean hasMoreContexts, @NotNull PredictionContextCache contextCache, int depth, boolean treatEofAsEpsilon)
      Recursive helper for closure(ATNConfigSet, ATNConfigSet, boolean, boolean, PredictionContextCache, boolean). Walks epsilon edges from config, adding leaf configurations to configs and optionally deferring rule transitions to intermediate for breadth-first processing.

      Default implementation delegates to EpsilonClosure. Subclasses may override to customize edge walking.

      PERF: Production callers pass the retained busy Set owned by EpsilonClosure (an OpenAddressedHashSet wrapping an open-addressed HPPC table) so right-recursion / EOF* guards avoid per-insert java.util.HashMap.Node<K extends Object,V extends Object> allocation. The parameter is typed as Set so this protected SPI never exposes HPPC types; subclasses may supply any Set implementation. Callers outside the closure engine should not allocate a fresh set per config.

      Parameters:
      closureBusy - busy set for right-recursion / EOF* cycle guards; Set.add(E) must return false when an equal config is already present

    • getRuleName

      @NotNull public String getRuleName(int index)

    • getEpsilonTarget

      @Nullable protected ATNConfig getEpsilonTarget(@NotNull ATNConfig config, @NotNull Transition t, boolean collectPredicates, boolean inContext, PredictionContextCache contextCache, boolean treatEofAsEpsilon)
      Compute the target configuration after traversing epsilon transition t from config, or null if t is not an epsilon (or EOF-as-epsilon) edge applicable in the current mode.

      PERF: The switch is ordered with the most common epsilon edge types (Transition.EPSILON, Transition.RULE) first so the interpreter/JIT can keep those paths monomorphic and hot.

    • actionTransition

      @NotNull protected ATNConfig actionTransition(@NotNull ATNConfig config, @NotNull ActionTransition t)

    • precedenceTransition

      @Nullable protected ATNConfig precedenceTransition(@NotNull ATNConfig config, @NotNull PrecedencePredicateTransition pt, boolean collectPredicates, boolean inContext)

    • predTransition

      @Nullable protected ATNConfig predTransition(@NotNull ATNConfig config, @NotNull PredicateTransition pt, boolean collectPredicates, boolean inContext)

    • ruleTransition

      @NotNull protected ATNConfig ruleTransition(@NotNull ATNConfig config, @NotNull RuleTransition t, @Nullable PredictionContextCache contextCache)
      Build the configuration that results from traversing rule transition t from config.

      PERF: Tail-call elimination reuses config's prediction context when enabled. Otherwise the child context is obtained through contextCache so repeated rule invocations share interned PredictionContext nodes.

    • isConflicted

      private ConflictInfo isConflicted(@NotNull ATNConfigSet configset, PredictionContextCache contextCache)

    • getConflictingAltsFromConfigSet

      protected BitSet getConflictingAltsFromConfigSet(ATNConfigSet configs)

    • getTokenName

      @NotNull public String getTokenName(int t)

    • getLookaheadName

      public String getLookaheadName(TokenStream input)

    • dumpDeadEndConfigs

      public void dumpDeadEndConfigs(@NotNull NoViableAltException nvae)

    • noViableAlt

      @NotNull protected NoViableAltException noViableAlt(@NotNull TokenStream input, @NotNull ParserRuleContext outerContext, @NotNull ATNConfigSet configs, int startIndex)

    • getUniqueAlt

      protected int getUniqueAlt(@NotNull Collection<ATNConfig> configs)

    • configWithAltAtStopState

      protected boolean configWithAltAtStopState(@NotNull Collection<ATNConfig> configs, int alt)

    • addDFAEdge

      @NotNull protected DFAState addDFAEdge(@NotNull DFA dfa, @NotNull DFAState fromState, int t, IntegerList contextTransitions, @NotNull ATNConfigSet toConfigs, PredictionContextCache contextCache)

    • addDFAEdge

      protected void addDFAEdge(@Nullable DFAState p, int t, @Nullable DFAState q)

    • addDFAContextState

      @NotNull protected DFAState addDFAContextState(@NotNull DFA dfa, @NotNull ATNConfigSet configs, int returnContext, PredictionContextCache contextCache)
      See comment on LexerInterpreter.addDFAState.

    • addDFAState

      @NotNull protected DFAState addDFAState(@NotNull DFA dfa, @NotNull ATNConfigSet configs, PredictionContextCache contextCache)
      See comment on LexerInterpreter.addDFAState.

    • createDFAState

      @NotNull protected DFAState createDFAState(@NotNull DFA dfa, @NotNull ATNConfigSet configs)

    • reportAttemptingFullContext

      protected void reportAttemptingFullContext(@NotNull DFA dfa, @Nullable BitSet conflictingAlts, @NotNull SimulatorState conflictState, int startIndex, int stopIndex)

    • reportContextSensitivity

      protected void reportContextSensitivity(@NotNull DFA dfa, int prediction, @NotNull SimulatorState acceptState, int startIndex, int stopIndex)

    • reportAmbiguity

      protected void reportAmbiguity(@NotNull DFA dfa, DFAState D, int startIndex, int stopIndex, boolean exact, @NotNull BitSet ambigAlts, @NotNull ATNConfigSet configs)
      If context sensitive parsing, we know it's ambiguity not conflict

    • getReturnState

      protected final int getReturnState(RuleContext context)

    • skipTailCalls

      protected final ParserRuleContext skipTailCalls(ParserRuleContext context)

    • getParser

      public Parser getParser()
      Since:
      4.3