1 //===--- Replacement.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 // Classes 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_CORE_REPLACEMENT_H
20 #define LLVM_CLANG_TOOLING_CORE_REPLACEMENT_H
21
22 #include "clang/Basic/LangOptions.h"
23 #include "clang/Basic/SourceLocation.h"
24 #include "llvm/ADT/StringRef.h"
25 #include <set>
26 #include <string>
27 #include <vector>
28
29 namespace clang {
30
31 class Rewriter;
32
33 namespace tooling {
34
35 /// \brief A source range independent of the \c SourceManager.
36 class Range {
37 public:
Range()38 Range() : Offset(0), Length(0) {}
Range(unsigned Offset,unsigned Length)39 Range(unsigned Offset, unsigned Length) : Offset(Offset), Length(Length) {}
40
41 /// \brief Accessors.
42 /// @{
getOffset()43 unsigned getOffset() const { return Offset; }
getLength()44 unsigned getLength() const { return Length; }
45 /// @}
46
47 /// \name Range Predicates
48 /// @{
49 /// \brief Whether this range overlaps with \p RHS or not.
overlapsWith(Range RHS)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.
contains(Range RHS)55 bool contains(Range RHS) const {
56 return RHS.Offset >= Offset &&
57 (RHS.Offset + RHS.Length) <= (Offset + Length);
58 }
59 /// @}
60
61 private:
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.
70 class Replacement {
71 public:
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, unsigned Length,
82 StringRef ReplacementText);
83
84 /// \brief Creates a Replacement of the range [Start, Start+Length) with
85 /// ReplacementText.
86 Replacement(const SourceManager &Sources, SourceLocation Start,
87 unsigned Length, 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 const LangOptions &LangOpts = LangOptions());
93
94 /// \brief Creates a Replacement of the node with ReplacementText.
95 template <typename Node>
96 Replacement(const SourceManager &Sources, const Node &NodeToReplace,
97 StringRef ReplacementText,
98 const LangOptions &LangOpts = LangOptions());
99
100 /// \brief Returns whether this replacement can be applied to a file.
101 ///
102 /// Only replacements that are in a valid file can be applied.
103 bool isApplicable() const;
104
105 /// \brief Accessors.
106 /// @{
getFilePath()107 StringRef getFilePath() const { return FilePath; }
getOffset()108 unsigned getOffset() const { return ReplacementRange.getOffset(); }
getLength()109 unsigned getLength() const { return ReplacementRange.getLength(); }
getReplacementText()110 StringRef getReplacementText() const { return ReplacementText; }
111 /// @}
112
113 /// \brief Applies the replacement on the Rewriter.
114 bool apply(Rewriter &Rewrite) const;
115
116 /// \brief Returns a human readable string representation.
117 std::string toString() const;
118
119 private:
120 void setFromSourceLocation(const SourceManager &Sources,
121 SourceLocation Start, unsigned Length,
122 StringRef ReplacementText);
123 void setFromSourceRange(const SourceManager &Sources,
124 const CharSourceRange &Range,
125 StringRef ReplacementText,
126 const LangOptions &LangOpts);
127
128 std::string FilePath;
129 Range ReplacementRange;
130 std::string ReplacementText;
131 };
132
133 /// \brief Less-than operator between two Replacements.
134 bool operator<(const Replacement &LHS, const Replacement &RHS);
135
136 /// \brief Equal-to operator between two Replacements.
137 bool operator==(const Replacement &LHS, const Replacement &RHS);
138
139 /// \brief A set of Replacements.
140 /// FIXME: Change to a vector and deduplicate in the RefactoringTool.
141 typedef std::set<Replacement> Replacements;
142
143 /// \brief Apply all replacements in \p Replaces to the Rewriter \p Rewrite.
144 ///
145 /// Replacement applications happen independently of the success of
146 /// other applications.
147 ///
148 /// \returns true if all replacements apply. false otherwise.
149 bool applyAllReplacements(const Replacements &Replaces, Rewriter &Rewrite);
150
151 /// \brief Apply all replacements in \p Replaces to the Rewriter \p Rewrite.
152 ///
153 /// Replacement applications happen independently of the success of
154 /// other applications.
155 ///
156 /// \returns true if all replacements apply. false otherwise.
157 bool applyAllReplacements(const std::vector<Replacement> &Replaces,
158 Rewriter &Rewrite);
159
160 /// \brief Applies all replacements in \p Replaces to \p Code.
161 ///
162 /// This completely ignores the path stored in each replacement. If one or more
163 /// replacements cannot be applied, this returns an empty \c string.
164 std::string applyAllReplacements(StringRef Code, const Replacements &Replaces);
165
166 /// \brief Calculates how a code \p Position is shifted when \p Replaces are
167 /// applied.
168 unsigned shiftedCodePosition(const Replacements& Replaces, unsigned Position);
169
170 /// \brief Calculates how a code \p Position is shifted when \p Replaces are
171 /// applied.
172 ///
173 /// \pre Replaces[i].getOffset() <= Replaces[i+1].getOffset().
174 unsigned shiftedCodePosition(const std::vector<Replacement> &Replaces,
175 unsigned Position);
176
177 /// \brief Removes duplicate Replacements and reports if Replacements conflict
178 /// with one another. All Replacements are assumed to be in the same file.
179 ///
180 /// \post Replaces[i].getOffset() <= Replaces[i+1].getOffset().
181 ///
182 /// This function sorts \p Replaces so that conflicts can be reported simply by
183 /// offset into \p Replaces and number of elements in the conflict.
184 void deduplicate(std::vector<Replacement> &Replaces,
185 std::vector<Range> &Conflicts);
186
187 /// \brief Collection of Replacements generated from a single translation unit.
188 struct TranslationUnitReplacements {
189 /// Name of the main source for the translation unit.
190 std::string MainSourceFile;
191
192 /// A freeform chunk of text to describe the context of the replacements.
193 /// Will be printed, for example, when detecting conflicts during replacement
194 /// deduplication.
195 std::string Context;
196
197 std::vector<Replacement> Replacements;
198 };
199
200 /// \brief Apply all replacements in \p Replaces to the Rewriter \p Rewrite.
201 ///
202 /// Replacement applications happen independently of the success of
203 /// other applications.
204 ///
205 /// \returns true if all replacements apply. false otherwise.
206 bool applyAllReplacements(const Replacements &Replaces, Rewriter &Rewrite);
207
208 /// \brief Apply all replacements in \p Replaces to the Rewriter \p Rewrite.
209 ///
210 /// Replacement applications happen independently of the success of
211 /// other applications.
212 ///
213 /// \returns true if all replacements apply. false otherwise.
214 bool applyAllReplacements(const std::vector<Replacement> &Replaces,
215 Rewriter &Rewrite);
216
217 /// \brief Applies all replacements in \p Replaces to \p Code.
218 ///
219 /// This completely ignores the path stored in each replacement. If one or more
220 /// replacements cannot be applied, this returns an empty \c string.
221 std::string applyAllReplacements(StringRef Code, const Replacements &Replaces);
222
223 /// \brief Merges two sets of replacements with the second set referring to the
224 /// code after applying the first set. Within both 'First' and 'Second',
225 /// replacements must not overlap.
226 Replacements mergeReplacements(const Replacements &First,
227 const Replacements &Second);
228
229 template <typename Node>
Replacement(const SourceManager & Sources,const Node & NodeToReplace,StringRef ReplacementText,const LangOptions & LangOpts)230 Replacement::Replacement(const SourceManager &Sources,
231 const Node &NodeToReplace, StringRef ReplacementText,
232 const LangOptions &LangOpts) {
233 const CharSourceRange Range =
234 CharSourceRange::getTokenRange(NodeToReplace->getSourceRange());
235 setFromSourceRange(Sources, Range, ReplacementText, LangOpts);
236 }
237
238 } // end namespace tooling
239 } // end namespace clang
240
241 #endif // LLVM_CLANG_TOOLING_CORE_REPLACEMENT_H
242