Coverage Report

Created: 2019-07-24 05:18

/Users/buildslave/jenkins/workspace/clang-stage2-coverage-R/llvm/tools/clang/include/clang/ASTMatchers/ASTMatchFinder.h
Line
Count
Source
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
8.00k
    virtual void onStartOfTranslationUnit() {}
102
103
    /// Called at the end of each translation unit.
104
    ///
105
    /// Optionally override to do per translation unit tasks.
106
4.44k
    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
230
  template <typename T> void match(const T &Node, ASTContext &Context) {
185
230
    match(clang::ast_type_traits::DynTypedNode::create(Node), Context);
186
230
  }
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
894
selectFirst(StringRef BoundTo, const SmallVectorImpl<BoundNodes> &Results) {
268
894
  for (const BoundNodes &N : Results) {
269
461
    if (const NodeT *Node = N.getNodeAs<NodeT>(BoundTo))
270
461
      return Node;
271
461
  }
272
894
  
return nullptr433
;
273
894
}
clang::Expr const* clang::ast_matchers::selectFirst<clang::Expr>(llvm::StringRef, llvm::SmallVectorImpl<clang::ast_matchers::BoundNodes> const&)
Line
Count
Source
267
449
selectFirst(StringRef BoundTo, const SmallVectorImpl<BoundNodes> &Results) {
268
449
  for (const BoundNodes &N : Results) {
269
188
    if (const NodeT *Node = N.getNodeAs<NodeT>(BoundTo))
270
188
      return Node;
271
188
  }
272
449
  
return nullptr261
;
273
449
}
clang::Stmt const* clang::ast_matchers::selectFirst<clang::Stmt>(llvm::StringRef, llvm::SmallVectorImpl<clang::ast_matchers::BoundNodes> const&)
Line
Count
Source
267
445
selectFirst(StringRef BoundTo, const SmallVectorImpl<BoundNodes> &Results) {
268
445
  for (const BoundNodes &N : Results) {
269
273
    if (const NodeT *Node = N.getNodeAs<NodeT>(BoundTo))
270
273
      return Node;
271
273
  }
272
445
  
return nullptr172
;
273
445
}
274
275
namespace internal {
276
class CollectMatchesCallback : public MatchFinder::MatchCallback {
277
public:
278
1.20k
  void run(const MatchFinder::MatchResult &Result) override {
279
1.20k
    Nodes.push_back(Result.Nodes);
280
1.20k
  }
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
19.6k
      ASTContext &Context) {
289
19.6k
  internal::CollectMatchesCallback Callback;
290
19.6k
  MatchFinder Finder;
291
19.6k
  Finder.addMatcher(Matcher, &Callback);
292
19.6k
  Finder.match(Node, Context);
293
19.6k
  return std::move(Callback.Nodes);
294
19.6k
}
llvm::SmallVector<clang::ast_matchers::BoundNodes, 1u> clang::ast_matchers::match<clang::ast_matchers::internal::BindableMatcher<clang::Stmt> >(clang::ast_matchers::internal::BindableMatcher<clang::Stmt>, clang::ast_type_traits::DynTypedNode const&, clang::ASTContext&)
Line
Count
Source
288
16.3k
      ASTContext &Context) {
289
16.3k
  internal::CollectMatchesCallback Callback;
290
16.3k
  MatchFinder Finder;
291
16.3k
  Finder.addMatcher(Matcher, &Callback);
292
16.3k
  Finder.match(Node, Context);
293
16.3k
  return std::move(Callback.Nodes);
294
16.3k
}
llvm::SmallVector<clang::ast_matchers::BoundNodes, 1u> clang::ast_matchers::match<clang::ast_matchers::internal::BindableMatcher<clang::Decl> >(clang::ast_matchers::internal::BindableMatcher<clang::Decl>, clang::ast_type_traits::DynTypedNode const&, clang::ASTContext&)
Line
Count
Source
288
245
      ASTContext &Context) {
289
245
  internal::CollectMatchesCallback Callback;
290
245
  MatchFinder Finder;
291
245
  Finder.addMatcher(Matcher, &Callback);
292
245
  Finder.match(Node, Context);
293
245
  return std::move(Callback.Nodes);
294
245
}
llvm::SmallVector<clang::ast_matchers::BoundNodes, 1u> clang::ast_matchers::match<clang::ast_matchers::internal::Matcher<clang::Decl> >(clang::ast_matchers::internal::Matcher<clang::Decl>, clang::ast_type_traits::DynTypedNode const&, clang::ASTContext&)
Line
Count
Source
288
1.14k
      ASTContext &Context) {
289
1.14k
  internal::CollectMatchesCallback Callback;
290
1.14k
  MatchFinder Finder;
291
1.14k
  Finder.addMatcher(Matcher, &Callback);
292
1.14k
  Finder.match(Node, Context);
293
1.14k
  return std::move(Callback.Nodes);
294
1.14k
}
llvm::SmallVector<clang::ast_matchers::BoundNodes, 1u> clang::ast_matchers::match<clang::ast_matchers::internal::Matcher<clang::Stmt> >(clang::ast_matchers::internal::Matcher<clang::Stmt>, clang::ast_type_traits::DynTypedNode const&, clang::ASTContext&)
Line
Count
Source
288
1.90k
      ASTContext &Context) {
289
1.90k
  internal::CollectMatchesCallback Callback;
290
1.90k
  MatchFinder Finder;
291
1.90k
  Finder.addMatcher(Matcher, &Callback);
292
1.90k
  Finder.match(Node, Context);
293
1.90k
  return std::move(Callback.Nodes);
294
1.90k
}
295
296
template <typename MatcherT, typename NodeT>
297
SmallVector<BoundNodes, 1>
298
19.6k
match(MatcherT Matcher, const NodeT &Node, ASTContext &Context) {
299
19.6k
  return match(Matcher, ast_type_traits::DynTypedNode::create(Node), Context);
300
19.6k
}
llvm::SmallVector<clang::ast_matchers::BoundNodes, 1u> clang::ast_matchers::match<clang::ast_matchers::internal::BindableMatcher<clang::Stmt>, clang::Stmt>(clang::ast_matchers::internal::BindableMatcher<clang::Stmt>, clang::Stmt const&, clang::ASTContext&)
Line
Count
Source
298
16.3k
match(MatcherT Matcher, const NodeT &Node, ASTContext &Context) {
299
16.3k
  return match(Matcher, ast_type_traits::DynTypedNode::create(Node), Context);
300
16.3k
}
llvm::SmallVector<clang::ast_matchers::BoundNodes, 1u> clang::ast_matchers::match<clang::ast_matchers::internal::BindableMatcher<clang::Decl>, clang::Decl>(clang::ast_matchers::internal::BindableMatcher<clang::Decl>, clang::Decl const&, clang::ASTContext&)
Line
Count
Source
298
243
match(MatcherT Matcher, const NodeT &Node, ASTContext &Context) {
299
243
  return match(Matcher, ast_type_traits::DynTypedNode::create(Node), Context);
300
243
}
llvm::SmallVector<clang::ast_matchers::BoundNodes, 1u> clang::ast_matchers::match<clang::ast_matchers::internal::Matcher<clang::Decl>, clang::Decl>(clang::ast_matchers::internal::Matcher<clang::Decl>, clang::Decl const&, clang::ASTContext&)
Line
Count
Source
298
1.14k
match(MatcherT Matcher, const NodeT &Node, ASTContext &Context) {
299
1.14k
  return match(Matcher, ast_type_traits::DynTypedNode::create(Node), Context);
300
1.14k
}
llvm::SmallVector<clang::ast_matchers::BoundNodes, 1u> clang::ast_matchers::match<clang::ast_matchers::internal::Matcher<clang::Stmt>, clang::Stmt>(clang::ast_matchers::internal::Matcher<clang::Stmt>, clang::Stmt const&, clang::ASTContext&)
Line
Count
Source
298
1.90k
match(MatcherT Matcher, const NodeT &Node, ASTContext &Context) {
299
1.90k
  return match(Matcher, ast_type_traits::DynTypedNode::create(Node), Context);
300
1.90k
}
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