Class ParseTreePatternMatcher
- java.lang.Object
-
- org.antlr.v4.runtime.tree.pattern.ParseTreePatternMatcher
-
public class ParseTreePatternMatcher extends Object
A tree pattern matching mechanism for ANTLRParseTree
s.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 aParseTree
with placeholders for theID
andexpr
subtree. Then thematch(org.antlr.v4.runtime.tree.ParseTree, java.lang.String, int)
routines can compare an actualParseTree
from a parse with this pattern. Tag<ID>
matches anyID
token and tag<expr>
references the result of theexpr
rule (generally an instance ofExprContext
.Pattern
x = 0;
is a similar pattern that matches the same pattern except that it requires the identifier to bex
and the expression to be0
.The
matches(org.antlr.v4.runtime.tree.ParseTree, java.lang.String, int)
routines returntrue
orfalse
based upon a match for the tree rooted at the parameter sent in. Thematch(org.antlr.v4.runtime.tree.ParseTree, java.lang.String, int)
routines return aParseTreeMatch
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 withParseTreeMatch.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)
andParseTreePattern.match(org.antlr.v4.runtime.tree.ParseTree)
that are easy to use but not super efficient because they create newParseTreePatternMatcher
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; aParserInterpreter
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 validexpr
but, from the parser passed in, we create a special version of the underlying grammar representation (anATN
) 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 usingsetDelimiters(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 Description static class
ParseTreePatternMatcher.CannotInvokeStartRule
static class
ParseTreePatternMatcher.StartRuleDoesNotConsumeFullPattern
-
Constructor Summary
Constructors Constructor Description ParseTreePatternMatcher(Lexer lexer, Parser parser)
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description ParseTreePattern
compile(String pattern, int patternRuleIndex)
For repeated use of a tree pattern, compile it to aParseTreePattern
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)
Ist
(expr <expr>)
subtree?ParseTreeMatch
match(ParseTree tree, String pattern, int patternRuleIndex)
Comparepattern
matched as rulepatternRuleIndex
againsttree
and return aParseTreeMatch
object that contains the matched elements, or the node at which the match failed.ParseTreeMatch
match(ParseTree tree, ParseTreePattern pattern)
Comparepattern
matched againsttree
and return aParseTreeMatch
object that contains the matched elements, or the node at which the match failed.boolean
matches(ParseTree tree, String pattern, int patternRuleIndex)
Doespattern
matched as rulepatternRuleIndex
matchtree
?boolean
matches(ParseTree tree, ParseTreePattern pattern)
Doespattern
matched as rule patternRuleIndex match tree? Pass in a compiled pattern instead of a string representation of a tree pattern.protected ParseTree
matchImpl(ParseTree tree, ParseTree patternTree, MultiMap<String,ParseTree> 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 bytokenize(java.lang.String)
.List<? extends Token>
tokenize(String pattern)
-
-
-
Constructor Detail
-
ParseTreePatternMatcher
public ParseTreePatternMatcher(Lexer lexer, Parser parser)
Constructs aParseTreePatternMatcher
or from aLexer
andParser
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
- ifstart
isnull
or empty.IllegalArgumentException
- ifstop
isnull
or empty.
-
matches
public boolean matches(ParseTree tree, String pattern, int patternRuleIndex)
Doespattern
matched as rulepatternRuleIndex
matchtree
?
-
matches
public boolean matches(ParseTree tree, ParseTreePattern pattern)
Doespattern
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)
Comparepattern
matched as rulepatternRuleIndex
againsttree
and return aParseTreeMatch
object that contains the matched elements, or the node at which the match failed.
-
match
public ParseTreeMatch match(ParseTree tree, ParseTreePattern pattern)
Comparepattern
matched againsttree
and return aParseTreeMatch
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 aParseTreePattern
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)
- Returns:
- the first node encountered in
tree
which does not match a corresponding node inpatternTree
, ornull
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)
Ist
(expr <expr>)
subtree?
-
split
public List<org.antlr.v4.runtime.tree.pattern.Chunk> split(String pattern)
Split<ID> = <e:expr> ;
into 4 chunks for tokenizing bytokenize(java.lang.String)
.
-
-