org.antlr.v4.runtime.tree.pattern

Class ParseTreePatternMatcher

java.lang.Object

org.antlr.v4.runtime.tree.pattern.ParseTreePatternMatcher

public class ParseTreePatternMatcher
extends java.lang.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 java.lang.String	escape
protected java.lang.String	start
protected java.lang.String	stop

Constructor Summary

Constructors

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

Method Summary

Methods

Modifier and Type	Method and Description
ParseTreePattern	compile(java.lang.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, java.lang.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, java.lang.String pattern, int patternRuleIndex) Does pattern matched as rule patternRuleIndex match tree?
protected ParseTree	matchImpl(ParseTree tree, ParseTree patternTree, MultiMap<java.lang.String,ParseTree> labels) Recursively walk tree against patternTree, filling match.labels.
void	setDelimiters(java.lang.String start, java.lang.String stop, java.lang.String escapeLeft) Set the delimiters used for marking rule and token tags within concrete syntax used by the tree pattern parser.
java.util.List<org.antlr.v4.runtime.tree.pattern.Chunk>	split(java.lang.String pattern) Split <ID> = <e:expr> ; into 4 chunks for tokenizing by tokenize(java.lang.String).
java.util.List<? extends Token>	tokenize(java.lang.String pattern)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

start

protected java.lang.String start

stop

protected java.lang.String stop

escape

protected java.lang.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(java.lang.String start,
                 java.lang.String stop,
                 java.lang.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:

java.lang.IllegalArgumentException - if start is null or empty.

java.lang.IllegalArgumentException - if stop is null or empty.

matches

public boolean matches(ParseTree tree,
              java.lang.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,
                   java.lang.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(java.lang.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<java.lang.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 java.util.List<? extends Token> tokenize(java.lang.String pattern)

split

public java.util.List<org.antlr.v4.runtime.tree.pattern.Chunk> split(java.lang.String pattern)

Split <ID> = <e:expr> ; into 4 chunks for tokenizing by tokenize(java.lang.String).