clang  10.0.0svn
Transformer.h
Go to the documentation of this file.
1 //===--- Transformer.h - Clang source-rewriting library ---------*- 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 /// \file
10 /// Defines a library supporting the concise specification of clang-based
11 /// source-to-source transformations.
12 ///
13 //===----------------------------------------------------------------------===//
14 
15 #ifndef LLVM_CLANG_TOOLING_REFACTOR_TRANSFORMER_H_
16 #define LLVM_CLANG_TOOLING_REFACTOR_TRANSFORMER_H_
17 
23 #include "llvm/ADT/STLExtras.h"
24 #include "llvm/ADT/SmallVector.h"
25 #include "llvm/Support/Error.h"
26 #include <deque>
27 #include <functional>
28 #include <string>
29 #include <type_traits>
30 #include <utility>
31 
32 namespace clang {
33 namespace tooling {
34 
35 // Note that \p TextGenerator is allowed to fail, e.g. when trying to access a
36 // matched node that was not bound. Allowing this to fail simplifies error
37 // handling for interactive tools like clang-query.
38 using TextGenerator = std::function<Expected<std::string>(
40 
41 /// Wraps a string as a TextGenerator.
42 inline TextGenerator text(std::string M) {
43  return [M](const ast_matchers::MatchFinder::MatchResult &)
44  -> Expected<std::string> { return M; };
45 }
46 
47 // Description of a source-code edit, expressed in terms of an AST node.
48 // Includes: an ID for the (bound) node, a selector for source related to the
49 // node, a replacement and, optionally, an explanation for the edit.
50 //
51 // * Target: the source code impacted by the rule. This identifies an AST node,
52 // or part thereof (\c Part), whose source range indicates the extent of the
53 // replacement applied by the replacement term. By default, the extent is the
54 // node matched by the pattern term (\c NodePart::Node). Target's are typed
55 // (\c Kind), which guides the determination of the node extent.
56 //
57 // * Replacement: a function that produces a replacement string for the target,
58 // based on the match result.
59 //
60 // * Note: (optional) a note specifically for this edit, potentially referencing
61 // elements of the match. This will be displayed to the user, where possible;
62 // for example, in clang-tidy diagnostics. Use of notes should be rare --
63 // explanations of the entire rewrite should be set in the rule
64 // (`RewriteRule::Explanation`) instead. Notes serve the rare cases wherein
65 // edit-specific diagnostics are required.
66 //
67 // `ASTEdit` should be built using the `change` convenience functions. For
68 // example,
69 // \code
70 // change(name(fun), text("Frodo"))
71 // \endcode
72 // Or, if we use Stencil for the TextGenerator:
73 // \code
74 // using stencil::cat;
75 // change(statement(thenNode), cat("{", thenNode, "}"))
76 // change(callArgs(call), cat(x, ",", y))
77 // \endcode
78 // Or, if you are changing the node corresponding to the rule's matcher, you can
79 // use the single-argument override of \c change:
80 // \code
81 // change(cat("different_expr"))
82 // \endcode
83 struct ASTEdit {
87 };
88 
89 /// Format of the path in an include directive -- angle brackets or quotes.
90 enum class IncludeFormat {
91  Quoted,
92  Angled,
93 };
94 
95 /// Description of a source-code transformation.
96 //
97 // A *rewrite rule* describes a transformation of source code. A simple rule
98 // contains each of the following components:
99 //
100 // * Matcher: the pattern term, expressed as clang matchers (with Transformer
101 // extensions).
102 //
103 // * Edits: a set of Edits to the source code, described with ASTEdits.
104 //
105 // * Explanation: explanation of the rewrite. This will be displayed to the
106 // user, where possible; for example, in clang-tidy diagnostics.
107 //
108 // However, rules can also consist of (sub)rules, where the first that matches
109 // is applied and the rest are ignored. So, the above components are gathered
110 // as a `Case` and a rule is a list of cases.
111 //
112 // Rule cases have an additional, implicit, component: the parameters. These are
113 // portions of the pattern which are left unspecified, yet bound in the pattern
114 // so that we can reference them in the edits.
115 //
116 // The \c Transformer class can be used to apply the rewrite rule and obtain the
117 // corresponding replacements.
118 struct RewriteRule {
119  struct Case {
120  ast_matchers::internal::DynTypedMatcher Matcher;
123  // Include paths to add to the file affected by this case. These are
124  // bundled with the `Case`, rather than the `RewriteRule`, because each case
125  // might have different associated changes to the includes.
126  std::vector<std::pair<std::string, IncludeFormat>> AddedIncludes;
127  };
128  // We expect RewriteRules will most commonly include only one case.
130 
131  // ID used as the default target of each match. The node described by the
132  // matcher is should always be bound to this id.
133  static constexpr llvm::StringLiteral RootID = "___root___";
134 };
135 
136 /// Convenience function for constructing a simple \c RewriteRule.
137 RewriteRule makeRule(ast_matchers::internal::DynTypedMatcher M,
139  TextGenerator Explanation = nullptr);
140 
141 /// Convenience overload of \c makeRule for common case of only one edit.
142 inline RewriteRule makeRule(ast_matchers::internal::DynTypedMatcher M,
143  ASTEdit Edit,
144  TextGenerator Explanation = nullptr) {
146  Edits.emplace_back(std::move(Edit));
147  return makeRule(std::move(M), std::move(Edits), std::move(Explanation));
148 }
149 
150 /// For every case in Rule, adds an include directive for the given header. The
151 /// common use is assumed to be a rule with only one case. For example, to
152 /// replace a function call and add headers corresponding to the new code, one
153 /// could write:
154 /// \code
155 /// auto R = makeRule(callExpr(callee(functionDecl(hasName("foo")))),
156 /// change(text("bar()")));
157 /// AddInclude(R, "path/to/bar_header.h");
158 /// AddInclude(R, "vector", IncludeFormat::Angled);
159 /// \endcode
160 void addInclude(RewriteRule &Rule, llvm::StringRef Header,
162 
163 /// Applies the first rule whose pattern matches; other rules are ignored. If
164 /// the matchers are independent then order doesn't matter. In that case,
165 /// `applyFirst` is simply joining the set of rules into one.
166 //
167 // `applyFirst` is like an `anyOf` matcher with an edit action attached to each
168 // of its cases. Anywhere you'd use `anyOf(m1.bind("id1"), m2.bind("id2"))` and
169 // then dispatch on those ids in your code for control flow, `applyFirst` lifts
170 // that behavior to the rule level. So, you can write `applyFirst({makeRule(m1,
171 // action1), makeRule(m2, action2), ...});`
172 //
173 // For example, consider a type `T` with a deterministic serialization function,
174 // `serialize()`. For performance reasons, we would like to make it
175 // non-deterministic. Therefore, we want to drop the expectation that
176 // `a.serialize() = b.serialize() iff a = b` (although we'll maintain
177 // `deserialize(a.serialize()) = a`).
178 //
179 // We have three cases to consider (for some equality function, `eq`):
180 // ```
181 // eq(a.serialize(), b.serialize()) --> eq(a,b)
182 // eq(a, b.serialize()) --> eq(deserialize(a), b)
183 // eq(a.serialize(), b) --> eq(a, deserialize(b))
184 // ```
185 //
186 // `applyFirst` allows us to specify each independently:
187 // ```
188 // auto eq_fun = functionDecl(...);
189 // auto method_call = cxxMemberCallExpr(...);
190 //
191 // auto two_calls = callExpr(callee(eq_fun), hasArgument(0, method_call),
192 // hasArgument(1, method_call));
193 // auto left_call =
194 // callExpr(callee(eq_fun), callExpr(hasArgument(0, method_call)));
195 // auto right_call =
196 // callExpr(callee(eq_fun), callExpr(hasArgument(1, method_call)));
197 //
198 // RewriteRule R = applyFirst({makeRule(two_calls, two_calls_action),
199 // makeRule(left_call, left_call_action),
200 // makeRule(right_call, right_call_action)});
201 // ```
203 
204 /// Replaces a portion of the source text with \p Replacement.
206 
207 /// Replaces the entirety of a RewriteRule's match with \p Replacement. For
208 /// example, to replace a function call, one could write:
209 /// \code
210 /// makeRule(callExpr(callee(functionDecl(hasName("foo")))),
211 /// change(text("bar()")))
212 /// \endcode
213 inline ASTEdit change(TextGenerator Replacement) {
214  return change(node(RewriteRule::RootID), std::move(Replacement));
215 }
216 
217 /// Inserts \p Replacement before \p S, leaving the source selected by \S
218 /// unchanged.
220  return change(before(std::move(S)), std::move(Replacement));
221 }
222 
223 /// Inserts \p Replacement after \p S, leaving the source selected by \S
224 /// unchanged.
226  return change(after(std::move(S)), std::move(Replacement));
227 }
228 
229 /// Removes the source selected by \p S.
230 inline ASTEdit remove(RangeSelector S) {
231  return change(std::move(S), text(""));
232 }
233 
234 /// The following three functions are a low-level part of the RewriteRule
235 /// API. We expose them for use in implementing the fixtures that interpret
236 /// RewriteRule, like Transformer and TransfomerTidy, or for more advanced
237 /// users.
238 //
239 // FIXME: These functions are really public, if advanced, elements of the
240 // RewriteRule API. Recast them as such. Or, just declare these functions
241 // public and well-supported and move them out of `detail`.
242 namespace detail {
243 /// Builds a single matcher for the rule, covering all of the rule's cases.
244 /// Only supports Rules whose cases' matchers share the same base "kind"
245 /// (`Stmt`, `Decl`, etc.) Deprecated: use `buildMatchers` instead, which
246 /// supports mixing matchers of different kinds.
247 ast_matchers::internal::DynTypedMatcher buildMatcher(const RewriteRule &Rule);
248 
249 /// Builds a set of matchers that cover the rule (one for each distinct node
250 /// matcher base kind: Stmt, Decl, etc.). Node-matchers for `QualType` and
251 /// `Type` are not permitted, since such nodes carry no source location
252 /// information and are therefore not relevant for rewriting. If any such
253 /// matchers are included, will return an empty vector.
254 std::vector<ast_matchers::internal::DynTypedMatcher>
255 buildMatchers(const RewriteRule &Rule);
256 
257 /// Returns the \c Case of \c Rule that was selected in the match result.
258 /// Assumes a matcher built with \c buildMatcher.
259 const RewriteRule::Case &
261  const RewriteRule &Rule);
262 
263 /// A source "transformation," represented by a character range in the source to
264 /// be replaced and a corresponding replacement string.
267  std::string Replacement;
268 };
269 
270 /// Attempts to translate `Edits`, which are in terms of AST nodes bound in the
271 /// match `Result`, into Transformations, which are in terms of the source code
272 /// text.
273 ///
274 /// Returns an empty vector if any of the edits apply to portions of the source
275 /// that are ineligible for rewriting (certain interactions with macros, for
276 /// example). Fails if any invariants are violated relating to bound nodes in
277 /// the match. However, it does not fail in the case of conflicting edits --
278 /// conflict handling is left to clients. We recommend use of the \c
279 /// AtomicChange or \c Replacements classes for assistance in detecting such
280 /// conflicts.
284 } // namespace detail
285 
286 /// Handles the matcher and callback registration for a single rewrite rule, as
287 /// defined by the arguments of the constructor.
289 public:
290  using ChangeConsumer =
291  std::function<void(Expected<clang::tooling::AtomicChange> Change)>;
292 
293  /// \param Consumer Receives each rewrite or error. Will not necessarily be
294  /// called for each match; for example, if the rewrite is not applicable
295  /// because of macros, but doesn't fail. Note that clients are responsible
296  /// for handling the case that independent \c AtomicChanges conflict with each
297  /// other.
299  : Rule(std::move(Rule)), Consumer(std::move(Consumer)) {}
300 
301  /// N.B. Passes `this` pointer to `MatchFinder`. So, this object should not
302  /// be moved after this call.
303  void registerMatchers(ast_matchers::MatchFinder *MatchFinder);
304 
305  /// Not called directly by users -- called by the framework, via base class
306  /// pointer.
307  void run(const ast_matchers::MatchFinder::MatchResult &Result) override;
308 
309 private:
310  RewriteRule Rule;
311  /// Receives each successful rewrites as an \c AtomicChange.
312  ChangeConsumer Consumer;
313 };
314 } // namespace tooling
315 } // namespace clang
316 
317 #endif // LLVM_CLANG_TOOLING_REFACTOR_TRANSFORMER_H_
A class to allow finding matches over the Clang AST.
std::vector< ast_matchers::internal::DynTypedMatcher > buildMatchers(const RewriteRule &Rule)
Builds a set of matchers that cover the rule (one for each distinct node matcher base kind: Stmt...
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
RangeSelector before(RangeSelector Selector)
Selects the (empty) range [B,B) when Selector selects the range [B,E).
TextGenerator Note
Definition: Transformer.h:86
ast_matchers::internal::DynTypedMatcher buildMatcher(const RewriteRule &Rule)
Builds a single matcher for the rule, covering all of the rule&#39;s cases.
SmallVector< Case, 1 > Cases
Definition: Transformer.h:129
std::function< void(Expected< clang::tooling::AtomicChange > Change)> ChangeConsumer
Definition: Transformer.h:291
Transformer(RewriteRule Rule, ChangeConsumer Consumer)
Definition: Transformer.h:298
Definition: Format.h:2327
std::function< Expected< CharSourceRange >(const ast_matchers::MatchFinder::MatchResult &)> RangeSelector
Definition: RangeSelector.h:27
SmallVector< ASTEdit, 1 > Edits
Definition: Transformer.h:121
ASTEdit insertAfter(RangeSelector S, TextGenerator Replacement)
Inserts Replacement after S, leaving the source selected by unchanged.
Definition: Transformer.h:225
ASTEdit insertBefore(RangeSelector S, TextGenerator Replacement)
Inserts Replacement before S, leaving the source selected by unchanged.
Definition: Transformer.h:219
RangeSelector node(std::string ID)
Selects a node, including trailing semicolon (for non-expression statements).
A text replacement.
Definition: Replacement.h:83
RangeSelector TargetRange
Definition: Transformer.h:84
Represents a character-granular source range.
ast_matchers::internal::DynTypedMatcher Matcher
Definition: Transformer.h:120
Contains all information for a given match.
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:40
static constexpr llvm::StringLiteral RootID
Definition: Transformer.h:133
RangeSelector after(RangeSelector Selector)
Selects the the point immediately following Selector.
Dataflow Directional Tag Classes.
Handles the matcher and callback registration for a single rewrite rule, as defined by the arguments ...
Definition: Transformer.h:288
std::vector< std::pair< std::string, IncludeFormat > > AddedIncludes
Definition: Transformer.h:126
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
ASTEdit change(RangeSelector Target, TextGenerator Replacement)
Replaces a portion of the source text with Replacement.
Definition: Transformer.cpp:64
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 a combinator library supporting the definition of selectors, which select source ranges based...
A source "transformation," represented by a character range in the source to be replaced and a corres...
Definition: Transformer.h:265
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.
Called when the Match registered for it was successfully found in the AST.
TextGenerator text(std::string M)
Wraps a string as a TextGenerator.
Definition: Transformer.h:42