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