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