Coverage Report

Created: 2022-07-16 07:03

/Users/buildslave/jenkins/workspace/coverage/llvm-project/clang/include/clang/Tooling/Transformer/RewriteRule.h
Line
Count
Source (jump to first uncovered line)
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
124
      -> llvm::Expected<llvm::Any> {
115
124
    return llvm::Expected<llvm::Any>(llvm::Any());
116
124
  };
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
7
inline EditGenerator injectEdits(ASTEdit E) { return edit(std::move(E)); }
164
5
inline EditGenerator injectEdits(EditGenerator G) { return G; }
165
} // namespace detail
166
167
2
template <typename... Ts> EditGenerator flatten(Ts &&...Edits) {
168
2
  return flattenVector({detail::injectEdits(std::forward<Ts>(Edits))...});
169
2
}
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
4
inline ASTEdit change(RangeSelector Target, TextGenerator Replacement) {
180
4
  return changeTo(std::move(Target), std::move(Replacement));
181
4
}
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
0
inline ASTEdit change(TextGenerator Replacement) {
194
0
  return changeTo(std::move(Replacement));
195
0
}
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
4
                          IncludeFormat Format = IncludeFormat::Quoted) {
223
4
  return addInclude(expansion(node(RootID)), Header, Format);
224
4
}
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