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_REWRITERULE_H 16 #define LLVM_CLANG_TOOLING_TRANSFORMER_REWRITERULE_H 17 18 #include "clang/ASTMatchers/ASTMatchFinder.h" 19 #include "clang/ASTMatchers/ASTMatchers.h" 20 #include "clang/ASTMatchers/ASTMatchersInternal.h" 21 #include "clang/Tooling/Refactoring/AtomicChange.h" 22 #include "clang/Tooling/Transformer/MatchConsumer.h" 23 #include "clang/Tooling/Transformer/RangeSelector.h" 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 // Specifies how to interpret an edit. 35 enum class EditKind { 36 // Edits a source range in the file. 37 Range, 38 // Inserts an include in the file. The `Replacement` field is the name of the 39 // newly included file. 40 AddInclude, 41 }; 42 43 /// A concrete description of a source edit, represented by a character range in 44 /// the source to be replaced and a corresponding replacement string. 45 struct Edit { 46 EditKind Kind = EditKind::Range; 47 CharSourceRange Range; 48 std::string Replacement; 49 llvm::Any Metadata; 50 }; 51 52 /// Format of the path in an include directive -- angle brackets or quotes. 53 enum class IncludeFormat { 54 Quoted, 55 Angled, 56 }; 57 58 /// Maps a match result to a list of concrete edits (with possible 59 /// failure). This type is a building block of rewrite rules, but users will 60 /// generally work in terms of `ASTEdit`s (below) rather than directly in terms 61 /// of `EditGenerator`. 62 using EditGenerator = MatchConsumer<llvm::SmallVector<Edit, 1>>; 63 64 template <typename T> using Generator = std::shared_ptr<MatchComputation<T>>; 65 66 using TextGenerator = Generator<std::string>; 67 68 using AnyGenerator = MatchConsumer<llvm::Any>; 69 70 // Description of a source-code edit, expressed in terms of an AST node. 71 // Includes: an ID for the (bound) node, a selector for source related to the 72 // node, a replacement and, optionally, an explanation for the edit. 73 // 74 // * Target: the source code impacted by the rule. This identifies an AST node, 75 // or part thereof (\c Part), whose source range indicates the extent of the 76 // replacement applied by the replacement term. By default, the extent is the 77 // node matched by the pattern term (\c NodePart::Node). Target's are typed 78 // (\c Kind), which guides the determination of the node extent. 79 // 80 // * Replacement: a function that produces a replacement string for the target, 81 // based on the match result. 82 // 83 // * Note: (optional) a note specifically for this edit, potentially referencing 84 // elements of the match. This will be displayed to the user, where possible; 85 // for example, in clang-tidy diagnostics. Use of notes should be rare -- 86 // explanations of the entire rewrite should be set in the rule 87 // (`RewriteRule::Explanation`) instead. Notes serve the rare cases wherein 88 // edit-specific diagnostics are required. 89 // 90 // `ASTEdit` should be built using the `change` convenience functions. For 91 // example, 92 // \code 93 // changeTo(name(fun), cat("Frodo")) 94 // \endcode 95 // Or, if we use Stencil for the TextGenerator: 96 // \code 97 // using stencil::cat; 98 // changeTo(statement(thenNode), cat("{", thenNode, "}")) 99 // changeTo(callArgs(call), cat(x, ",", y)) 100 // \endcode 101 // Or, if you are changing the node corresponding to the rule's matcher, you can 102 // use the single-argument override of \c change: 103 // \code 104 // changeTo(cat("different_expr")) 105 // \endcode 106 struct ASTEdit { 107 EditKind Kind = EditKind::Range; 108 RangeSelector TargetRange; 109 TextGenerator Replacement; 110 TextGenerator Note; 111 // Not all transformations will want or need to attach metadata and therefore 112 // should not be required to do so. 113 AnyGenerator Metadata = [](const ast_matchers::MatchFinder::MatchResult &) 114 -> llvm::Expected<llvm::Any> { 115 return llvm::Expected<llvm::Any>(llvm::Any()); 116 }; 117 }; 118 119 /// Generates a single (specified) edit. 120 EditGenerator edit(ASTEdit E); 121 122 /// Lifts a list of `ASTEdit`s into an `EditGenerator`. 123 /// 124 /// The `EditGenerator` will return an empty vector if any of the edits apply to 125 /// portions of the source that are ineligible for rewriting (certain 126 /// interactions with macros, for example) and it will fail if any invariants 127 /// are violated relating to bound nodes in the match. However, it does not 128 /// fail in the case of conflicting edits -- conflict handling is left to 129 /// clients. We recommend use of the \c AtomicChange or \c Replacements classes 130 /// for assistance in detecting such conflicts. 131 EditGenerator editList(llvm::SmallVector<ASTEdit, 1> Edits); 132 133 /// Generates no edits. 134 inline EditGenerator noEdits() { return editList({}); } 135 136 /// Generates a single, no-op edit anchored at the start location of the 137 /// specified range. A `noopEdit` may be preferred over `noEdits` to associate a 138 /// diagnostic `Explanation` with the rule. 139 EditGenerator noopEdit(RangeSelector Anchor); 140 141 /// Version of `ifBound` specialized to `ASTEdit`. 142 inline EditGenerator ifBound(std::string ID, ASTEdit TrueEdit, 143 ASTEdit FalseEdit) { 144 return ifBound(std::move(ID), edit(std::move(TrueEdit)), 145 edit(std::move(FalseEdit))); 146 } 147 148 /// Version of `ifBound` that has no "False" branch. If the node is not bound, 149 /// then no edits are produced. 150 inline EditGenerator ifBound(std::string ID, ASTEdit TrueEdit) { 151 return ifBound(std::move(ID), edit(std::move(TrueEdit)), noEdits()); 152 } 153 154 /// Flattens a list of generators into a single generator whose elements are the 155 /// concatenation of the results of the argument generators. 156 EditGenerator flattenVector(SmallVector<EditGenerator, 2> Generators); 157 158 namespace detail { 159 /// Helper function to construct an \c EditGenerator. Overloaded for common 160 /// cases so that user doesn't need to specify which factory function to 161 /// use. This pattern gives benefits similar to implicit constructors, while 162 /// maintaing a higher degree of explicitness. 163 inline EditGenerator injectEdits(ASTEdit E) { return edit(std::move(E)); } 164 inline EditGenerator injectEdits(EditGenerator G) { return G; } 165 } // namespace detail 166 167 template <typename... Ts> EditGenerator flatten(Ts &&...Edits) { 168 return flattenVector({detail::injectEdits(std::forward<Ts>(Edits))...}); 169 } 170 171 // Every rewrite rule is triggered by a match against some AST node. 172 // Transformer guarantees that this ID is bound to the triggering node whenever 173 // a rewrite rule is applied. 174 extern const char RootID[]; 175 176 /// Replaces a portion of the source text with \p Replacement. 177 ASTEdit changeTo(RangeSelector Target, TextGenerator Replacement); 178 /// DEPRECATED: use \c changeTo. 179 inline ASTEdit change(RangeSelector Target, TextGenerator Replacement) { 180 return changeTo(std::move(Target), std::move(Replacement)); 181 } 182 183 /// Replaces the entirety of a RewriteRule's match with \p Replacement. For 184 /// example, to replace a function call, one could write: 185 /// \code 186 /// makeRule(callExpr(callee(functionDecl(hasName("foo")))), 187 /// changeTo(cat("bar()"))) 188 /// \endcode 189 inline ASTEdit changeTo(TextGenerator Replacement) { 190 return changeTo(node(RootID), std::move(Replacement)); 191 } 192 /// DEPRECATED: use \c changeTo. 193 inline ASTEdit change(TextGenerator Replacement) { 194 return changeTo(std::move(Replacement)); 195 } 196 197 /// Inserts \p Replacement before \p S, leaving the source selected by \S 198 /// unchanged. 199 inline ASTEdit insertBefore(RangeSelector S, TextGenerator Replacement) { 200 return changeTo(before(std::move(S)), std::move(Replacement)); 201 } 202 203 /// Inserts \p Replacement after \p S, leaving the source selected by \S 204 /// unchanged. 205 inline ASTEdit insertAfter(RangeSelector S, TextGenerator Replacement) { 206 return changeTo(after(std::move(S)), std::move(Replacement)); 207 } 208 209 /// Removes the source selected by \p S. 210 ASTEdit remove(RangeSelector S); 211 212 /// Adds an include directive for the given header to the file of `Target`. The 213 /// particular location specified by `Target` is ignored. 214 ASTEdit addInclude(RangeSelector Target, StringRef Header, 215 IncludeFormat Format = IncludeFormat::Quoted); 216 217 /// Adds an include directive for the given header to the file associated with 218 /// `RootID`. If `RootID` matches inside a macro expansion, will add the 219 /// directive to the file in which the macro was expanded (as opposed to the 220 /// file in which the macro is defined). 221 inline ASTEdit addInclude(StringRef Header, 222 IncludeFormat Format = IncludeFormat::Quoted) { 223 return addInclude(expansion(node(RootID)), Header, Format); 224 } 225 226 // FIXME: If `Metadata` returns an `llvm::Expected<T>` the `AnyGenerator` will 227 // construct an `llvm::Expected<llvm::Any>` where no error is present but the 228 // `llvm::Any` holds the error. This is unlikely but potentially surprising. 229 // Perhaps the `llvm::Expected` should be unwrapped, or perhaps this should be a 230 // compile-time error. No solution here is perfect. 231 // 232 // Note: This function template accepts any type callable with a MatchResult 233 // rather than a `std::function` because the return-type needs to be deduced. If 234 // it accepted a `std::function<R(MatchResult)>`, lambdas or other callable 235 // types would not be able to deduce `R`, and users would be forced to specify 236 // explicitly the type they intended to return by wrapping the lambda at the 237 // call-site. 238 template <typename Callable> 239 inline ASTEdit withMetadata(ASTEdit Edit, Callable Metadata) { 240 Edit.Metadata = 241 [Gen = std::move(Metadata)]( 242 const ast_matchers::MatchFinder::MatchResult &R) -> llvm::Any { 243 return Gen(R); 244 }; 245 246 return Edit; 247 } 248 249 /// Assuming that the inner range is enclosed by the outer range, creates 250 /// precision edits to remove the parts of the outer range that are not included 251 /// in the inner range. 252 inline EditGenerator shrinkTo(RangeSelector outer, RangeSelector inner) { 253 return editList({remove(enclose(before(outer), before(inner))), 254 remove(enclose(after(inner), after(outer)))}); 255 } 256 257 /// Description of a source-code transformation. 258 // 259 // A *rewrite rule* describes a transformation of source code. A simple rule 260 // contains each of the following components: 261 // 262 // * Matcher: the pattern term, expressed as clang matchers (with Transformer 263 // extensions). 264 // 265 // * Edits: a set of Edits to the source code, described with ASTEdits. 266 // 267 // However, rules can also consist of (sub)rules, where the first that matches 268 // is applied and the rest are ignored. So, the above components together form 269 // a logical "case" and a rule is a sequence of cases. 270 // 271 // Rule cases have an additional, implicit, component: the parameters. These are 272 // portions of the pattern which are left unspecified, yet bound in the pattern 273 // so that we can reference them in the edits. 274 // 275 // The \c Transformer class can be used to apply the rewrite rule and obtain the 276 // corresponding replacements. 277 struct RewriteRuleBase { 278 struct Case { 279 ast_matchers::internal::DynTypedMatcher Matcher; 280 EditGenerator Edits; 281 }; 282 // We expect RewriteRules will most commonly include only one case. 283 SmallVector<Case, 1> Cases; 284 }; 285 286 /// A source-code transformation with accompanying metadata. 287 /// 288 /// When a case of the rule matches, the \c Transformer invokes the 289 /// corresponding metadata generator and provides it alongside the edits. 290 template <typename MetadataT> struct RewriteRuleWith : RewriteRuleBase { 291 SmallVector<Generator<MetadataT>, 1> Metadata; 292 }; 293 294 template <> struct RewriteRuleWith<void> : RewriteRuleBase {}; 295 296 using RewriteRule = RewriteRuleWith<void>; 297 298 namespace detail { 299 300 RewriteRule makeRule(ast_matchers::internal::DynTypedMatcher M, 301 EditGenerator Edits); 302 303 template <typename MetadataT> 304 RewriteRuleWith<MetadataT> makeRule(ast_matchers::internal::DynTypedMatcher M, 305 EditGenerator Edits, 306 Generator<MetadataT> Metadata) { 307 RewriteRuleWith<MetadataT> R; 308 R.Cases = {{std::move(M), std::move(Edits)}}; 309 R.Metadata = {std::move(Metadata)}; 310 return R; 311 } 312 313 inline EditGenerator makeEditGenerator(EditGenerator Edits) { return Edits; } 314 EditGenerator makeEditGenerator(llvm::SmallVector<ASTEdit, 1> Edits); 315 EditGenerator makeEditGenerator(ASTEdit Edit); 316 317 } // namespace detail 318 319 /// Constructs a simple \c RewriteRule. \c Edits can be an \c EditGenerator, 320 /// multiple \c ASTEdits, or a single \c ASTEdit. 321 /// @{ 322 template <int &..., typename EditsT> 323 RewriteRule makeRule(ast_matchers::internal::DynTypedMatcher M, 324 EditsT &&Edits) { 325 return detail::makeRule( 326 std::move(M), detail::makeEditGenerator(std::forward<EditsT>(Edits))); 327 } 328 329 RewriteRule makeRule(ast_matchers::internal::DynTypedMatcher M, 330 std::initializer_list<ASTEdit> Edits); 331 /// @} 332 333 /// Overloads of \c makeRule that also generate metadata when matching. 334 /// @{ 335 template <typename MetadataT, int &..., typename EditsT> 336 RewriteRuleWith<MetadataT> makeRule(ast_matchers::internal::DynTypedMatcher M, 337 EditsT &&Edits, 338 Generator<MetadataT> Metadata) { 339 return detail::makeRule( 340 std::move(M), detail::makeEditGenerator(std::forward<EditsT>(Edits)), 341 std::move(Metadata)); 342 } 343 344 template <typename MetadataT> 345 RewriteRuleWith<MetadataT> makeRule(ast_matchers::internal::DynTypedMatcher M, 346 std::initializer_list<ASTEdit> Edits, 347 Generator<MetadataT> Metadata) { 348 return detail::makeRule(std::move(M), 349 detail::makeEditGenerator(std::move(Edits)), 350 std::move(Metadata)); 351 } 352 /// @} 353 354 /// For every case in Rule, adds an include directive for the given header. The 355 /// common use is assumed to be a rule with only one case. For example, to 356 /// replace a function call and add headers corresponding to the new code, one 357 /// could write: 358 /// \code 359 /// auto R = makeRule(callExpr(callee(functionDecl(hasName("foo")))), 360 /// changeTo(cat("bar()"))); 361 /// addInclude(R, "path/to/bar_header.h"); 362 /// addInclude(R, "vector", IncludeFormat::Angled); 363 /// \endcode 364 void addInclude(RewriteRuleBase &Rule, llvm::StringRef Header, 365 IncludeFormat Format = IncludeFormat::Quoted); 366 367 /// Applies the first rule whose pattern matches; other rules are ignored. If 368 /// the matchers are independent then order doesn't matter. In that case, 369 /// `applyFirst` is simply joining the set of rules into one. 370 // 371 // `applyFirst` is like an `anyOf` matcher with an edit action attached to each 372 // of its cases. Anywhere you'd use `anyOf(m1.bind("id1"), m2.bind("id2"))` and 373 // then dispatch on those ids in your code for control flow, `applyFirst` lifts 374 // that behavior to the rule level. So, you can write `applyFirst({makeRule(m1, 375 // action1), makeRule(m2, action2), ...});` 376 // 377 // For example, consider a type `T` with a deterministic serialization function, 378 // `serialize()`. For performance reasons, we would like to make it 379 // non-deterministic. Therefore, we want to drop the expectation that 380 // `a.serialize() = b.serialize() iff a = b` (although we'll maintain 381 // `deserialize(a.serialize()) = a`). 382 // 383 // We have three cases to consider (for some equality function, `eq`): 384 // ``` 385 // eq(a.serialize(), b.serialize()) --> eq(a,b) 386 // eq(a, b.serialize()) --> eq(deserialize(a), b) 387 // eq(a.serialize(), b) --> eq(a, deserialize(b)) 388 // ``` 389 // 390 // `applyFirst` allows us to specify each independently: 391 // ``` 392 // auto eq_fun = functionDecl(...); 393 // auto method_call = cxxMemberCallExpr(...); 394 // 395 // auto two_calls = callExpr(callee(eq_fun), hasArgument(0, method_call), 396 // hasArgument(1, method_call)); 397 // auto left_call = 398 // callExpr(callee(eq_fun), callExpr(hasArgument(0, method_call))); 399 // auto right_call = 400 // callExpr(callee(eq_fun), callExpr(hasArgument(1, method_call))); 401 // 402 // RewriteRule R = applyFirst({makeRule(two_calls, two_calls_action), 403 // makeRule(left_call, left_call_action), 404 // makeRule(right_call, right_call_action)}); 405 // ``` 406 /// @{ 407 template <typename MetadataT> 408 RewriteRuleWith<MetadataT> 409 applyFirst(ArrayRef<RewriteRuleWith<MetadataT>> Rules) { 410 RewriteRuleWith<MetadataT> R; 411 for (auto &Rule : Rules) { 412 assert(Rule.Cases.size() == Rule.Metadata.size() && 413 "mis-match in case and metadata array size"); 414 R.Cases.append(Rule.Cases.begin(), Rule.Cases.end()); 415 R.Metadata.append(Rule.Metadata.begin(), Rule.Metadata.end()); 416 } 417 return R; 418 } 419 420 template <> 421 RewriteRuleWith<void> applyFirst(ArrayRef<RewriteRuleWith<void>> Rules); 422 423 template <typename MetadataT> 424 RewriteRuleWith<MetadataT> 425 applyFirst(const std::vector<RewriteRuleWith<MetadataT>> &Rules) { 426 return applyFirst(llvm::makeArrayRef(Rules)); 427 } 428 429 template <typename MetadataT> 430 RewriteRuleWith<MetadataT> 431 applyFirst(std::initializer_list<RewriteRuleWith<MetadataT>> Rules) { 432 return applyFirst(llvm::makeArrayRef(Rules.begin(), Rules.end())); 433 } 434 /// @} 435 436 /// Converts a \c RewriteRuleWith<T> to a \c RewriteRule by stripping off the 437 /// metadata generators. 438 template <int &..., typename MetadataT> 439 std::enable_if_t<!std::is_same<MetadataT, void>::value, RewriteRule> 440 stripMetadata(RewriteRuleWith<MetadataT> Rule) { 441 RewriteRule R; 442 R.Cases = std::move(Rule.Cases); 443 return R; 444 } 445 446 /// Applies `Rule` to all descendants of the node bound to `NodeId`. `Rule` can 447 /// refer to nodes bound by the calling rule. `Rule` is not applied to the node 448 /// itself. 449 /// 450 /// For example, 451 /// ``` 452 /// auto InlineX = 453 /// makeRule(declRefExpr(to(varDecl(hasName("x")))), changeTo(cat("3"))); 454 /// makeRule(functionDecl(hasName("f"), hasBody(stmt().bind("body"))).bind("f"), 455 /// flatten( 456 /// changeTo(name("f"), cat("newName")), 457 /// rewriteDescendants("body", InlineX))); 458 /// ``` 459 /// Here, we find the function `f`, change its name to `newName` and change all 460 /// appearances of `x` in its body to `3`. 461 EditGenerator rewriteDescendants(std::string NodeId, RewriteRule Rule); 462 463 /// The following three functions are a low-level part of the RewriteRule 464 /// API. We expose them for use in implementing the fixtures that interpret 465 /// RewriteRule, like Transformer and TransfomerTidy, or for more advanced 466 /// users. 467 // 468 // FIXME: These functions are really public, if advanced, elements of the 469 // RewriteRule API. Recast them as such. Or, just declare these functions 470 // public and well-supported and move them out of `detail`. 471 namespace detail { 472 /// The following overload set is a version of `rewriteDescendants` that 473 /// operates directly on the AST, rather than generating a Transformer 474 /// combinator. It applies `Rule` to all descendants of `Node`, although not 475 /// `Node` itself. `Rule` can refer to nodes bound in `Result`. 476 /// 477 /// For example, assuming that "body" is bound to a function body in MatchResult 478 /// `Results`, this will produce edits to change all appearances of `x` in that 479 /// body to `3`. 480 /// ``` 481 /// auto InlineX = 482 /// makeRule(declRefExpr(to(varDecl(hasName("x")))), changeTo(cat("3"))); 483 /// const auto *Node = Results.Nodes.getNodeAs<Stmt>("body"); 484 /// auto Edits = rewriteDescendants(*Node, InlineX, Results); 485 /// ``` 486 /// @{ 487 llvm::Expected<SmallVector<Edit, 1>> 488 rewriteDescendants(const Decl &Node, RewriteRule Rule, 489 const ast_matchers::MatchFinder::MatchResult &Result); 490 491 llvm::Expected<SmallVector<Edit, 1>> 492 rewriteDescendants(const Stmt &Node, RewriteRule Rule, 493 const ast_matchers::MatchFinder::MatchResult &Result); 494 495 llvm::Expected<SmallVector<Edit, 1>> 496 rewriteDescendants(const TypeLoc &Node, RewriteRule Rule, 497 const ast_matchers::MatchFinder::MatchResult &Result); 498 499 llvm::Expected<SmallVector<Edit, 1>> 500 rewriteDescendants(const DynTypedNode &Node, RewriteRule Rule, 501 const ast_matchers::MatchFinder::MatchResult &Result); 502 /// @} 503 504 /// Builds a single matcher for the rule, covering all of the rule's cases. 505 /// Only supports Rules whose cases' matchers share the same base "kind" 506 /// (`Stmt`, `Decl`, etc.) Deprecated: use `buildMatchers` instead, which 507 /// supports mixing matchers of different kinds. 508 ast_matchers::internal::DynTypedMatcher 509 buildMatcher(const RewriteRuleBase &Rule); 510 511 /// Builds a set of matchers that cover the rule. 512 /// 513 /// One matcher is built for each distinct node matcher base kind: Stmt, Decl, 514 /// etc. Node-matchers for `QualType` and `Type` are not permitted, since such 515 /// nodes carry no source location information and are therefore not relevant 516 /// for rewriting. If any such matchers are included, will return an empty 517 /// vector. 518 std::vector<ast_matchers::internal::DynTypedMatcher> 519 buildMatchers(const RewriteRuleBase &Rule); 520 521 /// Gets the beginning location of the source matched by a rewrite rule. If the 522 /// match occurs within a macro expansion, returns the beginning of the 523 /// expansion point. `Result` must come from the matching of a rewrite rule. 524 SourceLocation 525 getRuleMatchLoc(const ast_matchers::MatchFinder::MatchResult &Result); 526 527 /// Returns the index of the \c Case of \c Rule that was selected in the match 528 /// result. Assumes a matcher built with \c buildMatcher. 529 size_t findSelectedCase(const ast_matchers::MatchFinder::MatchResult &Result, 530 const RewriteRuleBase &Rule); 531 } // namespace detail 532 } // namespace transformer 533 } // namespace clang 534 535 #endif // LLVM_CLANG_TOOLING_TRANSFORMER_REWRITERULE_H 536