clang  9.0.0
Transformer.cpp
Go to the documentation of this file.
1 //===--- Transformer.cpp - Transformer library implementation ---*- 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 
10 #include "clang/AST/Expr.h"
13 #include "clang/Basic/Diagnostic.h"
18 #include "llvm/ADT/Optional.h"
19 #include "llvm/ADT/StringRef.h"
20 #include "llvm/Support/Errc.h"
21 #include "llvm/Support/Error.h"
22 #include <deque>
23 #include <string>
24 #include <utility>
25 #include <vector>
26 
27 using namespace clang;
28 using namespace tooling;
29 
31 using ast_matchers::internal::DynTypedMatcher;
34 using llvm::Error;
35 using llvm::StringError;
36 
38 
39 // Did the text at this location originate in a macro definition (aka. body)?
40 // For example,
41 //
42 // #define NESTED(x) x
43 // #define MACRO(y) { int y = NESTED(3); }
44 // if (true) MACRO(foo)
45 //
46 // The if statement expands to
47 //
48 // if (true) { int foo = 3; }
49 // ^ ^
50 // Loc1 Loc2
51 //
52 // For SourceManager SM, SM.isMacroArgExpansion(Loc1) and
53 // SM.isMacroArgExpansion(Loc2) are both true, but isOriginMacroBody(sm, Loc1)
54 // is false, because "foo" originated in the source file (as an argument to a
55 // macro), whereas isOriginMacroBody(SM, Loc2) is true, because "3" originated
56 // in the definition of MACRO.
59  while (Loc.isMacroID()) {
60  if (SM.isMacroBodyExpansion(Loc))
61  return true;
62  // Otherwise, it must be in an argument, so we continue searching up the
63  // invocation stack. getImmediateMacroCallerLoc() gives the location of the
64  // argument text, inside the call text.
65  Loc = SM.getImmediateMacroCallerLoc(Loc);
66  }
67  return false;
68 }
69 
70 Expected<SmallVector<tooling::detail::Transformation, 1>>
74  for (const auto &Edit : Edits) {
75  Expected<CharSourceRange> Range = Edit.TargetRange(Result);
76  if (!Range)
77  return Range.takeError();
78  if (Range->isInvalid() ||
79  isOriginMacroBody(*Result.SourceManager, Range->getBegin()))
81  auto Replacement = Edit.Replacement(Result);
82  if (!Replacement)
83  return Replacement.takeError();
85  T.Range = *Range;
86  T.Replacement = std::move(*Replacement);
87  Transformations.push_back(std::move(T));
88  }
89  return Transformations;
90 }
91 
93  ASTEdit E;
94  E.TargetRange = std::move(S);
95  E.Replacement = std::move(Replacement);
96  return E;
97 }
98 
100  TextGenerator Explanation) {
102  std::move(M), std::move(Edits), std::move(Explanation), {}}}};
103 }
104 
105 void tooling::addInclude(RewriteRule &Rule, StringRef Header,
106  IncludeFormat Format) {
107  for (auto &Case : Rule.Cases)
108  Case.AddedIncludes.emplace_back(Header.str(), Format);
109 }
110 
111 // Determines whether A is a base type of B in the class hierarchy, including
112 // the implicit relationship of Type and QualType.
113 static bool isBaseOf(ASTNodeKind A, ASTNodeKind B) {
114  static auto TypeKind = ASTNodeKind::getFromNodeKind<Type>();
115  static auto QualKind = ASTNodeKind::getFromNodeKind<QualType>();
116  /// Mimic the implicit conversions of Matcher<>.
117  /// - From Matcher<Type> to Matcher<QualType>
118  /// - From Matcher<Base> to Matcher<Derived>
119  return (A.isSame(TypeKind) && B.isSame(QualKind)) || A.isBaseOf(B);
120 }
121 
122 // Try to find a common kind to which all of the rule's matchers can be
123 // converted.
124 static ASTNodeKind
126  assert(!Cases.empty() && "Rule must have at least one case.");
127  ASTNodeKind JoinKind = Cases[0].Matcher.getSupportedKind();
128  // Find a (least) Kind K, for which M.canConvertTo(K) holds, for all matchers
129  // M in Rules.
130  for (const auto &Case : Cases) {
131  auto K = Case.Matcher.getSupportedKind();
132  if (isBaseOf(JoinKind, K)) {
133  JoinKind = K;
134  continue;
135  }
136  if (K.isSame(JoinKind) || isBaseOf(K, JoinKind))
137  // JoinKind is already the lowest.
138  continue;
139  // K and JoinKind are unrelated -- there is no least common kind.
140  return ASTNodeKind();
141  }
142  return JoinKind;
143 }
144 
145 // Binds each rule's matcher to a unique (and deterministic) tag based on
146 // `TagBase`.
147 static std::vector<DynTypedMatcher>
148 taggedMatchers(StringRef TagBase,
149  const SmallVectorImpl<RewriteRule::Case> &Cases) {
150  std::vector<DynTypedMatcher> Matchers;
151  Matchers.reserve(Cases.size());
152  size_t count = 0;
153  for (const auto &Case : Cases) {
154  std::string Tag = (TagBase + Twine(count)).str();
155  ++count;
156  auto M = Case.Matcher.tryBind(Tag);
157  assert(M && "RewriteRule matchers should be bindable.");
158  Matchers.push_back(*std::move(M));
159  }
160  return Matchers;
161 }
162 
163 // Simply gathers the contents of the various rules into a single rule. The
164 // actual work to combine these into an ordered choice is deferred to matcher
165 // registration.
167  RewriteRule R;
168  for (auto &Rule : Rules)
169  R.Cases.append(Rule.Cases.begin(), Rule.Cases.end());
170  return R;
171 }
172 
173 static DynTypedMatcher joinCaseMatchers(const RewriteRule &Rule) {
174  assert(!Rule.Cases.empty() && "Rule must have at least one case.");
175  if (Rule.Cases.size() == 1)
176  return Rule.Cases[0].Matcher;
177 
178  auto CommonKind = findCommonKind(Rule.Cases);
179  assert(!CommonKind.isNone() && "Cases must have compatible matchers.");
180  return DynTypedMatcher::constructVariadic(
181  DynTypedMatcher::VO_AnyOf, CommonKind, taggedMatchers("Tag", Rule.Cases));
182 }
183 
184 DynTypedMatcher tooling::detail::buildMatcher(const RewriteRule &Rule) {
185  DynTypedMatcher M = joinCaseMatchers(Rule);
186  M.setAllowBind(true);
187  // `tryBind` is guaranteed to succeed, because `AllowBind` was set to true.
188  return *M.tryBind(RewriteRule::RootID);
189 }
190 
191 // Finds the case that was "selected" -- that is, whose matcher triggered the
192 // `MatchResult`.
193 const RewriteRule::Case &
195  const RewriteRule &Rule) {
196  if (Rule.Cases.size() == 1)
197  return Rule.Cases[0];
198 
199  auto &NodesMap = Result.Nodes.getMap();
200  for (size_t i = 0, N = Rule.Cases.size(); i < N; ++i) {
201  std::string Tag = ("Tag" + Twine(i)).str();
202  if (NodesMap.find(Tag) != NodesMap.end())
203  return Rule.Cases[i];
204  }
205  llvm_unreachable("No tag found for this rule.");
206 }
207 
208 constexpr llvm::StringLiteral RewriteRule::RootID;
209 
211  MatchFinder->addDynamicMatcher(tooling::detail::buildMatcher(Rule), this);
212 }
213 
214 void Transformer::run(const MatchResult &Result) {
215  if (Result.Context->getDiagnostics().hasErrorOccurred())
216  return;
217 
218  // Verify the existence and validity of the AST node that roots this rule.
219  auto &NodesMap = Result.Nodes.getMap();
220  auto Root = NodesMap.find(RewriteRule::RootID);
221  assert(Root != NodesMap.end() && "Transformation failed: missing root node.");
222  SourceLocation RootLoc = Result.SourceManager->getExpansionLoc(
223  Root->second.getSourceRange().getBegin());
224  assert(RootLoc.isValid() && "Invalid location for Root node of match.");
225 
227  auto Transformations = tooling::detail::translateEdits(Result, Case.Edits);
228  if (!Transformations) {
229  Consumer(Transformations.takeError());
230  return;
231  }
232 
233  if (Transformations->empty()) {
234  // No rewrite applied (but no error encountered either).
235  RootLoc.print(llvm::errs() << "note: skipping match at loc ",
236  *Result.SourceManager);
237  llvm::errs() << "\n";
238  return;
239  }
240 
241  // Record the results in the AtomicChange.
242  AtomicChange AC(*Result.SourceManager, RootLoc);
243  for (const auto &T : *Transformations) {
244  if (auto Err = AC.replace(*Result.SourceManager, T.Range, T.Replacement)) {
245  Consumer(std::move(Err));
246  return;
247  }
248  }
249 
250  for (const auto &I : Case.AddedIncludes) {
251  auto &Header = I.first;
252  switch (I.second) {
254  AC.addHeader(Header);
255  break;
257  AC.addHeader((llvm::Twine("<") + Header + ">").str());
258  break;
259  }
260  }
261 
262  Consumer(std::move(AC));
263 }
A class to allow finding matches over the Clang AST.
llvm::Error replace(const SourceManager &SM, const CharSourceRange &Range, llvm::StringRef ReplacementText)
Adds a replacement that replaces the given Range with ReplacementText.
std::function< Expected< std::string >(const ast_matchers::MatchFinder::MatchResult &)> TextGenerator
Definition: Transformer.h:39
Description of a source-code transformation.
Definition: Transformer.h:118
bool isSame(ASTNodeKind Other) const
Returns true if this and Other represent the same kind.
Definition: ASTTypeTraits.h:77
void run(const ast_matchers::MatchFinder::MatchResult &Result) override
Not called directly by users – called by the framework, via base class pointer.
Defines a library supporting the concise specification of clang-based source-to-source transformation...
SourceLocation getImmediateMacroCallerLoc(SourceLocation Loc) const
Gets the location of the immediate macro caller, one level up the stack toward the initial macro type...
MatchFinder::MatchResult MatchResult
ast_matchers::internal::DynTypedMatcher buildMatcher(const RewriteRule &Rule)
Builds a single matcher for the rule, covering all of the rule&#39;s cases.
static bool isBaseOf(ASTNodeKind A, ASTNodeKind B)
long i
Definition: xmmintrin.h:1456
SmallVector< Case, 1 > Cases
Definition: Transformer.h:129
friend class SourceManager
std::function< Expected< CharSourceRange >(const ast_matchers::MatchFinder::MatchResult &)> RangeSelector
Definition: RangeSelector.h:27
void addHeader(llvm::StringRef Header)
Adds a header into the file that contains the key position.
Defines the Diagnostic-related interfaces.
bool isMacroBodyExpansion(SourceLocation Loc) const
Tests whether the given source location represents the expansion of a macro body. ...
Replacement()
Creates an invalid (not applicable) replacement.
Definition: Replacement.cpp:45
A text replacement.
Definition: Replacement.h:83
A source range independent of the SourceManager.
Definition: Replacement.h:44
RangeSelector TargetRange
Definition: Transformer.h:84
void registerMatchers(ast_matchers::MatchFinder *MatchFinder)
N.B.
MatchFinder::MatchResult MatchResult
Definition: Transformer.cpp:37
Contains all information for a given match.
const SourceManager & SM
Definition: Format.cpp:1572
Encodes a location in the source.
RewriteRule applyFirst(ArrayRef< RewriteRule > Rules)
Applies the first rule whose pattern matches; other rules are ignored.
Expected< SmallVector< Transformation, 1 > > translateEdits(const ast_matchers::MatchFinder::MatchResult &Result, llvm::ArrayRef< ASTEdit > Edits)
Attempts to translate Edits, which are in terms of AST nodes bound in the match Result, into Transformations, which are in terms of the source code text.
Definition: Transformer.cpp:71
bool isBaseOf(ASTNodeKind Other, unsigned *Distance=nullptr) const
Returns true if this is a base kind of (or same as) Other.
static std::vector< DynTypedMatcher > taggedMatchers(StringRef TagBase, const SmallVectorImpl< RewriteRule::Case > &Cases)
static constexpr llvm::StringLiteral RootID
Definition: Transformer.h:133
ast_type_traits::DynTypedNode DynTypedNode
static DynTypedMatcher joinCaseMatchers(const RewriteRule &Rule)
Dataflow Directional Tag Classes.
static bool isOriginMacroBody(const clang::SourceManager &SM, clang::SourceLocation Loc)
Definition: Transformer.cpp:57
const RewriteRule::Case & findSelectedCase(const ast_matchers::MatchFinder::MatchResult &Result, const RewriteRule &Rule)
Returns the Case of Rule that was selected in the match result.
TextGenerator Replacement
Definition: Transformer.h:85
static ASTNodeKind findCommonKind(const SmallVectorImpl< RewriteRule::Case > &Cases)
ASTEdit change(RangeSelector Target, TextGenerator Replacement)
Replaces a portion of the source text with Replacement.
Definition: Transformer.cpp:92
bool isMacroID() const
void addInclude(RewriteRule &Rule, llvm::StringRef Header, IncludeFormat Format=IncludeFormat::Quoted)
For every case in Rule, adds an include directive for the given header.
Defines the clang::SourceLocation class and associated facilities.
A source "transformation," represented by a character range in the source to be replaced and a corres...
Definition: Transformer.h:256
IncludeFormat
Format of the path in an include directive – angle brackets or quotes.
Definition: Transformer.h:90
RewriteRule makeRule(ast_matchers::internal::DynTypedMatcher M, SmallVector< ASTEdit, 1 > Edits, TextGenerator Explanation=nullptr)
Convenience function for constructing a simple RewriteRule.
An atomic change is used to create and group a set of source edits, e.g.
Definition: AtomicChange.h:36
This class handles loading and caching of source files into memory.
bool addDynamicMatcher(const internal::DynTypedMatcher &NodeMatch, MatchCallback *Action)
Adds a matcher to execute when running over the AST.