contrib/llvm/tools/clang/include/clang/ASTMatchers/ASTMatchFinder.h

   1 //===--- ASTMatchFinder.h - Structural query framework ----------*- C++ -*-===//
   2 //
   3 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
   4 // See https://llvm.org/LICENSE.txt for license information.
   5 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
   6 //
   7 //===----------------------------------------------------------------------===//
   8 //
   9 //  Provides a way to construct an ASTConsumer that runs given matchers
  10 //  over the AST and invokes a given callback on every match.
  11 //
  12 //  The general idea is to construct a matcher expression that describes a
  13 //  subtree match on the AST. Next, a callback that is executed every time the
  14 //  expression matches is registered, and the matcher is run over the AST of
  15 //  some code. Matched subexpressions can be bound to string IDs and easily
  16 //  be accessed from the registered callback. The callback can than use the
  17 //  AST nodes that the subexpressions matched on to output information about
  18 //  the match or construct changes that can be applied to the code.
  19 //
  20 //  Example:
  21 //  class HandleMatch : public MatchFinder::MatchCallback {
  22 //  public:
  23 //    virtual void Run(const MatchFinder::MatchResult &Result) {
  24 //      const CXXRecordDecl *Class =
  25 //          Result.Nodes.GetDeclAs<CXXRecordDecl>("id");
  26 //      ...
  27 //    }
  28 //  };
  29 //
  30 //  int main(int argc, char **argv) {
  31 //    ClangTool Tool(argc, argv);
  32 //    MatchFinder finder;
  33 //    finder.AddMatcher(Id("id", record(hasName("::a_namespace::AClass"))),
  34 //                      new HandleMatch);
  35 //    return Tool.Run(newFrontendActionFactory(&finder));
  36 //  }
  37 //
  38 //===----------------------------------------------------------------------===//
  39
  40 #ifndef LLVM_CLANG_ASTMATCHERS_ASTMATCHFINDER_H
  41 #define LLVM_CLANG_ASTMATCHERS_ASTMATCHFINDER_H
  42
  43 #include "clang/ASTMatchers/ASTMatchers.h"
  44 #include "llvm/ADT/SmallPtrSet.h"
  45 #include "llvm/ADT/StringMap.h"
  46 #include "llvm/Support/Timer.h"
  47
  48 namespace clang {
  49
  50 namespace ast_matchers {
  51
  52 /// A class to allow finding matches over the Clang AST.
  53 ///
  54 /// After creation, you can add multiple matchers to the MatchFinder via
  55 /// calls to addMatcher(...).
  56 ///
  57 /// Once all matchers are added, newASTConsumer() returns an ASTConsumer
  58 /// that will trigger the callbacks specified via addMatcher(...) when a match
  59 /// is found.
  60 ///
  61 /// The order of matches is guaranteed to be equivalent to doing a pre-order
  62 /// traversal on the AST, and applying the matchers in the order in which they
  63 /// were added to the MatchFinder.
  64 ///
  65 /// See ASTMatchers.h for more information about how to create matchers.
  66 ///
  67 /// Not intended to be subclassed.
  68 class MatchFinder {
  69 public:
  70   /// Contains all information for a given match.
  71   ///
  72   /// Every time a match is found, the MatchFinder will invoke the registered
  73   /// MatchCallback with a MatchResult containing information about the match.
  74   struct MatchResult {
  75     MatchResult(const BoundNodes &Nodes, clang::ASTContext *Context);
  76
  77     /// Contains the nodes bound on the current match.
  78     ///
  79     /// This allows user code to easily extract matched AST nodes.
  80     const BoundNodes Nodes;
  81
  82     /// Utilities for interpreting the matched AST structures.
  83     /// @{
  84     clang::ASTContext * const Context;
  85     clang::SourceManager * const SourceManager;
  86     /// @}
  87   };
  88
  89   /// Called when the Match registered for it was successfully found
  90   /// in the AST.
  91   class MatchCallback {
  92   public:
  93     virtual ~MatchCallback();
  94
  95     /// Called on every match by the \c MatchFinder.
  96     virtual void run(const MatchResult &Result) = 0;
  97
  98     /// Called at the start of each translation unit.
  99     ///
 100     /// Optionally override to do per translation unit tasks.
 101     virtual void onStartOfTranslationUnit() {}
 102
 103     /// Called at the end of each translation unit.
 104     ///
 105     /// Optionally override to do per translation unit tasks.
 106     virtual void onEndOfTranslationUnit() {}
 107
 108     /// An id used to group the matchers.
 109     ///
 110     /// This id is used, for example, for the profiling output.
 111     /// It defaults to "<unknown>".
 112     virtual StringRef getID() const;
 113   };
 114
 115   /// Called when parsing is finished. Intended for testing only.
 116   class ParsingDoneTestCallback {
 117   public:
 118     virtual ~ParsingDoneTestCallback();
 119     virtual void run() = 0;
 120   };
 121
 122   struct MatchFinderOptions {
 123     struct Profiling {
 124       Profiling(llvm::StringMap<llvm::TimeRecord> &Records)
 125           : Records(Records) {}
 126
 127       /// Per bucket timing information.
 128       llvm::StringMap<llvm::TimeRecord> &Records;
 129     };
 130
 131     /// Enables per-check timers.
 132     ///
 133     /// It prints a report after match.
 134     llvm::Optional<Profiling> CheckProfiling;
 135   };
 136
 137   MatchFinder(MatchFinderOptions Options = MatchFinderOptions());
 138   ~MatchFinder();
 139
 140   /// Adds a matcher to execute when running over the AST.
 141   ///
 142   /// Calls 'Action' with the BoundNodes on every match.
 143   /// Adding more than one 'NodeMatch' allows finding different matches in a
 144   /// single pass over the AST.
 145   ///
 146   /// Does not take ownership of 'Action'.
 147   /// @{
 148   void addMatcher(const DeclarationMatcher &NodeMatch,
 149                   MatchCallback *Action);
 150   void addMatcher(const TypeMatcher &NodeMatch,
 151                   MatchCallback *Action);
 152   void addMatcher(const StatementMatcher &NodeMatch,
 153                   MatchCallback *Action);
 154   void addMatcher(const NestedNameSpecifierMatcher &NodeMatch,
 155                   MatchCallback *Action);
 156   void addMatcher(const NestedNameSpecifierLocMatcher &NodeMatch,
 157                   MatchCallback *Action);
 158   void addMatcher(const TypeLocMatcher &NodeMatch,
 159                   MatchCallback *Action);
 160   void addMatcher(const CXXCtorInitializerMatcher &NodeMatch,
 161                   MatchCallback *Action);
 162   /// @}
 163
 164   /// Adds a matcher to execute when running over the AST.
 165   ///
 166   /// This is similar to \c addMatcher(), but it uses the dynamic interface. It
 167   /// is more flexible, but the lost type information enables a caller to pass
 168   /// a matcher that cannot match anything.
 169   ///
 170   /// \returns \c true if the matcher is a valid top-level matcher, \c false
 171   ///   otherwise.
 172   bool addDynamicMatcher(const internal::DynTypedMatcher &NodeMatch,
 173                          MatchCallback *Action);
 174
 175   /// Creates a clang ASTConsumer that finds all matches.
 176   std::unique_ptr<clang::ASTConsumer> newASTConsumer();
 177
 178   /// Calls the registered callbacks on all matches on the given \p Node.
 179   ///
 180   /// Note that there can be multiple matches on a single node, for
 181   /// example when using decl(forEachDescendant(stmt())).
 182   ///
 183   /// @{
 184   template <typename T> void match(const T &Node, ASTContext &Context) {
 185     match(clang::ast_type_traits::DynTypedNode::create(Node), Context);
 186   }
 187   void match(const clang::ast_type_traits::DynTypedNode &Node,
 188              ASTContext &Context);
 189   /// @}
 190
 191   /// Finds all matches in the given AST.
 192   void matchAST(ASTContext &Context);
 193
 194   /// Registers a callback to notify the end of parsing.
 195   ///
 196   /// The provided closure is called after parsing is done, before the AST is
 197   /// traversed. Useful for benchmarking.
 198   /// Each call to FindAll(...) will call the closure once.
 199   void registerTestCallbackAfterParsing(ParsingDoneTestCallback *ParsingDone);
 200
 201   /// For each \c Matcher<> a \c MatchCallback that will be called
 202   /// when it matches.
 203   struct MatchersByType {
 204     std::vector<std::pair<internal::DynTypedMatcher, MatchCallback *>>
 205         DeclOrStmt;
 206     std::vector<std::pair<TypeMatcher, MatchCallback *>> Type;
 207     std::vector<std::pair<NestedNameSpecifierMatcher, MatchCallback *>>
 208         NestedNameSpecifier;
 209     std::vector<std::pair<NestedNameSpecifierLocMatcher, MatchCallback *>>
 210         NestedNameSpecifierLoc;
 211     std::vector<std::pair<TypeLocMatcher, MatchCallback *>> TypeLoc;
 212     std::vector<std::pair<CXXCtorInitializerMatcher, MatchCallback *>> CtorInit;
 213     /// All the callbacks in one container to simplify iteration.
 214     llvm::SmallPtrSet<MatchCallback *, 16> AllCallbacks;
 215   };
 216
 217 private:
 218   MatchersByType Matchers;
 219
 220   MatchFinderOptions Options;
 221
 222   /// Called when parsing is done.
 223   ParsingDoneTestCallback *ParsingDone;
 224 };
 225
 226 /// Returns the results of matching \p Matcher on \p Node.
 227 ///
 228 /// Collects the \c BoundNodes of all callback invocations when matching
 229 /// \p Matcher on \p Node and returns the collected results.
 230 ///
 231 /// Multiple results occur when using matchers like \c forEachDescendant,
 232 /// which generate a result for each sub-match.
 233 ///
 234 /// If you want to find all matches on the sub-tree rooted at \c Node (rather
 235 /// than only the matches on \c Node itself), surround the \c Matcher with a
 236 /// \c findAll().
 237 ///
 238 /// \see selectFirst
 239 /// @{
 240 template <typename MatcherT, typename NodeT>
 241 SmallVector<BoundNodes, 1>
 242 match(MatcherT Matcher, const NodeT &Node, ASTContext &Context);
 243
 244 template <typename MatcherT>
 245 SmallVector<BoundNodes, 1>
 246 match(MatcherT Matcher, const ast_type_traits::DynTypedNode &Node,
 247       ASTContext &Context);
 248 /// @}
 249
 250 /// Returns the results of matching \p Matcher on the translation unit of
 251 /// \p Context and collects the \c BoundNodes of all callback invocations.
 252 template <typename MatcherT>
 253 SmallVector<BoundNodes, 1> match(MatcherT Matcher, ASTContext &Context);
 254
 255 /// Returns the first result of type \c NodeT bound to \p BoundTo.
 256 ///
 257 /// Returns \c NULL if there is no match, or if the matching node cannot be
 258 /// casted to \c NodeT.
 259 ///
 260 /// This is useful in combanation with \c match():
 261 /// \code
 262 ///   const Decl *D = selectFirst<Decl>("id", match(Matcher.bind("id"),
 263 ///                                                 Node, Context));
 264 /// \endcode
 265 template <typename NodeT>
 266 const NodeT *
 267 selectFirst(StringRef BoundTo, const SmallVectorImpl<BoundNodes> &Results) {
 268   for (const BoundNodes &N : Results) {
 269     if (const NodeT *Node = N.getNodeAs<NodeT>(BoundTo))
 270       return Node;
 271   }
 272   return nullptr;
 273 }
 274
 275 namespace internal {
 276 class CollectMatchesCallback : public MatchFinder::MatchCallback {
 277 public:
 278   void run(const MatchFinder::MatchResult &Result) override {
 279     Nodes.push_back(Result.Nodes);
 280   }
 281   SmallVector<BoundNodes, 1> Nodes;
 282 };
 283 }
 284
 285 template <typename MatcherT>
 286 SmallVector<BoundNodes, 1>
 287 match(MatcherT Matcher, const ast_type_traits::DynTypedNode &Node,
 288       ASTContext &Context) {
 289   internal::CollectMatchesCallback Callback;
 290   MatchFinder Finder;
 291   Finder.addMatcher(Matcher, &Callback);
 292   Finder.match(Node, Context);
 293   return std::move(Callback.Nodes);
 294 }
 295
 296 template <typename MatcherT, typename NodeT>
 297 SmallVector<BoundNodes, 1>
 298 match(MatcherT Matcher, const NodeT &Node, ASTContext &Context) {
 299   return match(Matcher, ast_type_traits::DynTypedNode::create(Node), Context);
 300 }
 301
 302 template <typename MatcherT>
 303 SmallVector<BoundNodes, 1>
 304 match(MatcherT Matcher, ASTContext &Context) {
 305   internal::CollectMatchesCallback Callback;
 306   MatchFinder Finder;
 307   Finder.addMatcher(Matcher, &Callback);
 308   Finder.matchAST(Context);
 309   return std::move(Callback.Nodes);
 310 }
 311
 312 } // end namespace ast_matchers
 313 } // end namespace clang
 314
 315 #endif