Coverage Report

Created: 2020-09-19 12:23

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