gitweb.ps.run Git - toc/blob - antlr4-cpp-runtime-4.9.2-source/runtime/src/tree/pattern/ParseTreeMatch.h

   1 /* Copyright (c) 2012-2017 The ANTLR Project. All rights reserved.
   2  * Use of this file is governed by the BSD 3-clause license that
   3  * can be found in the LICENSE.txt file in the project root.
   4  */
   5
   6 #pragma once
   7
   8 #include "antlr4-common.h"
   9
  10 namespace antlr4 {
  11 namespace tree {
  12 namespace pattern {
  13
  14   /// Represents the result of matching a ParseTree against a tree pattern.
  15   class ANTLR4CPP_PUBLIC ParseTreeMatch {
  16   private:
  17     /// This is the backing field for getTree().
  18     ParseTree *_tree;
  19
  20     /// This is the backing field for getPattern().
  21     const ParseTreePattern &_pattern;
  22
  23     /// This is the backing field for getLabels().
  24     std::map<std::string, std::vector<ParseTree *>> _labels;
  25
  26     /// This is the backing field for getMismatchedNode().
  27     ParseTree *_mismatchedNode;
  28
  29   public:
  30     /// <summary>
  31     /// Constructs a new instance of <seealso cref="ParseTreeMatch"/> from the specified
  32     /// parse tree and pattern.
  33     /// </summary>
  34     /// <param name="tree"> The parse tree to match against the pattern. </param>
  35     /// <param name="pattern"> The parse tree pattern. </param>
  36     /// <param name="labels"> A mapping from label names to collections of
  37     /// <seealso cref="ParseTree"/> objects located by the tree pattern matching process. </param>
  38     /// <param name="mismatchedNode"> The first node which failed to match the tree
  39     /// pattern during the matching process.
  40     /// </param>
  41     /// <exception cref="IllegalArgumentException"> if {@code tree} is {@code null} </exception>
  42     /// <exception cref="IllegalArgumentException"> if {@code pattern} is {@code null} </exception>
  43     /// <exception cref="IllegalArgumentException"> if {@code labels} is {@code null} </exception>
  44     ParseTreeMatch(ParseTree *tree, ParseTreePattern const& pattern,
  45                    const std::map<std::string, std::vector<ParseTree *>> &labels, ParseTree *mismatchedNode);
  46     ParseTreeMatch(ParseTreeMatch const&) = default;
  47     virtual ~ParseTreeMatch();
  48
  49     /// <summary>
  50     /// Get the last node associated with a specific {@code label}.
  51     /// <p/>
  52     /// For example, for pattern {@code <id:ID>}, {@code get("id")} returns the
  53     /// node matched for that {@code ID}. If more than one node
  54     /// matched the specified label, only the last is returned. If there is
  55     /// no node associated with the label, this returns {@code null}.
  56     /// <p/>
  57     /// Pattern tags like {@code <ID>} and {@code <expr>} without labels are
  58     /// considered to be labeled with {@code ID} and {@code expr}, respectively.
  59     /// </summary>
  60     /// <param name="labe"> The label to check.
  61     /// </param>
  62     /// <returns> The last <seealso cref="ParseTree"/> to match a tag with the specified
  63     /// label, or {@code null} if no parse tree matched a tag with the label. </returns>
  64     virtual ParseTree* get(const std::string &label);
  65
  66     /// <summary>
  67     /// Return all nodes matching a rule or token tag with the specified label.
  68     /// <p/>
  69     /// If the {@code label} is the name of a parser rule or token in the
  70     /// grammar, the resulting list will contain both the parse trees matching
  71     /// rule or tags explicitly labeled with the label and the complete set of
  72     /// parse trees matching the labeled and unlabeled tags in the pattern for
  73     /// the parser rule or token. For example, if {@code label} is {@code "foo"},
  74     /// the result will contain <em>all</em> of the following.
  75     ///
  76     /// <ul>
  77     /// <li>Parse tree nodes matching tags of the form {@code <foo:anyRuleName>} and
  78     /// {@code <foo:AnyTokenName>}.</li>
  79     /// <li>Parse tree nodes matching tags of the form {@code <anyLabel:foo>}.</li>
  80     /// <li>Parse tree nodes matching tags of the form {@code <foo>}.</li>
  81     /// </ul>
  82     /// </summary>
  83     /// <param name="labe"> The label.
  84     /// </param>
  85     /// <returns> A collection of all <seealso cref="ParseTree"/> nodes matching tags with
  86     /// the specified {@code label}. If no nodes matched the label, an empty list
  87     /// is returned. </returns>
  88     virtual std::vector<ParseTree *> getAll(const std::string &label);
  89
  90     /// <summary>
  91     /// Return a mapping from label &rarr; [list of nodes].
  92     /// <p/>
  93     /// The map includes special entries corresponding to the names of rules and
  94     /// tokens referenced in tags in the original pattern. For additional
  95     /// information, see the description of <seealso cref="#getAll(String)"/>.
  96     /// </summary>
  97     /// <returns> A mapping from labels to parse tree nodes. If the parse tree
  98     /// pattern did not contain any rule or token tags, this map will be empty. </returns>
  99     virtual std::map<std::string, std::vector<ParseTree *>>& getLabels();
 100
 101     /// <summary>
 102     /// Get the node at which we first detected a mismatch.
 103     /// </summary>
 104     /// <returns> the node at which we first detected a mismatch, or {@code null}
 105     /// if the match was successful. </returns>
 106     virtual ParseTree* getMismatchedNode();
 107
 108     /// <summary>
 109     /// Gets a value indicating whether the match operation succeeded.
 110     /// </summary>
 111     /// <returns> {@code true} if the match operation succeeded; otherwise,
 112     /// {@code false}. </returns>
 113     virtual bool succeeded();
 114
 115     /// <summary>
 116     /// Get the tree pattern we are matching against.
 117     /// </summary>
 118     /// <returns> The tree pattern we are matching against. </returns>
 119     virtual const ParseTreePattern& getPattern();
 120
 121     /// <summary>
 122     /// Get the parse tree we are trying to match to a pattern.
 123     /// </summary>
 124     /// <returns> The <seealso cref="ParseTree"/> we are trying to match to a pattern. </returns>
 125     virtual ParseTree* getTree();
 126
 127     virtual std::string toString();
 128   };
 129
 130 } // namespace pattern
 131 } // namespace tree
 132 } // namespace antlr4