This event may be reported during SLL prediction in cases where the conflicting SLL configuration set provides sufficient information to determine that the SLL conflict is truly an ambiguity. For example, if none of the ATN configurations in the conflicting SLL configuration set have traversed a global follow transition (i.e. is for all configurations), then the result of SLL prediction for that input is known to be equivalent to the result of LL prediction for that input.

In some cases, the minimum represented alternative in the conflicting LL configuration set is not equal to the minimum represented alternative in the conflicting SLL configuration set. Grammars and inputs which result in this scenario are unable to use , which in turn means they cannot use the two-stage parsing strategy to improve parsing performance for that input.

For the prediction mode, accept states are conflicting but not exact are treated as non-accept states.

In some cases, the unique alternative identified by LL prediction is not equal to the minimum represented alternative in the conflicting SLL configuration set. Grammars and inputs which result in this scenario are unable to use , which in turn means they cannot use the two-stage parsing strategy to improve parsing performance for that input.

Parsing performance in ANTLR 4 is heavily influenced by both static factors (e.g. the form of the rules in the grammar) and dynamic factors (e.g. the choice of input and the state of the DFA cache at the time profiling operations are started). For best results, gather and use aggregate statistics from a large sample of inputs representing the inputs expected in production before using the results to make changes in the grammar.

The executor tracks position information for position-dependent lexer actions efficiently, ensuring that actions appearing only at the end of the rule do not cause bloating of the created for the lexer.

When using this prediction mode, the parser will either return a correct parse tree (i.e. the same parse tree that would be returned with the prediction mode), or it will report a syntax error. If a syntax error is encountered when using the prediction mode, it may be due to either an actual syntax error in the input or indicate that the particular combination of grammar and input requires the more powerful prediction abilities to complete successfully.

This prediction mode does not provide any guarantees for prediction behavior for syntactically-incorrect inputs.

When using this prediction mode, the parser will make correct decisions for all syntactically-correct grammar and input combinations. However, in cases where the grammar is truly ambiguous this prediction mode might not report a precise answer for exactly which alternatives are ambiguous.

This prediction mode does not provide any guarantees for prediction behavior for syntactically-incorrect inputs.

This method computes the SLL prediction termination condition for both of the following cases.

• The usual SLL+LL fallback upon SLL conflict
• Pure SLL without LL fallback

COMBINED SLL+LL PARSING

When LL-fallback is enabled upon SLL conflict, correct predictions are ensured regardless of how the termination condition is computed by this method. Due to the substantially higher cost of LL prediction, the prediction should only fall back to LL when the additional lookahead cannot lead to a unique SLL prediction.

Assuming combined SLL+LL parsing, an SLL configuration set with only conflicting subsets should fall back to full LL, even if the configuration sets don't resolve to the same alternative (e.g. 1,2}} and 3,4}}. If there is at least one non-conflicting configuration, SLL could continue with the hopes that more lookahead will resolve via one of those non-conflicting configurations.

Here's the prediction termination rule them: SLL (for SLL+LL parsing) stops when it sees only conflicting configuration subsets. In contrast, full LL keeps going when there is uncertainty.

HEURISTIC

As a heuristic, we stop prediction when we see any conflicting subset unless we see a state that only has one alternative associated with it. The single-alt-state thing lets prediction continue upon rules like (otherwise, it would admit defeat too soon):

[12|1|[], 6|2|[], 12|2|[]]. 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|[]] .

It also let's us continue for this rule:

[1|1|[], 1|2|[], 8|3|[]] 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, don't declare the state done.

PURE SLL PARSING

To handle pure SLL parsing, all we have to do is make sure that we combine stack contexts for configurations that differ only by semantic predicate. From there, we can do the usual SLL termination heuristic.

PREDICATES IN SLL+LL PARSING

SLL decisions don't evaluate predicates until after they reach DFA stop states because they need to create the DFA cache that works in all semantic situations. In contrast, full LL evaluates predicates collected during start state computation so it can ignore predicates thereafter. This means that SLL termination detection can totally ignore semantic predicates.

Implementation-wise, combines stack contexts but not semantic predicate contexts so we might see two configurations like the following.

(s, 1, x, ), (s, 1, x', {p})}

Before testing these configurations against others, we have to merge x and x' (without modifying the existing configurations). For example, we test (x+x')==x'' when looking for conflicts in the following configurations.

(s, 1, x, ), (s, 1, x', {p}), (s, 2, x'', {})}

If the configuration set has predicates (as indicated by ), this algorithm makes a copy of the configurations to strip out all of the predicates so that a standard will merge everything ignoring predicates.

Can we stop looking ahead during ATN simulation or is there some uncertainty as to which alternative we will ultimately pick, after consuming more input? Even if there are partial conflicts, we might know that everything is going to resolve to the same minimum alternative. That means we can stop since no more lookahead will change that fact. On the other hand, there might be multiple conflicts that resolve to different minimums. That means we need more look ahead to decide which of those alternatives we should predict.

The basic idea is to split the set of configurations C , into conflicting subsets (s, _, ctx, _) and singleton subsets with non-conflicting configurations. Two configurations conflict if they have identical and values but different value, e.g. (s, i, ctx, _) and (s, j, ctx, _) for i!=j .

Reduce these configuration subsets to the set of possible alternatives. You can compute the alternative subsets in one pass as follows:

A_s,ctx = i | (s, i, ctx, _)}} for each configuration in C holding s and ctx fixed.

Or in pseudo-code, for each configuration c in C :

             map[c] U= c.
             getAlt()
             # map hash/equals uses s and x, not
             alt and not pred
             

The values in map are the set of A_s,ctx sets.

If |A_s,ctx|=1 then there is no conflict associated with s and ctx .

Reduce the subsets to singletons by choosing a minimum of each subset. If the union of these alternative subsets is a singleton, then no amount of more lookahead will help us. We will always pick that alternative. If, however, there is more than one alternative, then we are uncertain which alternative to predict and must continue looking for resolution. We may or may not discover an ambiguity in the future, even if there are no conflicting subsets this round.

The biggest sin is to terminate early because it means we've made a decision but were uncertain as to the eventual outcome. We haven't used enough lookahead. On the other hand, announcing a conflict too late is no big deal; you will still have the conflict. It's just inefficient. It might even look until the end of file.

No special consideration for semantic predicates is required because predicates are evaluated on-the-fly for full LL prediction, ensuring that no configuration contains a semantic context during the termination check.

CONFLICTING CONFIGS

Two configurations (s, i, x) and (s, j, x') , conflict when i!=j but x=x' . Because we merge all (s, i, _) configurations together, that means that there are at most n configurations associated with state s for n possible alternatives in the decision. The merged stacks complicate the comparison of configuration contexts x and x' . Sam checks to see if one is a subset of the other by calling merge and checking to see if the merged result is either x or x' . If the x associated with lowest alternative i is the superset, then i is the only possible prediction since the others resolve to min(i) as well. However, if x is associated with j>i then at least one stack configuration for j is not in conflict with alternative i . The algorithm should keep going, looking for more lookahead due to the uncertainty.

For simplicity, I'm doing a equality check between x and x' that lets the algorithm continue to consume lookahead longer than necessary. The reason I like the equality is of course the simplicity but also because that is the test you need to detect the alternatives that are actually in conflict.

CONTINUE/STOP RULE

Continue if union of resolved alternative sets from non-conflicting and conflicting alternative subsets has more than one alternative. We are uncertain about which alternative to predict.

The complete set of alternatives, [i for (_,i,_)] , tells us which alternatives are still in the running for the amount of input we've consumed at this point. The conflicting sets let us to strip away configurations that won't lead to more states because we resolve conflicts to the configuration with a minimum alternate for the conflicting set.

CASES

• no conflicts and more than 1 alternative in set => continue
• (s, 1, x) , (s, 2, x) , (s, 3, z) , (s', 1, y) , (s', 2, y) yields non-conflicting set 3}} U conflicting sets min( 1,2})} U min( 1,2})} = 1,3}} => continue
• (s, 1, x) , (s, 2, x) , (s', 1, y) , (s', 2, y) , (s'', 1, z) yields non-conflicting set 1}} U conflicting sets min( 1,2})} U min( 1,2})} = 1}} => stop and predict 1
• (s, 1, x) , (s, 2, x) , (s', 1, y) , (s', 2, y) yields conflicting, reduced sets 1}} U 1}} = 1}} => stop and predict 1, can announce ambiguity 1,2}}
• (s, 1, x) , (s, 2, x) , (s', 2, y) , (s', 3, y) yields conflicting, reduced sets 1}} U 2}} = 1,2}} => continue
• (s, 1, x) , (s, 2, x) , (s', 3, y) , (s', 4, y) yields conflicting, reduced sets 1}} U 3}} = 1,3}} => continue

EXACT AMBIGUITY DETECTION

If all states report the same conflicting set of alternatives, then we know we have the exact ambiguity set.

|A_i|>1 and A_i = A_j for all i, j.

In other words, we continue examining lookahead until all A_i have more than one alternative and all A_i are the same. If A= {1,2}, {1,3}}}, then regular LL prediction would terminate because the resolved set is 1}}. To determine what the real ambiguity is, we have to know whether the ambiguity is between one and two or one and three so we keep going. We can only stop prediction when we need exact ambiguity detection when the sets look like A= {1,2}}} or {1,2},{1,2}}}, etc...

This is a computed property that is calculated during ATN deserialization and stored for use in and .

This is a one way link. It emanates from a state (usually via a list of transitions) and has a target state.

Since we never have to change the ATN transitions once we construct it, we can fix these transitions as specific classes. The DFA transitions on the other hand need to update the labels as it adds transitions to the states. We'll use the term Edge for the DFA to distinguish them from ATN transitions.

The default implementation returns .

The default value is , which matches the default channel assigned to tokens created by the lexer.

I use a set of ATNConfig objects not simple states. An ATNConfig is both a state (ala normal conversion) and a RuleContext describing the chain of rules (if any) followed to arrive at that state.

A DFA state may have multiple references to a particular state, but with different ATN contexts (with same or different alts) meaning that state was reached via a different set of rule invocations.

• The parser could not figure out which path to take in the ATN (none of the available alternatives could possibly match)
• The current input does not match what we were looking for
• A predicate evaluated to false

• Forward movement: The value of index() before calling this method is less than the value of index() after calling this method.
• Ordered lookahead: The value of LA(1) before calling this method becomes the value of LA(-1) after calling this method.

Each full-context prediction which does not result in a syntax error will call either or .

When is not null, it contains the set of potentially viable alternatives identified by the prediction algorithm. When is null, use to obtain the represented alternatives from the argument.

When is , all of the potentially viable alternatives are truly viable, i.e. this is reporting an exact ambiguity. When is , at least two of the potentially viable alternatives are viable for the current input, but the prediction algorithm terminated as soon as it determined that at least the minimum potentially viable alternative is truly viable.

When the prediction mode is used, the parser is required to identify exact ambiguities so will always be .

If one or more configurations in configs contains a semantic predicate, the predicates are evaluated before this method is called. The subset of alternatives which are still viable after predicates are evaluated is reported in .

Each full-context prediction which does not result in a syntax error will call either or .

For prediction implementations that only evaluate full-context predictions when an SLL conflict is found (including the default implementation), this method reports cases where SLL conflicts were resolved to unique full-context predictions, i.e. the decision was context-sensitive. This report does not necessarily indicate a problem, and it may appear even in completely unambiguous grammars.

configs may have more than one represented alternative if the full-context prediction algorithm does not evaluate predicates before beginning the full-context prediction. In all cases, the final prediction is passed as the argument.

Note that the definition of "context sensitivity" in this method differs from the concept in . This method reports all instances where an SLL conflict occurred but LL parsing produced a unique result, whether or not that unique result matches the minimum alternative in the SLL conflicting set.

The non-negative numbers less than are assigned to the predefined channels and .

ANTLR provides a default implementation of this method, but applications are free to override the behavior in any manner which makes sense for the application. The default implementation returns the first result from the following list which produces a non- result.

1. The result of
2. The result of
3. The result of

            ParseTree t = parser.expr();
            ParseTreePattern p = parser.compileParseTreePattern("<ID>+0", MyParser.RULE_expr);
            ParseTreeMatch m = p.match(t);
            String id = m.get("ID");
            

If the set of expected tokens is not known and could not be computed, this method returns .

If the input stream is not available, this method returns .

Used for XPath and tree pattern compilation.

Used for XPath and tree pattern compilation.

For interpreters, we don't know their serialized ATN despite having created the interpreter from it.

Since tokens on hidden channels (e.g. whitespace or comments) are not added to the parse trees, they will not appear in the output of this method.

You can insert stuff, replace, and delete chunks. Note that the operations are done lazily--only if you convert the buffer to a with . This is very efficient because you are not moving data around all the time. As the buffer of tokens is converted to strings, the method(s) scan the input token stream and check to see if there is an operation at the current index. If so, the operation is done and then normal rendering continues on the buffer. This is like having multiple Turing machine instruction streams (programs) operating on a single input tape. :)

This rewriter makes no modifications to the token stream. It does not ask the stream to fill itself up nor does it advance the input cursor. The token stream will return the same value before and after any call.

The rewriter only works on tokens that you have in the buffer and ignores the current input cursor. If you are buffering tokens on-demand, calling halfway through the input will only do rewrites for those tokens in the first half of the file.

Since the operations are done lazily at -time, operations do not screw up the token index values. That is, an insert operation at token index i does not change the index values for tokens i +1..n-1.

Because operations never actually alter the buffer, you may always get the original token stream back without undoing anything. Since the instructions are queued up, you can easily simulate transactions and roll back any changes if there is an error just by removing instructions. For example,

            CharStream input = new ANTLRFileStream("input");
            TLexer lex = new TLexer(input);
            CommonTokenStream tokens = new CommonTokenStream(lex);
            T parser = new T(tokens);
            TokenStreamRewriter rewriter = new TokenStreamRewriter(tokens);
            parser.startRule();
            

Then in the rules, you can execute (assuming rewriter is visible):

            Token t,u;
            ...
            rewriter.insertAfter(t, "text to put after t");}
            rewriter.insertAfter(u, "text after u");}
            System.out.println(tokens.toString());
            

You can also have multiple "instruction streams" and get multiple rewrites from a single pass over the input. Just name the instruction streams and use that name again when printing the buffer. This could be useful for generating a C file and also its header file--all from the same buffer:

            tokens.insertAfter("pass1", t, "text to put after t");}
            tokens.insertAfter("pass2", u, "text after u");}
            System.out.println(tokens.toString("pass1"));
            System.out.println(tokens.toString("pass2"));
            

If you don't use named rewrite streams, a "default" stream is used as the first example shows.

The base implementation returns .

            ParseTreeProperty<Integer> values = new ParseTreeProperty<Integer>();
            values.put(tree, 36);
            int x = values.get(tree);
            values.removeFrom(tree);
            

The method returns a list of chunks in preparation for creating a token stream by . From there, we get a parse tree from with . These chunks are converted to , , or the regular tokens of the text surrounding the tags.

If the is the name of a parser rule or token in the grammar, the resulting list will contain both the parse trees matching rule or tags explicitly labeled with the label and the complete set of parse trees matching the labeled and unlabeled tags in the pattern for the parser rule or token. For example, if is "foo" , the result will contain all of the following.

• Parse tree nodes matching tags of the form <foo:anyRuleName> and <foo:AnyTokenName> .
• Parse tree nodes matching tags of the form <anyLabel:foo> .
• Parse tree nodes matching tags of the form <foo> .

The map includes special entries corresponding to the names of rules and tokens referenced in tags in the original pattern. For additional information, see the description of .

• expr : An unlabeled placeholder for a parser rule expr .
• ID : An unlabeled placeholder for a token of type ID .
• e:expr : A labeled placeholder for a parser rule expr .
• id:ID : A labeled placeholder for a token of type ID .

Split path into words and separators / and // via ANTLR itself then walk path elements from left to right. At each separator-word pair, find set of nodes. Next stage uses those as work list.

The basic interface is ParseTree.findAll (tree, pathString, parser) . But that is just shorthand for:

            
            p = new
            XPath
            (parser, pathString);
            return p.
            evaluate
            (tree);
            

See org.antlr.v4.test.TestXPath for descriptions. In short, this allows operators:

/

root

//

anywhere

!

invert; this must appear directly after root or anywhere operator

and path elements:

ID

token name

'string'

any string literal token from the grammar

expr

rule name

*

wildcard matching any node

Whitespace is not allowed.

The specific marker value used for this class allows for some level of protection against misuse where seek() is called on a mark or release() is called in the wrong order.

This value is used to set the token indexes if the stream provides tokens that implement .

The specific marker value used for this class allows for some level of protection against misuse where seek() is called on a mark or release() is called in the wrong order.