clang-tools-extra/clangd/refactor/Tweak.h

   1 //===--- Tweak.h -------------------------------------------------*- 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 // Tweaks are small actions that run over the AST and produce edits, messages
   9 // etc as a result. They are local, i.e. they should take the current editor
  10 // context, e.g. the cursor position and selection into account.
  11 // The actions are executed in two stages:
  12 //   - Stage 1 should check whether the action is available in a current
  13 //     context. It should be cheap and fast to compute as it is executed for all
  14 //     available actions on every client request, which happen quite frequently.
  15 //   - Stage 2 is performed after stage 1 and can be more expensive to compute.
  16 //     It is performed when the user actually chooses the action.
  17 //===----------------------------------------------------------------------===//
  18
  19 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_REFACTOR_TWEAK_H
  20 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_REFACTOR_TWEAK_H
  21
  22 #include "ParsedAST.h"
  23 #include "Selection.h"
  24 #include "SourceCode.h"
  25 #include "index/Index.h"
  26 #include "support/Path.h"
  27 #include "clang/Tooling/Core/Replacement.h"
  28 #include "llvm/ADT/StringRef.h"
  29 #include "llvm/Support/Error.h"
  30 #include <optional>
  31 #include <string>
  32
  33 namespace clang {
  34 namespace clangd {
  35
  36 class FeatureModuleSet;
  37
  38 /// An interface base for small context-sensitive refactoring actions.
  39 /// To implement a new tweak use the following pattern in a .cpp file:
  40 ///   class MyTweak : public Tweak {
  41 ///   public:
  42 ///     const char* id() const override final; // defined by REGISTER_TWEAK.
  43 ///     // implement other methods here.
  44 ///   };
  45 ///   REGISTER_TWEAK(MyTweak);
  46 class Tweak {
  47 public:
  48   /// Input to prepare and apply tweaks.
  49   struct Selection {
  50     Selection(const SymbolIndex *Index, ParsedAST &AST, unsigned RangeBegin,
  51               unsigned RangeEnd, SelectionTree ASTSelection,
  52               llvm::vfs::FileSystem *VFS);
  53     /// The text of the active document.
  54     llvm::StringRef Code;
  55     /// The Index for handling codebase related queries.
  56     const SymbolIndex *Index = nullptr;
  57     /// The parsed active file. Never null. (Pointer so Selection is movable).
  58     ParsedAST *AST;
  59     /// A location of the cursor in the editor.
  60     // FIXME: Cursor is redundant and should be removed
  61     SourceLocation Cursor;
  62     /// The begin offset of the selection
  63     unsigned SelectionBegin;
  64     /// The end offset of the selection
  65     unsigned SelectionEnd;
  66     /// The AST nodes that were selected.
  67     SelectionTree ASTSelection;
  68     /// File system used to access source code (for cross-file tweaks).
  69     /// This is only populated when applying a tweak, not during prepare.
  70     llvm::vfs::FileSystem *FS = nullptr;
  71     // FIXME: provide a way to get sources and ASTs for other files.
  72   };
  73
  74   struct Effect {
  75     /// A message to be displayed to the user.
  76     std::optional<std::string> ShowMessage;
  77     FileEdits ApplyEdits;
  78     /// Whether the edits should be formatted before presenting to the client.
  79     /// Note that it applies to all files.
  80     bool FormatEdits = true;
  81
  82     static Effect showMessage(StringRef S) {
  83       Effect E;
  84       E.ShowMessage = std::string(S);
  85       return E;
  86     }
  87
  88     /// Path is the absolute, symlink-resolved path for the file pointed by FID
  89     /// in SM. Edit is generated from Replacements.
  90     /// Fails if cannot figure out absolute path for FID.
  91     static llvm::Expected<std::pair<Path, Edit>>
  92     fileEdit(const SourceManager &SM, FileID FID,
  93              tooling::Replacements Replacements);
  94
  95     /// Creates an effect with an Edit for the main file.
  96     /// Fails if cannot figure out absolute path for main file.
  97     static llvm::Expected<Tweak::Effect>
  98     mainFileEdit(const SourceManager &SM, tooling::Replacements Replacements);
  99   };
 100
 101   virtual ~Tweak() = default;
 102   /// A unique id of the action, it is always equal to the name of the class
 103   /// defining the Tweak. Definition is provided automatically by
 104   /// REGISTER_TWEAK.
 105   virtual const char *id() const = 0;
 106   /// Run the first stage of the action. Returns true indicating that the
 107   /// action is available and should be shown to the user. Returns false if the
 108   /// action is not available.
 109   /// This function should be fast, if the action requires non-trivial work it
 110   /// should be moved into 'apply'.
 111   /// Returns true iff the action is available and apply() can be called on it.
 112   virtual bool prepare(const Selection &Sel) = 0;
 113   /// Run the second stage of the action that would produce the actual effect.
 114   /// EXPECTS: prepare() was called and returned true.
 115   virtual Expected<Effect> apply(const Selection &Sel) = 0;
 116
 117   /// A one-line title of the action that should be shown to the users in the
 118   /// UI.
 119   /// EXPECTS: prepare() was called and returned true.
 120   virtual std::string title() const = 0;
 121   /// Describes what kind of action this is.
 122   /// EXPECTS: prepare() was called and returned true.
 123   virtual llvm::StringLiteral kind() const = 0;
 124   /// Is this a 'hidden' tweak, which are off by default.
 125   virtual bool hidden() const { return false; }
 126 };
 127
 128 // All tweaks must be registered in the .cpp file next to their definition.
 129 #define REGISTER_TWEAK(Subclass)                                               \
 130   ::llvm::Registry<::clang::clangd::Tweak>::Add<Subclass>                      \
 131       TweakRegistrationFor##Subclass(#Subclass, /*Description=*/"");           \
 132   const char *Subclass::id() const { return #Subclass; }
 133
 134 /// Calls prepare() on all tweaks that satisfy the filter, returning those that
 135 /// can run on the selection.
 136 std::vector<std::unique_ptr<Tweak>>
 137 prepareTweaks(const Tweak::Selection &S,
 138               llvm::function_ref<bool(const Tweak &)> Filter,
 139               const FeatureModuleSet *Modules);
 140
 141 // Calls prepare() on the tweak with a given ID.
 142 // If prepare() returns false, returns an error.
 143 // If prepare() returns true, returns the corresponding tweak.
 144 llvm::Expected<std::unique_ptr<Tweak>>
 145 prepareTweak(StringRef ID, const Tweak::Selection &S,
 146              const FeatureModuleSet *Modules);
 147 } // namespace clangd
 148 } // namespace clang
 149
 150 #endif