AtomicChange.h source code [clang_source_code/include/clang/Tooling/Refactoring/AtomicChange.h]

1	//===--- AtomicChange.h - AtomicChange 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	// This file defines AtomicChange which is used to create a set of source
10	// changes, e.g. replacements and header insertions.
11	//
12	//===----------------------------------------------------------------------===//
13
14	#ifndef LLVM_CLANG_TOOLING_REFACTOR_ATOMICCHANGE_H
15	#define LLVM_CLANG_TOOLING_REFACTOR_ATOMICCHANGE_H
16
17	#include "clang/Basic/SourceManager.h"
18	#include "clang/Format/Format.h"
19	#include "clang/Tooling/Core/Replacement.h"
20	#include "llvm/ADT/StringRef.h"
21	#include "llvm/Support/Error.h"
22
23	namespace clang {
24	namespace tooling {
25
26	/// An atomic change is used to create and group a set of source edits,
27	/// e.g. replacements or header insertions. Edits in an AtomicChange should be
28	/// related, e.g. replacements for the same type reference and the corresponding
29	/// header insertion/deletion.
30	///
31	/// An AtomicChange is uniquely identified by a key and will either be fully
32	/// applied or not applied at all.
33	///
34	/// Calling setError on an AtomicChange stores the error message and marks it as
35	/// bad, i.e. none of its source edits will be applied.
36	class AtomicChange {
37	public:
38	/// Creates an atomic change around \p KeyPosition with the key being a
39	/// concatenation of the file name and the offset of \p KeyPosition.
40	/// \p KeyPosition should be the location of the key syntactical element that
41	/// is being changed, e.g. the call to a refactored method.
42	AtomicChange(const SourceManager &SM, SourceLocation KeyPosition);
43
44	/// Creates an atomic change for \p FilePath with a customized key.
45	AtomicChange(llvm::StringRef FilePath, llvm::StringRef Key)
46	: Key(Key), FilePath(FilePath) {}
47
48	AtomicChange(AtomicChange &&) = default;
49	AtomicChange(const AtomicChange &) = default;
50
51	AtomicChange &operator=(AtomicChange &&) = default;
52	AtomicChange &operator=(const AtomicChange &) = default;
53
54	bool operator==(const AtomicChange &Other) const;
55
56	/// Returns the atomic change as a YAML string.
57	std::string toYAMLString();
58
59	/// Converts a YAML-encoded automic change to AtomicChange.
60	static AtomicChange convertFromYAML(llvm::StringRef YAMLContent);
61
62	/// Returns the key of this change, which is a concatenation of the
63	/// file name and offset of the key position.
64	const std::string &getKey() const { return Key; }
65
66	/// Returns the path of the file containing this atomic change.
67	const std::string &getFilePath() const { return FilePath; }
68
69	/// If this change could not be created successfully, e.g. because of
70	/// conflicts among replacements, use this to set an error description.
71	/// Thereby, places that cannot be fixed automatically can be gathered when
72	/// applying changes.
73	void setError(llvm::StringRef Error) { this->Error = Error; }
74
75	/// Returns whether an error has been set on this list.
76	bool hasError() const { return !Error.empty(); }
77
78	/// Returns the error message or an empty string if it does not exist.
79	const std::string &getError() const { return Error; }
80
81	/// Adds a replacement that replaces the given Range with
82	/// ReplacementText.
83	/// \returns An llvm::Error carrying ReplacementError on error.
84	llvm::Error replace(const SourceManager &SM, const CharSourceRange &Range,
85	llvm::StringRef ReplacementText);
86
87	/// Adds a replacement that replaces range [Loc, Loc+Length) with
88	/// \p Text.
89	/// \returns An llvm::Error carrying ReplacementError on error.
90	llvm::Error replace(const SourceManager &SM, SourceLocation Loc,
91	unsigned Length, llvm::StringRef Text);
92
93	/// Adds a replacement that inserts \p Text at \p Loc. If this
94	/// insertion conflicts with an existing insertion (at the same position),
95	/// this will be inserted before/after the existing insertion depending on
96	/// \p InsertAfter. Users should use `replace` with `Length=0` instead if they
97	/// do not want conflict resolving by default. If the conflicting replacement
98	/// is not an insertion, an error is returned.
99	///
100	/// \returns An llvm::Error carrying ReplacementError on error.
101	llvm::Error insert(const SourceManager &SM, SourceLocation Loc,
102	llvm::StringRef Text, bool InsertAfter = true);
103
104	/// Adds a header into the file that contains the key position.
105	/// Header can be in angle brackets or double quotation marks. By default
106	/// (header is not quoted), header will be surrounded with double quotes.
107	void addHeader(llvm::StringRef Header);
108
109	/// Removes a header from the file that contains the key position.
110	void removeHeader(llvm::StringRef Header);
111
112	/// Returns a const reference to existing replacements.
113	const Replacements &getReplacements() const { return Replaces; }
114
115	llvm::ArrayRef<std::string> getInsertedHeaders() const {
116	return InsertedHeaders;
117	}
118
119	llvm::ArrayRef<std::string> getRemovedHeaders() const {
120	return RemovedHeaders;
121	}
122
123	private:
124	AtomicChange() {}
125
126	AtomicChange(std::string Key, std::string FilePath, std::string Error,
127	std::vector<std::string> InsertedHeaders,
128	std::vector<std::string> RemovedHeaders,
129	clang::tooling::Replacements Replaces);
130
131	// This uniquely identifies an AtomicChange.
132	std::string Key;
133	std::string FilePath;
134	std::string Error;
135	std::vector<std::string> InsertedHeaders;
136	std::vector<std::string> RemovedHeaders;
137	tooling::Replacements Replaces;
138	};
139
140	using AtomicChanges = std::vector<AtomicChange>;
141
142	// Defines specs for applying changes.
143	struct ApplyChangesSpec {
144	// If true, cleans up redundant/erroneous code around changed code with
145	// clang-format's cleanup functionality, e.g. redundant commas around deleted
146	// parameter or empty namespaces introduced by deletions.
147	bool Cleanup = true;
148
149	format::FormatStyle Style = format::getNoStyle();
150
151	// Options for selectively formatting changes with clang-format:
152	// kAll: Format all changed lines.
153	// kNone: Don't format anything.
154	// kViolations: Format lines exceeding the `ColumnLimit` in `Style`.
155	enum FormatOption { kAll, kNone, kViolations };
156
157	FormatOption Format = kNone;
158	};
159
160	/// Applies all AtomicChanges in \p Changes to the \p Code.
161	///
162	/// This completely ignores the file path in each change and replaces them with
163	/// \p FilePath, i.e. callers are responsible for ensuring all changes are for
164	/// the same file.
165	///
166	/// \returns The changed code if all changes are applied successfully;
167	/// otherwise, an llvm::Error carrying llvm::StringError is returned (the Error
168	/// message can be converted to string with `llvm::toString()` and the
169	/// error_code should be ignored).
170	llvm::Expected<std::string>
171	applyAtomicChanges(llvm::StringRef FilePath, llvm::StringRef Code,
172	llvm::ArrayRef<AtomicChange> Changes,
173	const ApplyChangesSpec &Spec);
174
175	} // end namespace tooling
176	} // end namespace clang
177
178	#endif // LLVM_CLANG_TOOLING_REFACTOR_ATOMICCHANGE_H
179