contrib/llvm/tools/clang/include/clang/Tooling/Refactoring.h

   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
  28 namespace clang {
  29
  30 class Rewriter;
  31 class SourceLocation;
  32
  33 namespace tooling {
  34
  35 /// \brief A text replacement.
  36 ///
  37 /// Represents a SourceManager independent replacement of a range of text in a
  38 /// specific file.
  39 class Replacement {
  40 public:
  41   /// \brief Creates an invalid (not applicable) replacement.
  42   Replacement();
  43
  44   /// \brief Creates a replacement of the range [Offset, Offset+Length) in
  45   /// FilePath with ReplacementText.
  46   ///
  47   /// \param FilePath A source file accessible via a SourceManager.
  48   /// \param Offset The byte offset of the start of the range in the file.
  49   /// \param Length The length of the range in bytes.
  50   Replacement(StringRef FilePath, unsigned Offset,
  51               unsigned Length, StringRef ReplacementText);
  52
  53   /// \brief Creates a Replacement of the range [Start, Start+Length) with
  54   /// ReplacementText.
  55   Replacement(SourceManager &Sources, SourceLocation Start, unsigned Length,
  56               StringRef ReplacementText);
  57
  58   /// \brief Creates a Replacement of the given range with ReplacementText.
  59   Replacement(SourceManager &Sources, const CharSourceRange &Range,
  60               StringRef ReplacementText);
  61
  62   /// \brief Creates a Replacement of the node with ReplacementText.
  63   template <typename Node>
  64   Replacement(SourceManager &Sources, const Node &NodeToReplace,
  65               StringRef ReplacementText);
  66
  67   /// \brief Returns whether this replacement can be applied to a file.
  68   ///
  69   /// Only replacements that are in a valid file can be applied.
  70   bool isApplicable() const;
  71
  72   /// \brief Accessors.
  73   /// @{
  74   StringRef getFilePath() const { return FilePath; }
  75   unsigned getOffset() const { return Offset; }
  76   unsigned getLength() const { return Length; }
  77   StringRef getReplacementText() const { return ReplacementText; }
  78   /// @}
  79
  80   /// \brief Applies the replacement on the Rewriter.
  81   bool apply(Rewriter &Rewrite) const;
  82
  83   /// \brief Returns a human readable string representation.
  84   std::string toString() const;
  85
  86   /// \brief Comparator to be able to use Replacement in std::set for uniquing.
  87   class Less {
  88   public:
  89     bool operator()(const Replacement &R1, const Replacement &R2) const;
  90   };
  91
  92  private:
  93   void setFromSourceLocation(SourceManager &Sources, SourceLocation Start,
  94                              unsigned Length, StringRef ReplacementText);
  95   void setFromSourceRange(SourceManager &Sources, const CharSourceRange &Range,
  96                           StringRef ReplacementText);
  97
  98   std::string FilePath;
  99   unsigned Offset;
 100   unsigned Length;
 101   std::string ReplacementText;
 102 };
 103
 104 /// \brief A set of Replacements.
 105 /// FIXME: Change to a vector and deduplicate in the RefactoringTool.
 106 typedef std::set<Replacement, Replacement::Less> Replacements;
 107
 108 /// \brief Apply all replacements in \p Replaces to the Rewriter \p Rewrite.
 109 ///
 110 /// Replacement applications happen independently of the success of
 111 /// other applications.
 112 ///
 113 /// \returns true if all replacements apply. false otherwise.
 114 bool applyAllReplacements(Replacements &Replaces, Rewriter &Rewrite);
 115
 116 /// \brief A tool to run refactorings.
 117 ///
 118 /// This is a refactoring specific version of \see ClangTool. FrontendActions
 119 /// passed to run() and runAndSave() should add replacements to
 120 /// getReplacements().
 121 class RefactoringTool : public ClangTool {
 122 public:
 123   /// \see ClangTool::ClangTool.
 124   RefactoringTool(const CompilationDatabase &Compilations,
 125                   ArrayRef<std::string> SourcePaths);
 126
 127   /// \brief Returns the set of replacements to which replacements should
 128   /// be added during the run of the tool.
 129   Replacements &getReplacements();
 130
 131   /// \brief Call run(), apply all generated replacements, and immediately save
 132   /// the results to disk.
 133   ///
 134   /// \returns 0 upon success. Non-zero upon failure.
 135   int runAndSave(FrontendActionFactory *ActionFactory);
 136
 137   /// \brief Apply all stored replacements to the given Rewriter.
 138   ///
 139   /// Replacement applications happen independently of the success of other
 140   /// applications.
 141   ///
 142   /// \returns true if all replacements apply. false otherwise.
 143   bool applyAllReplacements(Rewriter &Rewrite);
 144
 145 private:
 146   /// \brief Write all refactored files to disk.
 147   int saveRewrittenFiles(Rewriter &Rewrite);
 148
 149 private:
 150   Replacements Replace;
 151 };
 152
 153 template <typename Node>
 154 Replacement::Replacement(SourceManager &Sources, const Node &NodeToReplace,
 155                          StringRef ReplacementText) {
 156   const CharSourceRange Range =
 157       CharSourceRange::getTokenRange(NodeToReplace->getSourceRange());
 158   setFromSourceRange(Sources, Range, ReplacementText);
 159 }
 160
 161 } // end namespace tooling
 162 } // end namespace clang
 163
 164 #endif // end namespace LLVM_CLANG_TOOLING_REFACTORING_H