Class ParseTreePatternMatcher
ParseTree
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
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 ClassesModifier and TypeClassDescriptionstatic class
static class
-
Field Summary
Fields -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionFor repeated use of a tree pattern, compile it to aParseTreePattern
using this method.getLexer()
Used to convert the tree pattern string into a series of tokens.Used to collect to the grammar file name, token names, rule names for used to parse the pattern into a parse tree.protected RuleTagToken
Ist
(expr <expr>)
subtree?Comparepattern
matched as rulepatternRuleIndex
againsttree
and return aParseTreeMatch
object that contains the matched elements, or the node at which the match failed.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
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
Recursively walktree
againstpatternTree
, fillingmatch.
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<ID> = <e:expr> ;
into 4 chunks for tokenizing bytokenize(java.lang.String)
.
-
Field Details
-
start
-
stop
-
escape
-
-
Constructor Details
-
ParseTreePatternMatcher
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 Details
-
setDelimiters
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
Doespattern
matched as rulepatternRuleIndex
matchtree
? -
matches
Doespattern
matched as rule patternRuleIndex match tree? Pass in a compiled pattern instead of a string representation of a tree pattern. -
match
Comparepattern
matched as rulepatternRuleIndex
againsttree
and return aParseTreeMatch
object that contains the matched elements, or the node at which the match failed. -
match
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
For repeated use of a tree pattern, compile it to aParseTreePattern
using this method. -
getLexer
Used to convert the tree pattern string into a series of tokens. The input stream is reset. -
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 walktree
againstpatternTree
, fillingmatch.
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
Ist
(expr <expr>)
subtree? -
tokenize
-
split
Split<ID> = <e:expr> ;
into 4 chunks for tokenizing bytokenize(java.lang.String)
.
-