1//===--- Refactoring.h - Framework for clang refactoring tools --*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9//
10//  Interfaces supporting refactorings that span multiple translation units.
11//  While single translation unit refactorings are supported via the Rewriter,
12//  when refactoring multiple translation units changes must be stored in a
13//  SourceManager independent form, duplicate changes need to be removed, and
14//  all changes must be applied at once at the end of the refactoring so that
15//  the code is always parseable.
16//
17//===----------------------------------------------------------------------===//
18
19#ifndef LLVM_CLANG_TOOLING_REFACTORING_H
20#define LLVM_CLANG_TOOLING_REFACTORING_H
21
22#include "clang/Basic/SourceLocation.h"
23#include "clang/Tooling/Tooling.h"
24#include "llvm/ADT/StringRef.h"
25#include <set>
26#include <string>
27
28namespace clang {
29
30class Rewriter;
31class SourceLocation;
32
33namespace tooling {
34
35/// \brief A source range independent of the \c SourceManager.
36class Range {
37public:
38  Range() : Offset(0), Length(0) {}
39  Range(unsigned Offset, unsigned Length) : Offset(Offset), Length(Length) {}
40
41  /// \brief Accessors.
42  /// @{
43  unsigned getOffset() const { return Offset; }
44  unsigned getLength() const { return Length; }
45  /// @}
46
47  /// \name Range Predicates
48  /// @{
49  /// \brief Whether this range overlaps with \p RHS or not.
50  bool overlapsWith(Range RHS) const {
51    return Offset + Length > RHS.Offset && Offset < RHS.Offset + RHS.Length;
52  }
53
54  /// \brief Whether this range contains \p RHS or not.
55  bool contains(Range RHS) const {
56    return RHS.Offset >= Offset &&
57           (RHS.Offset + RHS.Length) <= (Offset + Length);
58  }
59  /// @}
60
61private:
62  unsigned Offset;
63  unsigned Length;
64};
65
66/// \brief A text replacement.
67///
68/// Represents a SourceManager independent replacement of a range of text in a
69/// specific file.
70class Replacement {
71public:
72  /// \brief Creates an invalid (not applicable) replacement.
73  Replacement();
74
75  /// \brief Creates a replacement of the range [Offset, Offset+Length) in
76  /// FilePath with ReplacementText.
77  ///
78  /// \param FilePath A source file accessible via a SourceManager.
79  /// \param Offset The byte offset of the start of the range in the file.
80  /// \param Length The length of the range in bytes.
81  Replacement(StringRef FilePath, unsigned Offset,
82              unsigned Length, StringRef ReplacementText);
83
84  /// \brief Creates a Replacement of the range [Start, Start+Length) with
85  /// ReplacementText.
86  Replacement(const SourceManager &Sources, SourceLocation Start, unsigned Length,
87              StringRef ReplacementText);
88
89  /// \brief Creates a Replacement of the given range with ReplacementText.
90  Replacement(const SourceManager &Sources, const CharSourceRange &Range,
91              StringRef ReplacementText);
92
93  /// \brief Creates a Replacement of the node with ReplacementText.
94  template <typename Node>
95  Replacement(const SourceManager &Sources, const Node &NodeToReplace,
96              StringRef ReplacementText);
97
98  /// \brief Returns whether this replacement can be applied to a file.
99  ///
100  /// Only replacements that are in a valid file can be applied.
101  bool isApplicable() const;
102
103  /// \brief Accessors.
104  /// @{
105  StringRef getFilePath() const { return FilePath; }
106  unsigned getOffset() const { return ReplacementRange.getOffset(); }
107  unsigned getLength() const { return ReplacementRange.getLength(); }
108  StringRef getReplacementText() const { return ReplacementText; }
109  /// @}
110
111  /// \brief Applies the replacement on the Rewriter.
112  bool apply(Rewriter &Rewrite) const;
113
114  /// \brief Returns a human readable string representation.
115  std::string toString() const;
116
117 private:
118  void setFromSourceLocation(const SourceManager &Sources, SourceLocation Start,
119                             unsigned Length, StringRef ReplacementText);
120  void setFromSourceRange(const SourceManager &Sources,
121                          const CharSourceRange &Range,
122                          StringRef ReplacementText);
123
124  std::string FilePath;
125  Range ReplacementRange;
126  std::string ReplacementText;
127};
128
129/// \brief Less-than operator between two Replacements.
130bool operator<(const Replacement &LHS, const Replacement &RHS);
131
132/// \brief Equal-to operator between two Replacements.
133bool operator==(const Replacement &LHS, const Replacement &RHS);
134
135/// \brief A set of Replacements.
136/// FIXME: Change to a vector and deduplicate in the RefactoringTool.
137typedef std::set<Replacement> Replacements;
138
139/// \brief Apply all replacements in \p Replaces to the Rewriter \p Rewrite.
140///
141/// Replacement applications happen independently of the success of
142/// other applications.
143///
144/// \returns true if all replacements apply. false otherwise.
145bool applyAllReplacements(const Replacements &Replaces, Rewriter &Rewrite);
146
147/// \brief Apply all replacements in \p Replaces to the Rewriter \p Rewrite.
148///
149/// Replacement applications happen independently of the success of
150/// other applications.
151///
152/// \returns true if all replacements apply. false otherwise.
153bool applyAllReplacements(const std::vector<Replacement> &Replaces,
154                          Rewriter &Rewrite);
155
156/// \brief Applies all replacements in \p Replaces to \p Code.
157///
158/// This completely ignores the path stored in each replacement. If one or more
159/// replacements cannot be applied, this returns an empty \c string.
160std::string applyAllReplacements(StringRef Code, const Replacements &Replaces);
161
162/// \brief Calculates how a code \p Position is shifted when \p Replaces are
163/// applied.
164unsigned shiftedCodePosition(const Replacements& Replaces, unsigned Position);
165
166/// \brief Calculates how a code \p Position is shifted when \p Replaces are
167/// applied.
168///
169/// \pre Replaces[i].getOffset() <= Replaces[i+1].getOffset().
170unsigned shiftedCodePosition(const std::vector<Replacement> &Replaces,
171                             unsigned Position);
172
173/// \brief Removes duplicate Replacements and reports if Replacements conflict
174/// with one another.
175///
176/// \post Replaces[i].getOffset() <= Replaces[i+1].getOffset().
177///
178/// This function sorts \p Replaces so that conflicts can be reported simply by
179/// offset into \p Replaces and number of elements in the conflict.
180void deduplicate(std::vector<Replacement> &Replaces,
181                 std::vector<Range> &Conflicts);
182
183/// \brief Collection of Replacements generated from a single translation unit.
184struct TranslationUnitReplacements {
185  /// Name of the main source for the translation unit.
186  std::string MainSourceFile;
187
188  /// A freeform chunk of text to describe the context of the replacements.
189  /// Will be printed, for example, when detecting conflicts during replacement
190  /// deduplication.
191  std::string Context;
192
193  std::vector<Replacement> Replacements;
194};
195
196/// \brief A tool to run refactorings.
197///
198/// This is a refactoring specific version of \see ClangTool. FrontendActions
199/// passed to run() and runAndSave() should add replacements to
200/// getReplacements().
201class RefactoringTool : public ClangTool {
202public:
203  /// \see ClangTool::ClangTool.
204  RefactoringTool(const CompilationDatabase &Compilations,
205                  ArrayRef<std::string> SourcePaths);
206
207  /// \brief Returns the set of replacements to which replacements should
208  /// be added during the run of the tool.
209  Replacements &getReplacements();
210
211  /// \brief Call run(), apply all generated replacements, and immediately save
212  /// the results to disk.
213  ///
214  /// \returns 0 upon success. Non-zero upon failure.
215  int runAndSave(FrontendActionFactory *ActionFactory);
216
217  /// \brief Apply all stored replacements to the given Rewriter.
218  ///
219  /// Replacement applications happen independently of the success of other
220  /// applications.
221  ///
222  /// \returns true if all replacements apply. false otherwise.
223  bool applyAllReplacements(Rewriter &Rewrite);
224
225private:
226  /// \brief Write all refactored files to disk.
227  int saveRewrittenFiles(Rewriter &Rewrite);
228
229private:
230  Replacements Replace;
231};
232
233template <typename Node>
234Replacement::Replacement(const SourceManager &Sources,
235                         const Node &NodeToReplace, StringRef ReplacementText) {
236  const CharSourceRange Range =
237      CharSourceRange::getTokenRange(NodeToReplace->getSourceRange());
238  setFromSourceRange(Sources, Range, ReplacementText);
239}
240
241} // end namespace tooling
242} // end namespace clang
243
244#endif // end namespace LLVM_CLANG_TOOLING_REFACTORING_H
245