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