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