clang  5.0.0
AtomicChange.h
Go to the documentation of this file.
1 //===--- AtomicChange.h - AtomicChange class --------------------*- 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 // This file defines AtomicChange which is used to create a set of source
11 // changes, e.g. replacements and header insertions.
12 //
13 //===----------------------------------------------------------------------===//
14 
15 #ifndef LLVM_CLANG_TOOLING_REFACTOR_ATOMICCHANGE_H
16 #define LLVM_CLANG_TOOLING_REFACTOR_ATOMICCHANGE_H
17 
20 #include "llvm/ADT/StringRef.h"
21 #include "llvm/Support/Error.h"
22 
23 namespace clang {
24 namespace tooling {
25 
26 /// \brief 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  /// \brief 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  /// \brief 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  /// \brief Returns the atomic change as a YAML string.
49  std::string toYAMLString();
50 
51  /// \brief Converts a YAML-encoded automic change to AtomicChange.
52  static AtomicChange convertFromYAML(llvm::StringRef YAMLContent);
53 
54  /// \brief Returns the key of this change, which is a concatenation of the
55  /// file name and offset of the key position.
56  const std::string &getKey() const { return Key; }
57 
58  /// \brief Returns the path of the file containing this atomic change.
59  const std::string &getFilePath() const { return FilePath; }
60 
61  /// \brief If this change could not be created successfully, e.g. because of
62  /// conflicts among replacements, use this to set an error description.
63  /// Thereby, places that cannot be fixed automatically can be gathered when
64  /// applying changes.
65  void setError(llvm::StringRef Error) { this->Error = Error; }
66 
67  /// \brief Returns whether an error has been set on this list.
68  bool hasError() const { return !Error.empty(); }
69 
70  /// \brief Returns the error message or an empty string if it does not exist.
71  const std::string &getError() const { return Error; }
72 
73  /// \brief Adds a replacement that replaces the given Range with
74  /// ReplacementText.
75  /// \returns An llvm::Error carrying ReplacementError on error.
77  llvm::StringRef ReplacementText);
78 
79  /// \brief Adds a replacement that replaces range [Loc, Loc+Length) with
80  /// \p Text.
81  /// \returns An llvm::Error carrying ReplacementError on error.
83  unsigned Length, llvm::StringRef Text);
84 
85  /// \brief Adds a replacement that inserts \p Text at \p Loc. If this
86  /// insertion conflicts with an existing insertion (at the same position),
87  /// this will be inserted before/after the existing insertion depending on
88  /// \p InsertAfter. Users should use `replace` with `Length=0` instead if they
89  /// do not want conflict resolving by default. If the conflicting replacement
90  /// is not an insertion, an error is returned.
91  ///
92  /// \returns An llvm::Error carrying ReplacementError on error.
94  llvm::StringRef Text, bool InsertAfter = true);
95 
96  /// \brief Adds a header into the file that contains the key position.
97  /// Header can be in angle brackets or double quotation marks. By default
98  /// (header is not quoted), header will be surrounded with double quotes.
99  void addHeader(llvm::StringRef Header);
100 
101  /// \brief Removes a header from the file that contains the key position.
102  void removeHeader(llvm::StringRef Header);
103 
104  /// \brief Returns a const reference to existing replacements.
105  const Replacements &getReplacements() const { return Replaces; }
106 
108  return InsertedHeaders;
109  }
110 
112  return RemovedHeaders;
113  }
114 
115 private:
116  AtomicChange() {}
117 
118  AtomicChange(std::string Key, std::string FilePath, std::string Error,
119  std::vector<std::string> InsertedHeaders,
120  std::vector<std::string> RemovedHeaders,
122 
123  // This uniquely identifies an AtomicChange.
124  std::string Key;
125  std::string FilePath;
126  std::string Error;
127  std::vector<std::string> InsertedHeaders;
128  std::vector<std::string> RemovedHeaders;
129  tooling::Replacements Replaces;
130 };
131 
132 } // end namespace tooling
133 } // end namespace clang
134 
135 #endif // LLVM_CLANG_TOOLING_REFACTOR_ATOMICCHANGE_H
llvm::Error replace(const SourceManager &SM, const CharSourceRange &Range, llvm::StringRef ReplacementText)
Adds a replacement that replaces the given Range with ReplacementText.
unsigned Length
Defines the SourceManager interface.
bool hasError() const
Returns whether an error has been set on this list.
Definition: AtomicChange.h:68
const std::string & getKey() const
Returns the key of this change, which is a concatenation of the file name and offset of the key posit...
Definition: AtomicChange.h:56
const std::string & getFilePath() const
Returns the path of the file containing this atomic change.
Definition: AtomicChange.h:59
Maintains a set of replacements that are conflict-free.
Definition: Replacement.h:205
void setError(llvm::StringRef Error)
If this change could not be created successfully, e.g.
Definition: AtomicChange.h:65
llvm::ArrayRef< std::string > getInsertedHeaders() const
Definition: AtomicChange.h:107
const Replacements & getReplacements() const
Returns a const reference to existing replacements.
Definition: AtomicChange.h:105
AtomicChange(llvm::StringRef FilePath, llvm::StringRef Key)
Creates an atomic change for FilePath with a customized key.
Definition: AtomicChange.h:45
void addHeader(llvm::StringRef Header)
Adds a header into the file that contains the key position.
llvm::ArrayRef< std::string > getRemovedHeaders() const
Definition: AtomicChange.h:111
A source range independent of the SourceManager.
Definition: Replacement.h:42
Represents a character-granular source range.
const SourceManager & SM
Definition: Format.cpp:1293
std::string toYAMLString()
Returns the atomic change as a YAML string.
static AtomicChange convertFromYAML(llvm::StringRef YAMLContent)
Converts a YAML-encoded automic change to AtomicChange.
Encodes a location in the source.
const std::string & getError() const
Returns the error message or an empty string if it does not exist.
Definition: AtomicChange.h:71
llvm::Error insert(const SourceManager &SM, SourceLocation Loc, llvm::StringRef Text, bool InsertAfter=true)
Adds a replacement that inserts Text at Loc.
void removeHeader(llvm::StringRef Header)
Removes a header from the file that contains the key position.
An atomic change is used to create and group a set of source edits, e.g.
Definition: AtomicChange.h:36
StringRef Text
Definition: Format.cpp:1302
This class handles loading and caching of source files into memory.