ParseTreePatternMatcher (ANTLR 4 Runtime 4.6 API)

java.lang.Object
- org.antlr.v4.runtime.tree.pattern.ParseTreePatternMatcher

```
public class ParseTreePatternMatcher
extends Object
```
A tree pattern matching mechanism for ANTLR ParseTrees.
Patterns are strings of source input text with special tags representing token or rule references such as:

<ID> = <expr>;

Given a pattern start rule such as statement, this object constructs a ParseTree with placeholders for the ID and expr subtree. Then the match(org.antlr.v4.runtime.tree.ParseTree, java.lang.String, int) routines can compare an actual ParseTree from a parse with this pattern. Tag <ID> matches any ID token and tag <expr> references the result of the expr rule (generally an instance of ExprContext.

Pattern x = 0; is a similar pattern that matches the same pattern except that it requires the identifier to be x and the expression to be 0.

The matches(org.antlr.v4.runtime.tree.ParseTree, java.lang.String, int) routines return true or false based upon a match for the tree rooted at the parameter sent in. The match(org.antlr.v4.runtime.tree.ParseTree, java.lang.String, int) routines return a ParseTreeMatch object that contains the parse tree, the parse tree pattern, and a map from tag name to matched nodes (more below). A subtree that fails to match, returns with ParseTreeMatch.mismatchedNode set to the first tree node that did not match.

For efficiency, you can compile a tree pattern in string form to a ParseTreePattern object.

See TestParseTreeMatcher for lots of examples. ParseTreePattern has two static helper methods: ParseTreePattern.findAll(org.antlr.v4.runtime.tree.ParseTree, java.lang.String) and ParseTreePattern.match(org.antlr.v4.runtime.tree.ParseTree) that are easy to use but not super efficient because they create new ParseTreePatternMatcher objects each time and have to compile the pattern in string form before using it.

The lexer and parser that you pass into the ParseTreePatternMatcher constructor are used to parse the pattern in string form. The lexer converts the <ID> = <expr>; into a sequence of four tokens (assuming lexer throws out whitespace or puts it on a hidden channel). Be aware that the input stream is reset for the lexer (but not the parser; a ParserInterpreter is created to parse the input.). Any user-defined fields you have put into the lexer might get changed when this mechanism asks it to scan the pattern string.

Normally a parser does not accept token <expr> as a valid expr but, from the parser passed in, we create a special version of the underlying grammar representation (an ATN) that allows imaginary tokens representing rules (<expr>) to match entire rules. We call these bypass alternatives.

Delimiters are < and >, with \ as the escape string by default, but you can set them to whatever you want using setDelimiters(java.lang.String, java.lang.String, java.lang.String). You must escape both start and stop strings \< and \>.

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`ParseTreePatternMatcher.CannotInvokeStartRule`
`static class`	`ParseTreePatternMatcher.StartRuleDoesNotConsumeFullPattern`

Field Summary

Fields
Modifier and Type Field and Description

protected String escape

protected String start

protected String stop

Fields
Modifier and Type	Field and Description
`protected String`	`escape`
`protected String`	`start`
`protected String`	`stop`

Constructor Summary

Constructors
Constructor and Description

ParseTreePatternMatcher(Lexer lexer, Parser parser)
Constructs a ParseTreePatternMatcher or from a Lexer and Parser object.

Constructors
Constructor and Description
`ParseTreePatternMatcher(Lexer lexer, Parser parser)` Constructs a `ParseTreePatternMatcher` or from a `Lexer` and `Parser` object.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`ParseTreePattern`	`compile(String pattern, int patternRuleIndex)` For repeated use of a tree pattern, compile it to a `ParseTreePattern` using this method.
`Lexer`	`getLexer()` Used to convert the tree pattern string into a series of tokens.
`Parser`	`getParser()` Used to collect to the grammar file name, token names, rule names for used to parse the pattern into a parse tree.
`protected RuleTagToken`	`getRuleTagToken(ParseTree t)` Is `t` `(expr <expr>)` subtree?
`ParseTreeMatch`	`match(ParseTree tree, ParseTreePattern pattern)` Compare `pattern` matched against `tree` and return a `ParseTreeMatch` object that contains the matched elements, or the node at which the match failed.
`ParseTreeMatch`	`match(ParseTree tree, String pattern, int patternRuleIndex)` Compare `pattern` matched as rule `patternRuleIndex` against `tree` and return a `ParseTreeMatch` object that contains the matched elements, or the node at which the match failed.
`boolean`	`matches(ParseTree tree, ParseTreePattern pattern)` Does `pattern` matched as rule patternRuleIndex match tree? Pass in a compiled pattern instead of a string representation of a tree pattern.
`boolean`	`matches(ParseTree tree, String pattern, int patternRuleIndex)` Does `pattern` matched as rule `patternRuleIndex` match `tree`?
`protected ParseTree`	`matchImpl(ParseTree tree, ParseTree patternTree, MultiMap<String,ParseTree> labels)` Recursively walk `tree` against `patternTree`, filling `match.labels`.
`void`	`setDelimiters(String start, String stop, String escapeLeft)` Set the delimiters used for marking rule and token tags within concrete syntax used by the tree pattern parser.
`List<org.antlr.v4.runtime.tree.pattern.Chunk>`	`split(String pattern)` Split `<ID> = <e:expr> ;` into 4 chunks for tokenizing by `tokenize(java.lang.String)`.
`List<? extends Token>`	`tokenize(String pattern)`

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - start
```
protected String start
```
  - stop
```
protected String stop
```
  - escape
```
protected String escape
```
- Constructor Detail
  - ParseTreePatternMatcher
```
public ParseTreePatternMatcher(Lexer lexer,
                               Parser parser)
```
    Constructs a ParseTreePatternMatcher or from a Lexer and Parser object. The lexer input stream is altered for tokenizing the tree patterns. The parser is used as a convenient mechanism to get the grammar name, plus token, rule names.
- Method Detail
  - setDelimiters
```
public void setDelimiters(String start,
                          String stop,
                          String escapeLeft)
```
    Set the delimiters used for marking rule and token tags within concrete syntax used by the tree pattern parser.
    
    Parameters:
    
    start - The start delimiter.
    
    stop - The stop delimiter.
    
    escapeLeft - The escape sequence to use for escaping a start or stop delimiter.
    
    Throws:
    
    IllegalArgumentException - if start is null or empty.
    
    IllegalArgumentException - if stop is null or empty.
  - matches
```
public boolean matches(ParseTree tree,
                       String pattern,
                       int patternRuleIndex)
```
    Does pattern matched as rule patternRuleIndex match tree?
  - matches
```
public boolean matches(ParseTree tree,
                       ParseTreePattern pattern)
```
    Does pattern matched as rule patternRuleIndex match tree? Pass in a compiled pattern instead of a string representation of a tree pattern.
  - match
```
public ParseTreeMatch match(ParseTree tree,
                            String pattern,
                            int patternRuleIndex)
```
    Compare pattern matched as rule patternRuleIndex against tree and return a ParseTreeMatch object that contains the matched elements, or the node at which the match failed.
  - match
```
public ParseTreeMatch match(ParseTree tree,
                            ParseTreePattern pattern)
```
    Compare pattern matched against tree and return a ParseTreeMatch object that contains the matched elements, or the node at which the match failed. Pass in a compiled pattern instead of a string representation of a tree pattern.
  - compile
```
public ParseTreePattern compile(String pattern,
                                int patternRuleIndex)
```
    For repeated use of a tree pattern, compile it to a ParseTreePattern using this method.
  - getLexer
```
public Lexer getLexer()
```
    Used to convert the tree pattern string into a series of tokens. The input stream is reset.
  - getParser
```
public Parser getParser()
```
    Used to collect to the grammar file name, token names, rule names for used to parse the pattern into a parse tree.
  - matchImpl
```
protected ParseTree matchImpl(ParseTree tree,
                              ParseTree patternTree,
                              MultiMap<String,ParseTree> labels)
```
    Recursively walk tree against patternTree, filling match.labels.
    
    Returns:
    
    the first node encountered in tree which does not match a corresponding node in patternTree, or null if the match was successful. The specific node returned depends on the matching algorithm used by the implementation, and may be overridden.
  - getRuleTagToken
```
protected RuleTagToken getRuleTagToken(ParseTree t)
```
    Is t (expr <expr>) subtree?
  - tokenize
```
public List<? extends Token> tokenize(String pattern)
```
  - split
```
public List<org.antlr.v4.runtime.tree.pattern.Chunk> split(String pattern)
```
    Split <ID> = <e:expr> ; into 4 chunks for tokenizing by tokenize(java.lang.String).

Class ParseTreePatternMatcher

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

start

stop

escape

Constructor Detail

ParseTreePatternMatcher

Method Detail

setDelimiters

matches

matches

match

match

compile

getLexer

getParser

matchImpl

getRuleTagToken

tokenize

split