granicus.if.org Git - clang/blob - 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     virtual void run(const MatchResult &Result) = 0;
  89   };
  90
  91   /// \brief Called when parsing is finished. Intended for testing only.
  92   class ParsingDoneTestCallback {
  93   public:
  94     virtual ~ParsingDoneTestCallback();
  95     virtual void run() = 0;
  96   };
  97
  98   MatchFinder();
  99   ~MatchFinder();
 100
 101   /// \brief Adds a matcher to execute when running over the AST.
 102   ///
 103   /// Calls 'Action' with the BoundNodes on every match.
 104   /// Adding more than one 'NodeMatch' allows finding different matches in a
 105   /// single pass over the AST.
 106   ///
 107   /// Does not take ownership of 'Action'.
 108   /// @{
 109   void addMatcher(const DeclarationMatcher &NodeMatch,
 110                   MatchCallback *Action);
 111   void addMatcher(const TypeMatcher &NodeMatch,
 112                   MatchCallback *Action);
 113   void addMatcher(const StatementMatcher &NodeMatch,
 114                   MatchCallback *Action);
 115   /// @}
 116
 117   /// \brief Creates a clang ASTConsumer that finds all matches.
 118   clang::ASTConsumer *newASTConsumer();
 119
 120   /// \brief Registers a callback to notify the end of parsing.
 121   ///
 122   /// The provided closure is called after parsing is done, before the AST is
 123   /// traversed. Useful for benchmarking.
 124   /// Each call to FindAll(...) will call the closure once.
 125   void registerTestCallbackAfterParsing(ParsingDoneTestCallback *ParsingDone);
 126
 127 private:
 128   /// \brief The MatchCallback*'s will be called every time the
 129   /// UntypedBaseMatcher matches on the AST.
 130   std::vector< std::pair<
 131     const internal::UntypedBaseMatcher*,
 132     MatchCallback*> > Triggers;
 133
 134   /// \brief Called when parsing is done.
 135   ParsingDoneTestCallback *ParsingDone;
 136 };
 137
 138 } // end namespace ast_matchers
 139 } // end namespace clang
 140
 141 #endif // LLVM_CLANG_AST_MATCHERS_AST_MATCH_FINDER_H