[ASTMatchers] Always create a "binding" for the node being matched on.

[njames93]

Summary

Most often when using matchers, there is a need to get the root node that the matcher matched on.
Currently the only way to do this is to manually create a binding the the root matcher, however this has some drawbacks.
It can be prone to typos and there is no universal agreed name to give the root node, so an API that accepts a DynTypedMatcher wont be able to figure out what the root actually is.

By altering the infrastructure to always provide access to the node being matched on, that isn't dependent on names, it can simplify workflow a lot.

[steveire]

Can you add some tests for this?

clang/include/clang/ASTMatchers/ASTMatchFinder.h

 selectFirst(StringRef BoundTo, const SmallVectorImpl<BoundNodes> &Results) {
   for (const BoundNodes &N : Results) {
     if (const NodeT *Node = N.getNodeAs<NodeT>(BoundTo))
       return Node;
   }
   return nullptr;
 }
 
+/// Returns the first result of type \c NodeT bound to the root match result.
+///
+/// Returns \c NULL if there is no match, or if the matching node cannot be
+/// casted to \c NodeT.
+///
+/// This is useful in combanation with \c match():
+/// \code
+///   const Decl *D = selectFirst<Decl>(match(DeclMatcher, Node, Context));
+/// \endcode
+template <typename NodeT>
+const NodeT *selectFirst(const SmallVectorImpl<BoundNodes> &Results) {
+  for (const BoundNodes &N : Results) {
+    if (const NodeT *Node = N.getRootAs<NodeT>())
+      return Node;
+  }
+  return nullptr;
+}
+
 namespace internal {
 class CollectMatchesCallback : public MatchFinder::MatchCallback {
 public:
   void run(const MatchFinder::MatchResult &Result) override {
     Nodes.push_back(Result.Nodes);
   }
 
   llvm::Optional<TraversalKind> getCheckTraversalKind() const override {

clang/include/clang/ASTMatchers/ASTMatchers.h

public:
   /// type of \c clang::DynTypedNode
   using IDToNodeMap = internal::BoundNodesMap::IDToNodeMap;
 
   /// Retrieve mapping from binding identifiers to bound nodes.
   const IDToNodeMap &getMap() const {
     return MyBoundNodes.getMap();
   }
 
+  template <typename T> const T *getRootAs() const { return RootNode.get<T>(); }
+
+  const DynTypedNode &getRoot() const { return RootNode; }
+
 private:
   friend class internal::BoundNodesTreeBuilder;
 
   /// Create BoundNodes from a pre-filled map of bindings.
-  BoundNodes(internal::BoundNodesMap &MyBoundNodes)
-      : MyBoundNodes(MyBoundNodes) {}
+  BoundNodes(internal::BoundNodesMap &MyBoundNodes,
+             const DynTypedNode &RootNode)
+      : MyBoundNodes(MyBoundNodes), RootNode(RootNode) {}
 
   internal::BoundNodesMap MyBoundNodes;
+
+  DynTypedNode RootNode;
 };
 
 /// Types of matchers for the top-level classes in the AST class
 /// hierarchy.
 /// @{
 using DeclarationMatcher = internal::Matcher<Decl>;
 using StatementMatcher = internal::Matcher<Stmt>;
 using TypeMatcher = internal::Matcher<QualType>;

clang/include/clang/ASTMatchers/ASTMatchersInternal.h

public:
   }
 
   /// Adds a branch in the tree.
   void addMatch(const BoundNodesTreeBuilder &Bindings);
 
   /// Visits all matches that this BoundNodesTree represents.
   ///
   /// The ownership of 'ResultVisitor' remains at the caller.
-  void visitMatches(Visitor* ResultVisitor);
+  void visitMatches(Visitor *ResultVisitor, const DynTypedNode &RootNode);
 
   template <typename ExcludePredicate>
   bool removeBindings(const ExcludePredicate &Predicate) {
     Bindings.erase(std::remove_if(Bindings.begin(), Bindings.end(), Predicate),
                    Bindings.end());
     return !Bindings.empty();
   }
 

clang/lib/ASTMatchers/ASTMatchFinder.cpp

void matchWithoutFilter(const T &Node, const MC &Matchers) {
     const bool EnableCheckProfiling = Options.CheckProfiling.hasValue();
     TimeBucketRegion Timer;
     for (const auto &MP : Matchers) {
       if (EnableCheckProfiling)
         Timer.setBucket(&TimeByBucket[MP.second->getID()]);
       BoundNodesTreeBuilder Builder;
       if (MP.first.matches(Node, this, &Builder)) {
         MatchVisitor Visitor(ActiveASTContext, MP.second);
-        Builder.visitMatches(&Visitor);
+        Builder.visitMatches(&Visitor, DynTypedNode::create(Node));
       }
     }
   }
 
   void matchWithFilter(const DynTypedNode &DynNode) {
     auto Kind = DynNode.getNodeKind();
     auto it = MatcherFiltersMap.find(Kind);
     const auto &Filter =
for (unsigned short I : Filter) {
         TraversalKindScope RAII(getASTContext(), MP.first.getTraversalKind());
         if (getASTContext().getParentMapContext().traverseIgnored(DynNode) !=
             DynNode)
           continue;
       }
 
       if (MP.first.matches(DynNode, this, &Builder)) {
         MatchVisitor Visitor(ActiveASTContext, MP.second);
-        Builder.visitMatches(&Visitor);
+        Builder.visitMatches(&Visitor, DynNode);
       }
     }
   }
 
   const std::vector<unsigned short> &getFilterForKind(ASTNodeKind Kind) {
     auto &Filter = MatcherFiltersMap[Kind];
     auto &Matchers = this->Matchers->DeclOrStmt;
     assert((Matchers.size() < USHRT_MAX) && "Too many matchers.");

clang/lib/ASTMatchers/ASTMatchersInternal.cpp

const auto basePredicate =
         }
         return false;
       };
 
   return Node.lookupInBases(basePredicate, Paths,
                             /*LookupInDependent =*/true);
 }
 
-void BoundNodesTreeBuilder::visitMatches(Visitor *ResultVisitor) {
+void BoundNodesTreeBuilder::visitMatches(Visitor *ResultVisitor,
+                                         const DynTypedNode &RootNode) {
   if (Bindings.empty())
     Bindings.push_back(BoundNodesMap());
   for (BoundNodesMap &Binding : Bindings) {
-    ResultVisitor->visitMatch(BoundNodes(Binding));
+    ResultVisitor->visitMatch(BoundNodes(Binding, RootNode));
   }
 }
 
 namespace {
 
 using VariadicOperatorFunction = bool (*)(
     const DynTypedNode &DynNode, ASTMatchFinder *Finder,
     BoundNodesTreeBuilder *Builder, ArrayRef<DynTypedMatcher> InnerMatchers);