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

   1 //===--- Refactoring.h - Framework for clang refactoring tools --*- 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 //  Interfaces supporting refactorings that span multiple translation units.
  10 //  While single translation unit refactorings are supported via the Rewriter,
  11 //  when refactoring multiple translation units changes must be stored in a
  12 //  SourceManager independent form, duplicate changes need to be removed, and
  13 //  all changes must be applied at once at the end of the refactoring so that
  14 //  the code is always parseable.
  15 //
  16 //===----------------------------------------------------------------------===//
  17
  18 #ifndef LLVM_CLANG_TOOLING_REFACTORING_H
  19 #define LLVM_CLANG_TOOLING_REFACTORING_H
  20
  21 #include "clang/Tooling/Core/Replacement.h"
  22 #include "clang/Tooling/Tooling.h"
  23 #include <map>
  24 #include <string>
  25
  26 namespace clang {
  27
  28 class Rewriter;
  29
  30 namespace tooling {
  31
  32 /// A tool to run refactorings.
  33 ///
  34 /// This is a refactoring specific version of \see ClangTool. FrontendActions
  35 /// passed to run() and runAndSave() should add replacements to
  36 /// getReplacements().
  37 class RefactoringTool : public ClangTool {
  38 public:
  39   /// \see ClangTool::ClangTool.
  40   RefactoringTool(const CompilationDatabase &Compilations,
  41                   ArrayRef<std::string> SourcePaths,
  42                   std::shared_ptr<PCHContainerOperations> PCHContainerOps =
  43                       std::make_shared<PCHContainerOperations>());
  44
  45   /// Returns the file path to replacements map to which replacements
  46   /// should be added during the run of the tool.
  47   std::map<std::string, Replacements> &getReplacements();
  48
  49   /// Call run(), apply all generated replacements, and immediately save
  50   /// the results to disk.
  51   ///
  52   /// \returns 0 upon success. Non-zero upon failure.
  53   int runAndSave(FrontendActionFactory *ActionFactory);
  54
  55   /// Apply all stored replacements to the given Rewriter.
  56   ///
  57   /// FileToReplaces will be deduplicated with `groupReplacementsByFile` before
  58   /// application.
  59   ///
  60   /// Replacement applications happen independently of the success of other
  61   /// applications.
  62   ///
  63   /// \returns true if all replacements apply. false otherwise.
  64   bool applyAllReplacements(Rewriter &Rewrite);
  65
  66 private:
  67   /// Write all refactored files to disk.
  68   int saveRewrittenFiles(Rewriter &Rewrite);
  69
  70 private:
  71   std::map<std::string, Replacements> FileToReplaces;
  72 };
  73
  74 /// Groups \p Replaces by the file path and applies each group of
  75 /// Replacements on the related file in \p Rewriter. In addition to applying
  76 /// given Replacements, this function also formats the changed code.
  77 ///
  78 /// \pre Replacements must be conflict-free.
  79 ///
  80 /// FileToReplaces will be deduplicated with `groupReplacementsByFile` before
  81 /// application.
  82 ///
  83 /// Replacement applications happen independently of the success of other
  84 /// applications.
  85 ///
  86 /// \param[in] FileToReplaces Replacements (grouped by files) to apply.
  87 /// \param[in] Rewrite The `Rewritter` to apply replacements on.
  88 /// \param[in] Style The style name used for reformatting. See ```getStyle``` in
  89 /// "include/clang/Format/Format.h" for all possible style forms.
  90 ///
  91 /// \returns true if all replacements applied and formatted. false otherwise.
  92 bool formatAndApplyAllReplacements(
  93     const std::map<std::string, Replacements> &FileToReplaces,
  94     Rewriter &Rewrite, StringRef Style = "file");
  95
  96 } // end namespace tooling
  97 } // end namespace clang
  98
  99 #endif // LLVM_CLANG_TOOLING_REFACTORING_H