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

   1 //===--- ASTMatchFinder.h - Structural query framework ----------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 //  Provides a way to construct an ASTConsumer that runs given matchers
  11 //  over the AST and invokes a given callback on every match.
  12 //
  13 //  The general idea is to construct a matcher expression that describes a
  14 //  subtree match on the AST. Next, a callback that is executed every time the
  15 //  expression matches is registered, and the matcher is run over the AST of
  16 //  some code. Matched subexpressions can be bound to string IDs and easily
  17 //  be accessed from the registered callback. The callback can than use the
  18 //  AST nodes that the subexpressions matched on to output information about
  19 //  the match or construct changes that can be applied to the code.
  20 //
  21 //  Example:
  22 //  class HandleMatch : public MatchFinder::MatchCallback {
  23 //  public:
  24 //    virtual void Run(const MatchFinder::MatchResult &Result) {
  25 //      const CXXRecordDecl *Class =
  26 //          Result.Nodes.GetDeclAs<CXXRecordDecl>("id");
  27 //      ...
  28 //    }
  29 //  };
  30 //
  31 //  int main(int argc, char **argv) {
  32 //    ClangTool Tool(argc, argv);
  33 //    MatchFinder finder;
  34 //    finder.AddMatcher(Id("id", record(hasName("::a_namespace::AClass"))),
  35 //                      new HandleMatch);
  36 //    return Tool.Run(newFrontendActionFactory(&finder));
  37 //  }
  38 //
  39 //===----------------------------------------------------------------------===//
  40
  41 #ifndef LLVM_CLANG_AST_MATCHERS_AST_MATCH_FINDER_H
  42 #define LLVM_CLANG_AST_MATCHERS_AST_MATCH_FINDER_H
  43
  44 #include "clang/ASTMatchers/ASTMatchers.h"
  45
  46 namespace clang {
  47
  48 namespace ast_matchers {
  49
  50 /// \brief A class to allow finding matches over the Clang AST.
  51 ///
  52 /// After creation, you can add multiple matchers to the MatchFinder via
  53 /// calls to addMatcher(...).
  54 ///
  55 /// Once all matchers are added, newASTConsumer() returns an ASTConsumer
  56 /// that will trigger the callbacks specified via addMatcher(...) when a match
  57 /// is found.
  58 ///
  59 /// See ASTMatchers.h for more information about how to create matchers.
  60 ///
  61 /// Not intended to be subclassed.
  62 class MatchFinder {
  63 public:
  64   /// \brief Contains all information for a given match.
  65   ///
  66   /// Every time a match is found, the MatchFinder will invoke the registered
  67   /// MatchCallback with a MatchResult containing information about the match.
  68   struct MatchResult {
  69     MatchResult(const BoundNodes &Nodes, clang::ASTContext *Context);
  70
  71     /// \brief Contains the nodes bound on the current match.
  72     ///
  73     /// This allows user code to easily extract matched AST nodes.
  74     const BoundNodes Nodes;
  75
  76     /// \brief Utilities for interpreting the matched AST structures.
  77     /// @{
  78     clang::ASTContext * const Context;
  79     clang::SourceManager * const SourceManager;
  80     /// @}
  81   };
  82
  83   /// \brief Called when the Match registered for it was successfully found
  84   /// in the AST.
  85   class MatchCallback {
  86   public:
  87     virtual ~MatchCallback();
  88
  89     /// \brief Called on every match by the \c MatchFinder.
  90     virtual void run(const MatchResult &Result) = 0;
  91
  92     /// \brief Called at the start of each translation unit.
  93     ///
  94     /// Optionally override to do per translation unit tasks.
  95     virtual void onStartOfTranslationUnit() {}
  96   };
  97
  98   /// \brief Called when parsing is finished. Intended for testing only.
  99   class ParsingDoneTestCallback {
 100   public:
 101     virtual ~ParsingDoneTestCallback();
 102     virtual void run() = 0;
 103   };
 104
 105   MatchFinder();
 106   ~MatchFinder();
 107
 108   /// \brief Adds a matcher to execute when running over the AST.
 109   ///
 110   /// Calls 'Action' with the BoundNodes on every match.
 111   /// Adding more than one 'NodeMatch' allows finding different matches in a
 112   /// single pass over the AST.
 113   ///
 114   /// Does not take ownership of 'Action'.
 115   /// @{
 116   void addMatcher(const DeclarationMatcher &NodeMatch,
 117                   MatchCallback *Action);
 118   void addMatcher(const TypeMatcher &NodeMatch,
 119                   MatchCallback *Action);
 120   void addMatcher(const StatementMatcher &NodeMatch,
 121                   MatchCallback *Action);
 122   void addMatcher(const NestedNameSpecifierMatcher &NodeMatch,
 123                   MatchCallback *Action);
 124   void addMatcher(const NestedNameSpecifierLocMatcher &NodeMatch,
 125                   MatchCallback *Action);
 126   void addMatcher(const TypeLocMatcher &NodeMatch,
 127                   MatchCallback *Action);
 128   /// @}
 129
 130   /// \brief Creates a clang ASTConsumer that finds all matches.
 131   clang::ASTConsumer *newASTConsumer();
 132
 133   /// \brief Finds all matches on the given \c Node.
 134   ///
 135   /// @{
 136   void findAll(const Decl &Node, ASTContext &Context);
 137   void findAll(const Stmt &Node, ASTContext &Context);
 138   /// @}
 139
 140   /// \brief Registers a callback to notify the end of parsing.
 141   ///
 142   /// The provided closure is called after parsing is done, before the AST is
 143   /// traversed. Useful for benchmarking.
 144   /// Each call to FindAll(...) will call the closure once.
 145   void registerTestCallbackAfterParsing(ParsingDoneTestCallback *ParsingDone);
 146
 147 private:
 148   /// \brief For each \c DynTypedMatcher a \c MatchCallback that will be called
 149   /// when it matches.
 150   std::vector<std::pair<const internal::DynTypedMatcher*, MatchCallback*> >
 151     MatcherCallbackPairs;
 152
 153   /// \brief Called when parsing is done.
 154   ParsingDoneTestCallback *ParsingDone;
 155 };
 156
 157 } // end namespace ast_matchers
 158 } // end namespace clang
 159
 160 #endif // LLVM_CLANG_AST_MATCHERS_AST_MATCH_FINDER_H