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_ACTIONS_TWEAK_H 20 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_REFACTOR_ACTIONS_TWEAK_H 21 22 #include "ParsedAST.h" 23 #include "Protocol.h" 24 #include "Selection.h" 25 #include "SourceCode.h" 26 #include "index/Index.h" 27 #include "support/Path.h" 28 #include "clang/Tooling/Core/Replacement.h" 29 #include "llvm/ADT/Optional.h" 30 #include "llvm/ADT/StringMap.h" 31 #include "llvm/ADT/StringRef.h" 32 #include "llvm/Support/Error.h" 33 #include <string> 34 35 namespace clang { 36 namespace clangd { 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 /// The text of the active document. 53 llvm::StringRef Code; 54 /// The Index for handling codebase related queries. 55 const SymbolIndex *Index = nullptr; 56 /// The parsed active file. Never null. (Pointer so Selection is movable). 57 ParsedAST *AST; 58 /// A location of the cursor in the editor. 59 // FIXME: Cursor is redundant and should be removed 60 SourceLocation Cursor; 61 /// The begin offset of the selection 62 unsigned SelectionBegin; 63 /// The end offset of the selection 64 unsigned SelectionEnd; 65 /// The AST nodes that were selected. 66 SelectionTree ASTSelection; 67 // FIXME: provide a way to get sources and ASTs for other files. 68 }; 69 70 struct Effect { 71 /// A message to be displayed to the user. 72 llvm::Optional<std::string> ShowMessage; 73 FileEdits ApplyEdits; 74 showMessageEffect75 static Effect showMessage(StringRef S) { 76 Effect E; 77 E.ShowMessage = std::string(S); 78 return E; 79 } 80 81 /// Path is the absolute, symlink-resolved path for the file pointed by FID 82 /// in SM. Edit is generated from Replacements. 83 /// Fails if cannot figure out absolute path for FID. 84 static llvm::Expected<std::pair<Path, Edit>> 85 fileEdit(const SourceManager &SM, FileID FID, 86 tooling::Replacements Replacements); 87 88 /// Creates an effect with an Edit for the main file. 89 /// Fails if cannot figure out absolute path for main file. 90 static llvm::Expected<Tweak::Effect> 91 mainFileEdit(const SourceManager &SM, tooling::Replacements Replacements); 92 }; 93 94 virtual ~Tweak() = default; 95 /// A unique id of the action, it is always equal to the name of the class 96 /// defining the Tweak. Definition is provided automatically by 97 /// REGISTER_TWEAK. 98 virtual const char *id() const = 0; 99 /// Run the first stage of the action. Returns true indicating that the 100 /// action is available and should be shown to the user. Returns false if the 101 /// action is not available. 102 /// This function should be fast, if the action requires non-trivial work it 103 /// should be moved into 'apply'. 104 /// Returns true iff the action is available and apply() can be called on it. 105 virtual bool prepare(const Selection &Sel) = 0; 106 /// Run the second stage of the action that would produce the actual effect. 107 /// EXPECTS: prepare() was called and returned true. 108 virtual Expected<Effect> apply(const Selection &Sel) = 0; 109 110 /// A one-line title of the action that should be shown to the users in the 111 /// UI. 112 /// EXPECTS: prepare() was called and returned true. 113 virtual std::string title() const = 0; 114 /// Describes what kind of action this is. 115 /// EXPECTS: prepare() was called and returned true. 116 virtual llvm::StringLiteral kind() const = 0; 117 /// Is this a 'hidden' tweak, which are off by default. hidden()118 virtual bool hidden() const { return false; } 119 }; 120 121 // All tweaks must be registered in the .cpp file next to their definition. 122 #define REGISTER_TWEAK(Subclass) \ 123 ::llvm::Registry<::clang::clangd::Tweak>::Add<Subclass> \ 124 TweakRegistrationFor##Subclass(#Subclass, /*Description=*/""); \ 125 const char *Subclass::id() const { return #Subclass; } 126 127 /// Calls prepare() on all tweaks that satisfy the filter, returning those that 128 /// can run on the selection. 129 std::vector<std::unique_ptr<Tweak>> 130 prepareTweaks(const Tweak::Selection &S, 131 llvm::function_ref<bool(const Tweak &)> Filter); 132 133 // Calls prepare() on the tweak with a given ID. 134 // If prepare() returns false, returns an error. 135 // If prepare() returns true, returns the corresponding tweak. 136 llvm::Expected<std::unique_ptr<Tweak>> prepareTweak(StringRef TweakID, 137 const Tweak::Selection &S); 138 } // namespace clangd 139 } // namespace clang 140 141 #endif 142