clang-tools 10.0.0

CodeComplete.h
Go to the documentation of this file.
1 //===--- CodeComplete.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 //
9 // Code completion provides suggestions for what the user might type next.
10 // After "std::string S; S." we might suggest members of std::string.
11 // Signature help describes the parameters of a function as you type them.
12 //
13 //===----------------------------------------------------------------------===//
14
15 #ifndef LLVM_CLANG_TOOLS_EXTRA_CLANGD_CODECOMPLETE_H
16 #define LLVM_CLANG_TOOLS_EXTRA_CLANGD_CODECOMPLETE_H
17
18 #include "Headers.h"
19 #include "Logger.h"
20 #include "Path.h"
21 #include "Protocol.h"
22 #include "index/Index.h"
23 #include "index/Symbol.h"
24 #include "index/SymbolOrigin.h"
25 #include "clang/Sema/CodeCompleteConsumer.h"
26 #include "clang/Sema/CodeCompleteOptions.h"
27 #include "clang/Tooling/CompilationDatabase.h"
28 #include "llvm/ADT/Optional.h"
29 #include "llvm/ADT/SmallVector.h"
30 #include "llvm/ADT/StringRef.h"
31 #include "llvm/Support/Error.h"
32 #include <future>
33
34 namespace clang {
35 class NamedDecl;
36 namespace clangd {
37 struct PreambleData;
38
39 struct CodeCompleteOptions {
40 /// Returns options that can be passed to clang's completion engine.
41 clang::CodeCompleteOptions getClangCompleteOpts() const;
42
43 /// When true, completion items will contain expandable code snippets in
44 /// completion (e.g. `return ${1:expression}` or `foo(${1:int a}, ${2:int
45 /// b})).
46 bool EnableSnippets = false;
47
48 /// Add code patterns to completion results.
49 /// If EnableSnippets is false, this options is ignored and code patterns will
50 /// always be omitted.
51 bool IncludeCodePatterns = true;
52
53 /// Add macros to code completion results.
54 bool IncludeMacros = true;
55
56 /// Add comments to code completion results, if available.
57 bool IncludeComments = true;
58
59 /// Include results that are not legal completions in the current context.
60 /// For example, private members are usually inaccessible.
61 bool IncludeIneligibleResults = false;
62
63 /// Combine overloads into a single completion item where possible.
64 /// If none, the implementation may choose an appropriate behavior.
65 /// (In practice, ClangdLSPServer enables bundling if the client claims
66 /// to supports signature help).
67 llvm::Optional<bool> BundleOverloads;
68
69 /// Limit the number of results returned (0 means no limit).
70 /// If more results are available, we set CompletionList.isIncomplete.
71 size_t Limit = 0;
72
73 enum IncludeInsertion {
74 IWYU,
75 NeverInsert,
76 } InsertIncludes = IncludeInsertion::IWYU;
77
78 /// A visual indicator to prepend to the completion label to indicate whether
79 /// completion result would trigger an #include insertion or not.
80 struct IncludeInsertionIndicator {
81 std::string Insert = "•";
82 std::string NoInsert = " ";
83 } IncludeIndicator;
84
85 /// Expose origins of completion items in the label (for debugging).
86 bool ShowOrigins = false;
87
88 /// If set to true, this will send an asynchronous speculative index request,
89 /// based on the index request for the last code completion on the same file
90 /// and the filter text typed before the cursor, before sema code completion
91 /// is invoked. This can reduce the code completion latency (by roughly
92 /// latency of sema code completion) if the speculative request is the same as
93 /// the one generated for the ongoing code completion from sema. As a sequence
94 /// of code completions often have the same scopes and proximity paths etc,
95 /// this should be effective for a number of code completions.
96 bool SpeculativeIndexRequest = false;
97
98 // Populated internally by clangd, do not set.
99 /// If `Index` is set, it is used to augment the code completion
100 /// results.
101 /// FIXME(ioeric): we might want a better way to pass the index around inside
102 /// clangd.
103 const SymbolIndex *Index = nullptr;
104
105 /// Include completions that require small corrections, e.g. change '.' to
106 /// '->' on member access etc.
107 bool IncludeFixIts = false;
108
109 /// Whether to generate snippets for function arguments on code-completion.
110 /// Needs snippets to be enabled as well.
111 bool EnableFunctionArgSnippets = true;
112
113 /// Whether to include index symbols that are not defined in the scopes
114 /// visible from the code completion point. This applies in contexts without
115 /// explicit scope qualifiers.
116 ///
117 /// Such completions can insert scope qualifiers.
118 bool AllScopes = false;
119
120 /// Whether to use the clang parser, or fallback to text-based completion
121 /// (using identifiers in the current file and symbol indexes).
122 enum CodeCompletionParse {
123 /// Block until we can run the parser (e.g. preamble is built).
124 /// Return an error if this fails.
125 AlwaysParse,
126 /// Run the parser if inputs (preamble) are ready.
127 /// Otherwise, use text-based completion.
128 ParseIfReady,
129 /// Always use text-based completion.
130 NeverParse,
131 } RunParser = ParseIfReady;
132 };
133
134 // Semi-structured representation of a code-complete suggestion for our C++ API.
135 // We don't use the LSP structures here (unlike most features) as we want
136 // to expose more data to allow for more precise testing and evaluation.
137 struct CodeCompletion {
138 // The unqualified name of the symbol or other completion item.
139 std::string Name;
140 // The scope qualifier for the symbol name. e.g. "ns1::ns2::"
141 // Empty for non-symbol completions. Not inserted, but may be displayed.
142 std::string Scope;
143 // Text that must be inserted before the name, and displayed (e.g. base::).
144 std::string RequiredQualifier;
145 // Details to be displayed following the name. Not inserted.
146 std::string Signature;
147 // Text to be inserted following the name, in snippet format.
148 std::string SnippetSuffix;
149 // Type to be displayed for this completion.
150 std::string ReturnType;
151 std::string Documentation;
152 CompletionItemKind Kind = CompletionItemKind::Missing;
153 // This completion item may represent several symbols that can be inserted in
154 // the same way, such as function overloads. In this case BundleSize > 1, and
155 // the following fields are summaries:
156 // - Signature is e.g. "(...)" for functions.
157 // - SnippetSuffix is similarly e.g. "(${0})".
158 // - ReturnType may be empty
159 // - Documentation may be from one symbol, or a combination of several
160 // Other fields should apply equally to all bundled completions.
161 unsigned BundleSize = 1;
162 SymbolOrigin Origin = SymbolOrigin::Unknown;
163
164 struct IncludeCandidate {
165 // The header through which this symbol could be included.
166 // Quoted string as expected by an #include directive, e.g. "<memory>".
167 // Empty for non-symbol completions, or when not known.
168 std::string Header;
169 // Present if Header should be inserted to use this item.
170 llvm::Optional<TextEdit> Insertion;
171 };
172 // All possible include headers ranked by preference. By default, the first
173 // include is used.
174 // If we've bundled together overloads that have different sets of includes,
175 // thse includes may not be accurate for all of them.
176 llvm::SmallVector<IncludeCandidate, 1> Includes;
177
178 /// Holds information about small corrections that needs to be done. Like
179 /// converting '->' to '.' on member access.
180 std::vector<TextEdit> FixIts;
181
182 /// Holds the range of the token we are going to replace with this completion.
183 Range CompletionTokenRange;
184
185 // Scores are used to rank completion items.
186 struct Scores {
187 // The score that items are ranked by.
188 float Total = 0.f;
189
190 // The finalScore with the fuzzy name match score excluded.
191 // When filtering client-side, editors should calculate the new fuzzy score,
192 // whose scale is 0-1 (with 1 = prefix match, special case 2 = exact match),
193 // and recompute finalScore = fuzzyScore * symbolScore.
194 float ExcludingName = 0.f;
195
196 // Component scores that contributed to the final score:
197
198 // Quality describes how important we think this candidate is,
199 // independent of the query.
200 // e.g. symbols with lots of incoming references have higher quality.
201 float Quality = 0.f;
202 // Relevance describes how well this candidate matched the query.
203 // e.g. symbols from nearby files have higher relevance.
204 float Relevance = 0.f;
205 };
206 Scores Score;
207
208 /// Indicates if this item is deprecated.
209 bool Deprecated = false;
210
211 // Serialize this to an LSP completion item. This is a lossy operation.
212 CompletionItem render(const CodeCompleteOptions &) const;
213 };
214 raw_ostream &operator<<(raw_ostream &, const CodeCompletion &);
215 struct CodeCompleteResult {
216 std::vector<CodeCompletion> Completions;
217 bool HasMore = false;
218 CodeCompletionContext::Kind Context = CodeCompletionContext::CCC_Other;
219 // Usually the source will be parsed with a real C++ parser.
220 // But heuristics may be used instead if e.g. the preamble is not ready.
221 bool RanParser = true;
222 };
223 raw_ostream &operator<<(raw_ostream &, const CodeCompleteResult &);
224
225 /// A speculative and asynchronous fuzzy find index request (based on cached
226 /// request) that can be sent before parsing sema. This would reduce completion
227 /// latency if the speculation succeeds.
228 struct SpeculativeFuzzyFind {
229 /// A cached request from past code completions.
230 /// Set by caller of `codeComplete()`.
231 llvm::Optional<FuzzyFindRequest> CachedReq;
232 /// The actual request used by `codeComplete()`.
233 /// Set by `codeComplete()`. This can be used by callers to update cache.
234 llvm::Optional<FuzzyFindRequest> NewReq;
235 /// The result is consumed by `codeComplete()` if speculation succeeded.
236 /// NOTE: the destructor will wait for the async call to finish.
237 std::future<SymbolSlab> Result;
238 };
239
240 /// Gets code completions at a specified \p Pos in \p FileName.
241 ///
242 /// If \p Preamble is nullptr, this runs code completion without compiling the
243 /// code.
244 ///
245 /// If \p SpecFuzzyFind is set, a speculative and asynchronous fuzzy find index
246 /// request (based on cached request) will be run before parsing sema. In case
247 /// the speculative result is used by code completion (e.g. speculation failed),
248 /// the speculative result is not consumed, and `SpecFuzzyFind` is only
249 /// destroyed when the async request finishes.
250 CodeCompleteResult codeComplete(PathRef FileName,
251 const tooling::CompileCommand &Command,
252 const PreambleData *Preamble,
253 StringRef Contents, Position Pos,
254 IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS,
255 CodeCompleteOptions Opts,
256 SpeculativeFuzzyFind *SpecFuzzyFind = nullptr);
257
258 /// Get signature help at a specified \p Pos in \p FileName.
259 SignatureHelp signatureHelp(PathRef FileName,
260 const tooling::CompileCommand &Command,
261 const PreambleData *Preamble, StringRef Contents,
262 Position Pos,
263 IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS,
264 const SymbolIndex *Index);
265
266 // For index-based completion, we only consider:
267 // * symbols in namespaces or translation unit scopes (e.g. no class
268 // members, no locals)
269 // * enum constants in unscoped enum decl (e.g. "red" in "enum {red};")
270 // * primary templates (no specializations)
271 // For the other cases, we let Clang do the completion because it does not
272 // need any non-local information and it will be much better at following
273 // lookup rules. Other symbols still appear in the index for other purposes,
274 // like workspace/symbols or textDocument/definition, but are not used for code
275 // completion.
276 bool isIndexedForCodeCompletion(const NamedDecl &ND, ASTContext &ASTCtx);
277
278 // Text immediately before the completion point that should be completed.
279 // This is heuristically derived from the source code, and is used when:
280 // - semantic analysis fails
281 // - semantic analysis may be slow, and we speculatively query the index
282 struct CompletionPrefix {
283 // The unqualified partial name.
284 // If there is none, begin() == end() == completion position.
285 llvm::StringRef Name;
286 // The spelled scope qualifier, such as Foo::.
287 // If there is none, begin() == end() == Name.begin().
288 llvm::StringRef Qualifier;
289 };
290 // Heuristically parses before Offset to determine what should be completed.
291 CompletionPrefix guessCompletionPrefix(llvm::StringRef Content,
292 unsigned Offset);
293
294 } // namespace clangd
295 } // namespace clang
296
297 #endif // LLVM_CLANG_TOOLS_EXTRA_CLANGD_CODECOMPLETE_H
clang::clangd::SpeculativeFuzzyFind::Result
std::future< SymbolSlab > Result
The result is consumed by codeComplete() if speculation succeeded.
Definition: CodeComplete.h:237
clang::clangd::CodeCompleteOptions::ShowOrigins
bool ShowOrigins
Expose origins of completion items in the label (for debugging).
Definition: CodeComplete.h:86
Command
const tooling::CompileCommand & Command
Definition: CodeComplete.cpp:1019
clang::clangd::CodeCompletion::Signature
std::string Signature
Definition: CodeComplete.h:146
clang::clangd::CodeCompleteOptions::Limit
size_t Limit
Limit the number of results returned (0 means no limit).
Definition: CodeComplete.h:71
Quality
SignatureQualitySignals Quality
Definition: CodeComplete.cpp:796
Contents
llvm::StringRef Contents
Definition: CodeComplete.cpp:1021
clang::clangd::CodeCompleteOptions::NeverParse
Always use text-based completion.
Definition: CodeComplete.h:130
Index.h
VFS
llvm::IntrusiveRefCntPtr< llvm::vfs::FileSystem > VFS
Definition: CodeComplete.cpp:1023
clang::clangd::CodeCompleteResult
Definition: CodeComplete.h:215
clang::clangd::CodeCompletion::Scores
Definition: CodeComplete.h:186
Symbol.h
clang::clangd::CodeCompleteOptions::EnableSnippets
bool EnableSnippets
When true, completion items will contain expandable code snippets in completion (e.g.
Definition: CodeComplete.h:46
clang::clangd::CompletionItem
Definition: Protocol.h:951
clang::clangd::CodeCompleteResult::Completions
std::vector< CodeCompletion > Completions
Definition: CodeComplete.h:216
clang::clangd::SymbolIndex
Interface for symbol indexes that can be used for searching or matching symbols among a set of symbol...
Definition: Index.h:85
Protocol.h
clang::clangd::Position
Definition: Protocol.h:127
clang::clangd::CodeCompleteOptions::ParseIfReady
Run the parser if inputs (preamble) are ready.
Definition: CodeComplete.h:128
clang::clangd::PathRef
llvm::StringRef PathRef
A typedef to represent a ref to file path.
Definition: Path.h:23
clang::clangd::CodeCompletion::SnippetSuffix
std::string SnippetSuffix
Definition: CodeComplete.h:148
clang::clangd::CodeCompletion::Name
std::string Name
Definition: CodeComplete.h:139
clang::clangd::CodeCompleteOptions::CodeCompletionParse
CodeCompletionParse
Whether to use the clang parser, or fallback to text-based completion (using identifiers in the curre...
Definition: CodeComplete.h:122
clang::clangd::CodeCompletion::ReturnType
std::string ReturnType
Definition: CodeComplete.h:150
clang::clangd::CodeCompletion::IncludeCandidate::Insertion
llvm::Optional< TextEdit > Insertion
Definition: CodeComplete.h:170
clang::clangd::CodeCompleteOptions::IncludeInsertionIndicator::Insert
std::string Insert
Definition: CodeComplete.h:81
Headers.h
clang::clangd::CompletionPrefix
Definition: CodeComplete.h:282
clang::clangd::CompletionItemKind
CompletionItemKind
The kind of a completion entry.
Definition: Protocol.h:260
clang::clangd::signatureHelp
SignatureHelp signatureHelp(PathRef FileName, const tooling::CompileCommand &Command, const PreambleData *Preamble, llvm::StringRef Contents, Position Pos, llvm::IntrusiveRefCntPtr< llvm::vfs::FileSystem > VFS, const SymbolIndex *Index)
Definition: CodeComplete.cpp:1749
Kind
BindArgumentKind Kind
Definition: AvoidBindCheck.cpp:57
clang::clangd::SpeculativeFuzzyFind::CachedReq
llvm::Optional< FuzzyFindRequest > CachedReq
A cached request from past code completions.
Definition: CodeComplete.h:231
clang::clangd::CodeCompletion::Documentation
std::string Documentation
Definition: CodeComplete.h:151
clang::clangd::CodeCompleteOptions::IncludeFixIts
bool IncludeFixIts
Include completions that require small corrections, e.g.
Definition: CodeComplete.h:107
clang::clangd::CompletionItemKind::Missing
clang::clangd::CodeCompleteOptions::IncludeComments
bool IncludeComments
Add comments to code completion results, if available.
Definition: CodeComplete.h:57
clang::clangd::CodeCompletion::Score
Scores Score
Definition: CodeComplete.h:206
clang::clangd::CodeCompleteOptions::IWYU
Definition: CodeComplete.h:74
clang::clangd::CodeCompleteOptions::IncludeCodePatterns
bool IncludeCodePatterns
Add code patterns to completion results.
Definition: CodeComplete.h:51
clang::clangd::Range
Definition: Protocol.h:156
clang::clangd::isIndexedForCodeCompletion
bool isIndexedForCodeCompletion(const NamedDecl &ND, ASTContext &ASTCtx)
Definition: CodeComplete.cpp:1774
clang::clangd::CodeCompleteOptions::SpeculativeIndexRequest
bool SpeculativeIndexRequest
If set to true, this will send an asynchronous speculative index request, based on the index request ...
Definition: CodeComplete.h:96
clang::clangd::SpeculativeFuzzyFind
A speculative and asynchronous fuzzy find index request (based on cached request) that can be sent be...
Definition: CodeComplete.h:228
clang::clangd::CodeCompletion::Scope
std::string Scope
Definition: CodeComplete.h:142
clang::clangd::CodeCompleteOptions::IncludeInsertionIndicator
A visual indicator to prepend to the completion label to indicate whether completion result would tri...
Definition: CodeComplete.h:80
clang::clangd::CodeCompletion::Includes
llvm::SmallVector< IncludeCandidate, 1 > Includes
Definition: CodeComplete.h:176
clang::clangd::CodeCompleteOptions
Definition: CodeComplete.h:39
clang::clangd::CodeCompleteOptions::IncludeIneligibleResults
bool IncludeIneligibleResults
Include results that are not legal completions in the current context.
Definition: CodeComplete.h:61
clang::clangd::CodeCompleteOptions::RunParser
enum clang::clangd::CodeCompleteOptions::CodeCompletionParse RunParser
clang::clangd::CodeCompleteOptions::BundleOverloads
llvm::Optional< bool > BundleOverloads
Combine overloads into a single completion item where possible.
Definition: CodeComplete.h:67
clang::clangd::SpeculativeFuzzyFind::NewReq
llvm::Optional< FuzzyFindRequest > NewReq
The actual request used by codeComplete().
Definition: CodeComplete.h:234
FileName
PathRef FileName
Definition: CodeComplete.cpp:1018
clang::clangd::CodeCompleteOptions::NeverInsert
Definition: CodeComplete.h:75
Pos
Position Pos
Definition: SourceCode.cpp:772
clang::clangd::Context
A context is an immutable container for per-request data that must be propagated through layers that ...
Definition: Context.h:69
clang::clangd::CodeCompleteOptions::getClangCompleteOpts
clang::CodeCompleteOptions getClangCompleteOpts() const
Returns options that can be passed to clang&#39;s completion engine.
Definition: CodeComplete.cpp:1688
clang::clangd::CompletionPrefix::Qualifier
llvm::StringRef Qualifier
Definition: CodeComplete.h:288
clang::clangd::CodeCompletion::IncludeCandidate
Definition: CodeComplete.h:164
clang::clangd::CompletionPrefix::Name
llvm::StringRef Name
Definition: CodeComplete.h:285
clang::clangd::codeComplete
CodeCompleteResult codeComplete(PathRef FileName, const tooling::CompileCommand &Command, const PreambleData *Preamble, llvm::StringRef Contents, Position Pos, llvm::IntrusiveRefCntPtr< llvm::vfs::FileSystem > VFS, CodeCompleteOptions Opts, SpeculativeFuzzyFind *SpecFuzzyFind)
Definition: CodeComplete.cpp:1731
clang::clangd::CodeCompleteOptions::Index
const SymbolIndex * Index
If Index is set, it is used to augment the code completion results.
Definition: CodeComplete.h:103
Logger.h
Offset
size_t Offset
Definition: CodeComplete.cpp:1022
clang::clangd::SignatureHelp
Represents the signature of a callable.
Definition: Protocol.h:1061
clang::clangd::CodeCompleteOptions::AlwaysParse
Block until we can run the parser (e.g.
Definition: CodeComplete.h:125
Preamble
const PreambleData * Preamble
Definition: CodeComplete.cpp:1020
clang
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
Definition: ApplyReplacements.h:27
Path.h
clang::clangd::CodeCompleteOptions::IncludeIndicator
struct clang::clangd::CodeCompleteOptions::IncludeInsertionIndicator IncludeIndicator
clang::clangd::CodeCompleteOptions::IncludeMacros
bool IncludeMacros
Add macros to code completion results.
Definition: CodeComplete.h:54
SymbolOrigin.h
clang::clangd::CodeCompleteOptions::IncludeInsertion
IncludeInsertion
Definition: CodeComplete.h:73
clang::clangd::SymbolOrigin::Unknown
clang::clangd::CodeCompleteOptions::EnableFunctionArgSnippets
bool EnableFunctionArgSnippets
Whether to generate snippets for function arguments on code-completion.
Definition: CodeComplete.h:111
clang::clangd::CodeCompletion::RequiredQualifier
std::string RequiredQualifier
Definition: CodeComplete.h:144
clang::clangd::CodeCompleteOptions::IncludeInsertionIndicator::NoInsert
std::string NoInsert
Definition: CodeComplete.h:82
clang::clangd::CodeCompleteOptions::AllScopes
bool AllScopes
Whether to include index symbols that are not defined in the scopes visible from the code completion ...
Definition: CodeComplete.h:118
clang::clangd::guessCompletionPrefix
CompletionPrefix guessCompletionPrefix(llvm::StringRef Content, unsigned Offset)
Definition: CodeComplete.cpp:1708
clang::clangd::operator<<
llvm::raw_ostream & operator<<(llvm::raw_ostream &OS, const CodeCompletion &C)
Definition: CodeComplete.cpp:1850
clang::clangd::PreambleData
The parsed preamble and associated data.
Definition: Preamble.h:45
clang::clangd::CodeCompletion
Definition: CodeComplete.h:137
clang::clangd::SymbolOrigin
SymbolOrigin
Definition: SymbolOrigin.h:21
clang::clangd::CodeCompletion::IncludeCandidate::Header
std::string Header
Definition: CodeComplete.h:168
clang::clangd::CodeCompleteOptions::InsertIncludes
enum clang::clangd::CodeCompleteOptions::IncludeInsertion InsertIncludes
clang::clangd::CodeCompletion::CompletionTokenRange
Range CompletionTokenRange
Holds the range of the token we are going to replace with this completion.
Definition: CodeComplete.h:183
clang::clangd::CodeCompletion::FixIts
std::vector< TextEdit > FixIts
Holds information about small corrections that needs to be done.
Definition: CodeComplete.h:180