clang-tools 17.0.0git
CodeComplete.cpp
Go to the documentation of this file.
1//===--- CodeComplete.cpp ----------------------------------------*- 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 has several moving parts:
10// - AST-based completions are provided using the completion hooks in Sema.
11// - external completions are retrieved from the index (using hints from Sema)
12// - the two sources overlap, and must be merged and overloads bundled
13// - results must be scored and ranked (see Quality.h) before rendering
14//
15// Signature help works in a similar way as code completion, but it is simpler:
16// it's purely AST-based, and there are few candidates.
17//
18//===----------------------------------------------------------------------===//
19
20#include "CodeComplete.h"
21#include "AST.h"
23#include "Compiler.h"
24#include "ExpectedTypes.h"
25#include "Feature.h"
26#include "FileDistance.h"
27#include "FuzzyMatch.h"
28#include "Headers.h"
29#include "Hover.h"
30#include "Preamble.h"
31#include "Protocol.h"
32#include "Quality.h"
33#include "SourceCode.h"
34#include "URI.h"
35#include "index/Index.h"
36#include "index/Symbol.h"
37#include "index/SymbolOrigin.h"
38#include "support/Logger.h"
39#include "support/Markup.h"
40#include "support/Threading.h"
42#include "support/Trace.h"
43#include "clang/AST/Decl.h"
44#include "clang/AST/DeclBase.h"
45#include "clang/Basic/CharInfo.h"
46#include "clang/Basic/LangOptions.h"
47#include "clang/Basic/SourceLocation.h"
48#include "clang/Basic/TokenKinds.h"
49#include "clang/Format/Format.h"
50#include "clang/Frontend/CompilerInstance.h"
51#include "clang/Frontend/FrontendActions.h"
52#include "clang/Lex/ExternalPreprocessorSource.h"
53#include "clang/Lex/Lexer.h"
54#include "clang/Lex/Preprocessor.h"
55#include "clang/Lex/PreprocessorOptions.h"
56#include "clang/Sema/CodeCompleteConsumer.h"
57#include "clang/Sema/DeclSpec.h"
58#include "clang/Sema/Sema.h"
59#include "llvm/ADT/ArrayRef.h"
60#include "llvm/ADT/SmallVector.h"
61#include "llvm/ADT/StringExtras.h"
62#include "llvm/ADT/StringRef.h"
63#include "llvm/Support/Casting.h"
64#include "llvm/Support/Compiler.h"
65#include "llvm/Support/Debug.h"
66#include "llvm/Support/Error.h"
67#include "llvm/Support/FormatVariadic.h"
68#include "llvm/Support/ScopedPrinter.h"
69#include <algorithm>
70#include <iterator>
71#include <limits>
72#include <optional>
73#include <utility>
74
75// We log detailed candidate here if you run with -debug-only=codecomplete.
76#define DEBUG_TYPE "CodeComplete"
77
78namespace clang {
79namespace clangd {
80
81#if CLANGD_DECISION_FOREST
85#else
88#endif
89
90namespace {
91
92CompletionItemKind toCompletionItemKind(index::SymbolKind Kind) {
93 using SK = index::SymbolKind;
94 switch (Kind) {
95 case SK::Unknown:
97 case SK::Module:
98 case SK::Namespace:
99 case SK::NamespaceAlias:
101 case SK::Macro:
103 case SK::Enum:
105 case SK::Struct:
107 case SK::Class:
108 case SK::Extension:
109 case SK::Union:
111 case SK::Protocol:
112 // Use interface instead of class for differentiation of classes and
113 // protocols with the same name (e.g. @interface NSObject vs. @protocol
114 // NSObject).
116 case SK::TypeAlias:
117 // We use the same kind as the VSCode C++ extension.
118 // FIXME: pick a better option when we have one.
120 case SK::Using:
122 case SK::Function:
123 case SK::ConversionFunction:
125 case SK::Variable:
126 case SK::Parameter:
127 case SK::NonTypeTemplateParm:
129 case SK::Field:
131 case SK::EnumConstant:
133 case SK::InstanceMethod:
134 case SK::ClassMethod:
135 case SK::StaticMethod:
136 case SK::Destructor:
138 case SK::InstanceProperty:
139 case SK::ClassProperty:
140 case SK::StaticProperty:
142 case SK::Constructor:
144 case SK::TemplateTypeParm:
145 case SK::TemplateTemplateParm:
147 case SK::Concept:
149 }
150 llvm_unreachable("Unhandled clang::index::SymbolKind.");
151}
152
153CompletionItemKind toCompletionItemKind(const CodeCompletionResult &Res,
154 CodeCompletionContext::Kind CtxKind) {
155 if (Res.Declaration)
156 return toCompletionItemKind(index::getSymbolInfo(Res.Declaration).Kind);
157 if (CtxKind == CodeCompletionContext::CCC_IncludedFile)
159 switch (Res.Kind) {
160 case CodeCompletionResult::RK_Declaration:
161 llvm_unreachable("RK_Declaration without Decl");
162 case CodeCompletionResult::RK_Keyword:
164 case CodeCompletionResult::RK_Macro:
165 // There is no 'Macro' kind in LSP.
166 // Avoid using 'Text' to avoid confusion with client-side word-based
167 // completion proposals.
168 return Res.MacroDefInfo && Res.MacroDefInfo->isFunctionLike()
171 case CodeCompletionResult::RK_Pattern:
173 }
174 llvm_unreachable("Unhandled CodeCompletionResult::ResultKind.");
175}
176
177// FIXME: find a home for this (that can depend on both markup and Protocol).
178MarkupContent renderDoc(const markup::Document &Doc, MarkupKind Kind) {
179 MarkupContent Result;
180 Result.kind = Kind;
181 switch (Kind) {
183 Result.value.append(Doc.asPlainText());
184 break;
186 Result.value.append(Doc.asMarkdown());
187 break;
188 }
189 return Result;
190}
191
192Symbol::IncludeDirective insertionDirective(const CodeCompleteOptions &Opts) {
193 if (!Opts.ImportInsertions || !Opts.MainFileSignals)
196}
197
198// Identifier code completion result.
199struct RawIdentifier {
200 llvm::StringRef Name;
201 unsigned References; // # of usages in file.
202};
203
204/// A code completion result, in clang-native form.
205/// It may be promoted to a CompletionItem if it's among the top-ranked results.
206struct CompletionCandidate {
207 llvm::StringRef Name; // Used for filtering and sorting.
208 // We may have a result from Sema, from the index, or both.
209 const CodeCompletionResult *SemaResult = nullptr;
210 const Symbol *IndexResult = nullptr;
211 const RawIdentifier *IdentifierResult = nullptr;
212 llvm::SmallVector<SymbolInclude, 1> RankedIncludeHeaders;
213
214 // Returns a token identifying the overload set this is part of.
215 // 0 indicates it's not part of any overload set.
216 size_t overloadSet(const CodeCompleteOptions &Opts, llvm::StringRef FileName,
217 IncludeInserter *Inserter) const {
218 if (!Opts.BundleOverloads.value_or(false))
219 return 0;
220
221 // Depending on the index implementation, we can see different header
222 // strings (literal or URI) mapping to the same file. We still want to
223 // bundle those, so we must resolve the header to be included here.
224 std::string HeaderForHash;
225 if (Inserter) {
226 if (auto Header = headerToInsertIfAllowed(Opts)) {
227 if (auto HeaderFile = toHeaderFile(*Header, FileName)) {
228 if (auto Spelled =
229 Inserter->calculateIncludePath(*HeaderFile, FileName))
230 HeaderForHash = *Spelled;
231 } else {
232 vlog("Code completion header path manipulation failed {0}",
233 HeaderFile.takeError());
234 }
235 }
236 }
237
238 llvm::SmallString<256> Scratch;
239 if (IndexResult) {
240 switch (IndexResult->SymInfo.Kind) {
241 case index::SymbolKind::ClassMethod:
242 case index::SymbolKind::InstanceMethod:
243 case index::SymbolKind::StaticMethod:
244#ifndef NDEBUG
245 llvm_unreachable("Don't expect members from index in code completion");
246#else
247 [[fallthrough]];
248#endif
249 case index::SymbolKind::Function:
250 // We can't group overloads together that need different #includes.
251 // This could break #include insertion.
252 return llvm::hash_combine(
253 (IndexResult->Scope + IndexResult->Name).toStringRef(Scratch),
254 HeaderForHash);
255 default:
256 return 0;
257 }
258 }
259 if (SemaResult) {
260 // We need to make sure we're consistent with the IndexResult case!
261 const NamedDecl *D = SemaResult->Declaration;
262 if (!D || !D->isFunctionOrFunctionTemplate())
263 return 0;
264 {
265 llvm::raw_svector_ostream OS(Scratch);
266 D->printQualifiedName(OS);
267 }
268 return llvm::hash_combine(Scratch, HeaderForHash);
269 }
270 assert(IdentifierResult);
271 return 0;
272 }
273
274 // The best header to include if include insertion is allowed.
275 std::optional<llvm::StringRef>
276 headerToInsertIfAllowed(const CodeCompleteOptions &Opts) const {
277 if (Opts.InsertIncludes == CodeCompleteOptions::NeverInsert ||
278 RankedIncludeHeaders.empty())
279 return std::nullopt;
280 if (SemaResult && SemaResult->Declaration) {
281 // Avoid inserting new #include if the declaration is found in the current
282 // file e.g. the symbol is forward declared.
283 auto &SM = SemaResult->Declaration->getASTContext().getSourceManager();
284 for (const Decl *RD : SemaResult->Declaration->redecls())
285 if (SM.isInMainFile(SM.getExpansionLoc(RD->getBeginLoc())))
286 return std::nullopt;
287 }
288 Symbol::IncludeDirective Directive = insertionDirective(Opts);
289 for (const auto &Inc : RankedIncludeHeaders)
290 if ((Inc.Directive & Directive) != 0)
291 return Inc.Header;
292 return std::nullopt;
293 }
294
295 using Bundle = llvm::SmallVector<CompletionCandidate, 4>;
296};
297using ScoredBundle =
298 std::pair<CompletionCandidate::Bundle, CodeCompletion::Scores>;
299struct ScoredBundleGreater {
300 bool operator()(const ScoredBundle &L, const ScoredBundle &R) {
301 if (L.second.Total != R.second.Total)
302 return L.second.Total > R.second.Total;
303 return L.first.front().Name <
304 R.first.front().Name; // Earlier name is better.
305 }
306};
307
308// Assembles a code completion out of a bundle of >=1 completion candidates.
309// Many of the expensive strings are only computed at this point, once we know
310// the candidate bundle is going to be returned.
311//
312// Many fields are the same for all candidates in a bundle (e.g. name), and are
313// computed from the first candidate, in the constructor.
314// Others vary per candidate, so add() must be called for remaining candidates.
315struct CodeCompletionBuilder {
316 CodeCompletionBuilder(ASTContext *ASTCtx, const CompletionCandidate &C,
317 CodeCompletionString *SemaCCS,
318 llvm::ArrayRef<std::string> AccessibleScopes,
319 const IncludeInserter &Includes,
320 llvm::StringRef FileName,
321 CodeCompletionContext::Kind ContextKind,
322 const CodeCompleteOptions &Opts,
323 bool IsUsingDeclaration, tok::TokenKind NextTokenKind)
324 : ASTCtx(ASTCtx),
325 EnableFunctionArgSnippets(Opts.EnableFunctionArgSnippets),
326 IsUsingDeclaration(IsUsingDeclaration), NextTokenKind(NextTokenKind) {
327 Completion.Deprecated = true; // cleared by any non-deprecated overload.
328 add(C, SemaCCS);
329 if (C.SemaResult) {
330 assert(ASTCtx);
331 Completion.Origin |= SymbolOrigin::AST;
332 Completion.Name = std::string(llvm::StringRef(SemaCCS->getTypedText()));
333 Completion.FilterText = SemaCCS->getAllTypedText();
334 if (Completion.Scope.empty()) {
335 if ((C.SemaResult->Kind == CodeCompletionResult::RK_Declaration) ||
336 (C.SemaResult->Kind == CodeCompletionResult::RK_Pattern))
337 if (const auto *D = C.SemaResult->getDeclaration())
338 if (const auto *ND = dyn_cast<NamedDecl>(D))
339 Completion.Scope = std::string(
341 }
342 Completion.Kind = toCompletionItemKind(*C.SemaResult, ContextKind);
343 // Sema could provide more info on whether the completion was a file or
344 // folder.
345 if (Completion.Kind == CompletionItemKind::File &&
346 Completion.Name.back() == '/')
347 Completion.Kind = CompletionItemKind::Folder;
348 for (const auto &FixIt : C.SemaResult->FixIts) {
349 Completion.FixIts.push_back(toTextEdit(
350 FixIt, ASTCtx->getSourceManager(), ASTCtx->getLangOpts()));
351 }
352 llvm::sort(Completion.FixIts, [](const TextEdit &X, const TextEdit &Y) {
353 return std::tie(X.range.start.line, X.range.start.character) <
354 std::tie(Y.range.start.line, Y.range.start.character);
355 });
356 }
357 if (C.IndexResult) {
358 Completion.Origin |= C.IndexResult->Origin;
359 if (Completion.Scope.empty())
360 Completion.Scope = std::string(C.IndexResult->Scope);
361 if (Completion.Kind == CompletionItemKind::Missing)
362 Completion.Kind = toCompletionItemKind(C.IndexResult->SymInfo.Kind);
363 if (Completion.Name.empty())
364 Completion.Name = std::string(C.IndexResult->Name);
365 if (Completion.FilterText.empty())
366 Completion.FilterText = Completion.Name;
367 // If the completion was visible to Sema, no qualifier is needed. This
368 // avoids unneeded qualifiers in cases like with `using ns::X`.
369 if (Completion.RequiredQualifier.empty() && !C.SemaResult) {
370 llvm::StringRef ShortestQualifier = C.IndexResult->Scope;
371 for (llvm::StringRef Scope : AccessibleScopes) {
372 llvm::StringRef Qualifier = C.IndexResult->Scope;
373 if (Qualifier.consume_front(Scope) &&
374 Qualifier.size() < ShortestQualifier.size())
375 ShortestQualifier = Qualifier;
376 }
377 Completion.RequiredQualifier = std::string(ShortestQualifier);
378 }
379 }
380 if (C.IdentifierResult) {
381 Completion.Origin |= SymbolOrigin::Identifier;
382 Completion.Kind = CompletionItemKind::Text;
383 Completion.Name = std::string(C.IdentifierResult->Name);
384 Completion.FilterText = Completion.Name;
385 }
386
387 // Turn absolute path into a literal string that can be #included.
388 auto Inserted = [&](llvm::StringRef Header)
389 -> llvm::Expected<std::pair<std::string, bool>> {
390 auto ResolvedDeclaring =
391 URI::resolve(C.IndexResult->CanonicalDeclaration.FileURI, FileName);
392 if (!ResolvedDeclaring)
393 return ResolvedDeclaring.takeError();
394 auto ResolvedInserted = toHeaderFile(Header, FileName);
395 if (!ResolvedInserted)
396 return ResolvedInserted.takeError();
397 auto Spelled = Includes.calculateIncludePath(*ResolvedInserted, FileName);
398 if (!Spelled)
399 return error("Header not on include path");
400 return std::make_pair(
401 std::move(*Spelled),
402 Includes.shouldInsertInclude(*ResolvedDeclaring, *ResolvedInserted));
403 };
404 bool ShouldInsert = C.headerToInsertIfAllowed(Opts).has_value();
405 Symbol::IncludeDirective Directive = insertionDirective(Opts);
406 // Calculate include paths and edits for all possible headers.
407 for (const auto &Inc : C.RankedIncludeHeaders) {
408 if ((Inc.Directive & Directive) == 0)
409 continue;
410
411 if (auto ToInclude = Inserted(Inc.Header)) {
412 CodeCompletion::IncludeCandidate Include;
413 Include.Header = ToInclude->first;
414 if (ToInclude->second && ShouldInsert)
415 Include.Insertion = Includes.insert(
416 ToInclude->first, Directive == Symbol::Import
417 ? tooling::IncludeDirective::Import
418 : tooling::IncludeDirective::Include);
419 Completion.Includes.push_back(std::move(Include));
420 } else
421 log("Failed to generate include insertion edits for adding header "
422 "(FileURI='{0}', IncludeHeader='{1}') into {2}: {3}",
423 C.IndexResult->CanonicalDeclaration.FileURI, Inc.Header, FileName,
424 ToInclude.takeError());
425 }
426 // Prefer includes that do not need edits (i.e. already exist).
427 std::stable_partition(Completion.Includes.begin(),
428 Completion.Includes.end(),
429 [](const CodeCompletion::IncludeCandidate &I) {
430 return !I.Insertion.has_value();
431 });
432 }
433
434 void add(const CompletionCandidate &C, CodeCompletionString *SemaCCS) {
435 assert(bool(C.SemaResult) == bool(SemaCCS));
436 Bundled.emplace_back();
437 BundledEntry &S = Bundled.back();
438 if (C.SemaResult) {
439 getSignature(*SemaCCS, &S.Signature, &S.SnippetSuffix, C.SemaResult->Kind,
440 C.SemaResult->CursorKind, &Completion.RequiredQualifier);
441 if (!C.SemaResult->FunctionCanBeCall)
442 S.SnippetSuffix.clear();
443 S.ReturnType = getReturnType(*SemaCCS);
444 } else if (C.IndexResult) {
445 S.Signature = std::string(C.IndexResult->Signature);
446 S.SnippetSuffix = std::string(C.IndexResult->CompletionSnippetSuffix);
447 S.ReturnType = std::string(C.IndexResult->ReturnType);
448 }
449 if (!Completion.Documentation) {
450 auto SetDoc = [&](llvm::StringRef Doc) {
451 if (!Doc.empty()) {
452 Completion.Documentation.emplace();
453 parseDocumentation(Doc, *Completion.Documentation);
454 }
455 };
456 if (C.IndexResult) {
457 SetDoc(C.IndexResult->Documentation);
458 } else if (C.SemaResult) {
459 const auto DocComment = getDocComment(*ASTCtx, *C.SemaResult,
460 /*CommentsFromHeaders=*/false);
461 SetDoc(formatDocumentation(*SemaCCS, DocComment));
462 }
463 }
464 if (Completion.Deprecated) {
465 if (C.SemaResult)
466 Completion.Deprecated &=
467 C.SemaResult->Availability == CXAvailability_Deprecated;
468 if (C.IndexResult)
469 Completion.Deprecated &=
470 bool(C.IndexResult->Flags & Symbol::Deprecated);
471 }
472 }
473
474 CodeCompletion build() {
475 Completion.ReturnType = summarizeReturnType();
476 Completion.Signature = summarizeSignature();
477 Completion.SnippetSuffix = summarizeSnippet();
478 Completion.BundleSize = Bundled.size();
479 return std::move(Completion);
480 }
481
482private:
483 struct BundledEntry {
484 std::string SnippetSuffix;
485 std::string Signature;
486 std::string ReturnType;
487 };
488
489 // If all BundledEntries have the same value for a property, return it.
490 template <std::string BundledEntry::*Member>
491 const std::string *onlyValue() const {
492 auto B = Bundled.begin(), E = Bundled.end();
493 for (auto *I = B + 1; I != E; ++I)
494 if (I->*Member != B->*Member)
495 return nullptr;
496 return &(B->*Member);
497 }
498
499 template <bool BundledEntry::*Member> const bool *onlyValue() const {
500 auto B = Bundled.begin(), E = Bundled.end();
501 for (auto *I = B + 1; I != E; ++I)
502 if (I->*Member != B->*Member)
503 return nullptr;
504 return &(B->*Member);
505 }
506
507 std::string summarizeReturnType() const {
508 if (auto *RT = onlyValue<&BundledEntry::ReturnType>())
509 return *RT;
510 return "";
511 }
512
513 std::string summarizeSnippet() const {
514 if (IsUsingDeclaration)
515 return "";
516 auto *Snippet = onlyValue<&BundledEntry::SnippetSuffix>();
517 if (!Snippet)
518 // All bundles are function calls.
519 // FIXME(ibiryukov): sometimes add template arguments to a snippet, e.g.
520 // we need to complete 'forward<$1>($0)'.
521 return "($0)";
522
523 if (Snippet->empty())
524 return "";
525
526 bool MayHaveArgList = Completion.Kind == CompletionItemKind::Function ||
527 Completion.Kind == CompletionItemKind::Method ||
528 Completion.Kind == CompletionItemKind::Constructor ||
529 Completion.Kind == CompletionItemKind::Text /*Macro*/;
530 // If likely arg list already exists, don't add new parens & placeholders.
531 // Snippet: function(int x, int y)
532 // func^(1,2) -> function(1, 2)
533 // NOT function(int x, int y)(1, 2)
534 if (MayHaveArgList) {
535 // Check for a template argument list in the code.
536 // Snippet: function<class T>(int x)
537 // fu^<int>(1) -> function<int>(1)
538 if (NextTokenKind == tok::less && Snippet->front() == '<')
539 return "";
540 // Potentially followed by regular argument list.
541 if (NextTokenKind == tok::l_paren) {
542 // Snippet: function<class T>(int x)
543 // fu^(1,2) -> function<class T>(1, 2)
544 if (Snippet->front() == '<') {
545 // Find matching '>', handling nested brackets.
546 int Balance = 0;
547 size_t I = 0;
548 do {
549 if (Snippet->at(I) == '>')
550 --Balance;
551 else if (Snippet->at(I) == '<')
552 ++Balance;
553 ++I;
554 } while (Balance > 0);
555 return Snippet->substr(0, I);
556 }
557 return "";
558 }
559 }
560 if (EnableFunctionArgSnippets)
561 return *Snippet;
562
563 // Replace argument snippets with a simplified pattern.
564 if (MayHaveArgList) {
565 // Functions snippets can be of 2 types:
566 // - containing only function arguments, e.g.
567 // foo(${1:int p1}, ${2:int p2});
568 // We transform this pattern to '($0)' or '()'.
569 // - template arguments and function arguments, e.g.
570 // foo<${1:class}>(${2:int p1}).
571 // We transform this pattern to '<$1>()$0' or '<$0>()'.
572
573 bool EmptyArgs = llvm::StringRef(*Snippet).endswith("()");
574 if (Snippet->front() == '<')
575 return EmptyArgs ? "<$1>()$0" : "<$1>($0)";
576 if (Snippet->front() == '(')
577 return EmptyArgs ? "()" : "($0)";
578 return *Snippet; // Not an arg snippet?
579 }
580 // 'CompletionItemKind::Interface' matches template type aliases.
581 if (Completion.Kind == CompletionItemKind::Interface ||
582 Completion.Kind == CompletionItemKind::Class) {
583 if (Snippet->front() != '<')
584 return *Snippet; // Not an arg snippet?
585
586 // Classes and template using aliases can only have template arguments,
587 // e.g. Foo<${1:class}>.
588 if (llvm::StringRef(*Snippet).endswith("<>"))
589 return "<>"; // can happen with defaulted template arguments.
590 return "<$0>";
591 }
592 return *Snippet;
593 }
594
595 std::string summarizeSignature() const {
596 if (auto *Signature = onlyValue<&BundledEntry::Signature>())
597 return *Signature;
598 // All bundles are function calls.
599 return "(…)";
600 }
601
602 // ASTCtx can be nullptr if not run with sema.
603 ASTContext *ASTCtx;
604 CodeCompletion Completion;
605 llvm::SmallVector<BundledEntry, 1> Bundled;
606 bool EnableFunctionArgSnippets;
607 // No snippets will be generated for using declarations and when the function
608 // arguments are already present.
609 bool IsUsingDeclaration;
610 tok::TokenKind NextTokenKind;
611};
612
613// Determine the symbol ID for a Sema code completion result, if possible.
614SymbolID getSymbolID(const CodeCompletionResult &R, const SourceManager &SM) {
615 switch (R.Kind) {
616 case CodeCompletionResult::RK_Declaration:
617 case CodeCompletionResult::RK_Pattern: {
618 // Computing USR caches linkage, which may change after code completion.
619 if (hasUnstableLinkage(R.Declaration))
620 return {};
621 return clang::clangd::getSymbolID(R.Declaration);
622 }
623 case CodeCompletionResult::RK_Macro:
624 return clang::clangd::getSymbolID(R.Macro->getName(), R.MacroDefInfo, SM);
625 case CodeCompletionResult::RK_Keyword:
626 return {};
627 }
628 llvm_unreachable("unknown CodeCompletionResult kind");
629}
630
631// Scopes of the partial identifier we're trying to complete.
632// It is used when we query the index for more completion results.
633struct SpecifiedScope {
634 // The scopes we should look in, determined by Sema.
635 //
636 // If the qualifier was fully resolved, we look for completions in these
637 // scopes; if there is an unresolved part of the qualifier, it should be
638 // resolved within these scopes.
639 //
640 // Examples of qualified completion:
641 //
642 // "::vec" => {""}
643 // "using namespace std; ::vec^" => {"", "std::"}
644 // "namespace ns {using namespace std;} ns::^" => {"ns::", "std::"}
645 // "std::vec^" => {""} // "std" unresolved
646 //
647 // Examples of unqualified completion:
648 //
649 // "vec^" => {""}
650 // "using namespace std; vec^" => {"", "std::"}
651 // "namespace ns {inline namespace ni { struct Foo {}}}
652 // using namespace ns::ni; Fo^ " => {"", "ns::ni::"}
653 // "using namespace std; namespace ns { vec^ }" => {"ns::", "std::", ""}
654 //
655 // "" for global namespace, "ns::" for normal namespace.
656 std::vector<std::string> AccessibleScopes;
657 // This is an overestimate of AccessibleScopes, e.g. it ignores inline
658 // namespaces, to fetch more relevant symbols from index.
659 std::vector<std::string> QueryScopes;
660 // The full scope qualifier as typed by the user (without the leading "::").
661 // Set if the qualifier is not fully resolved by Sema.
662 std::optional<std::string> UnresolvedQualifier;
663
664 std::optional<std::string> EnclosingNamespace;
665
666 bool AllowAllScopes = false;
667
668 // Scopes that are accessible from current context. Used for dropping
669 // unnecessary namespecifiers.
670 std::vector<std::string> scopesForQualification() {
671 std::set<std::string> Results;
672 for (llvm::StringRef AS : AccessibleScopes)
673 Results.insert(
674 (AS + (UnresolvedQualifier ? *UnresolvedQualifier : "")).str());
675 return {Results.begin(), Results.end()};
676 }
677
678 // Construct scopes being queried in indexes. The results are deduplicated.
679 // This method formats the scopes to match the index request representation.
680 std::vector<std::string> scopesForIndexQuery() {
681 // The enclosing namespace must be first, it gets a quality boost.
682 std::vector<std::string> EnclosingAtFront;
683 if (EnclosingNamespace.has_value())
684 EnclosingAtFront.push_back(*EnclosingNamespace);
685 std::set<std::string> Deduplicated;
686 for (llvm::StringRef S : QueryScopes)
687 if (S != EnclosingNamespace)
688 Deduplicated.insert((S + UnresolvedQualifier.value_or("")).str());
689
690 EnclosingAtFront.reserve(EnclosingAtFront.size() + Deduplicated.size());
691 llvm::copy(Deduplicated, std::back_inserter(EnclosingAtFront));
692
693 return EnclosingAtFront;
694 }
695};
696
697// Get all scopes that will be queried in indexes and whether symbols from
698// any scope is allowed. The first scope in the list is the preferred scope
699// (e.g. enclosing namespace).
700SpecifiedScope getQueryScopes(CodeCompletionContext &CCContext,
701 const Sema &CCSema,
702 const CompletionPrefix &HeuristicPrefix,
703 const CodeCompleteOptions &Opts) {
704 SpecifiedScope Scopes;
705 for (auto *Context : CCContext.getVisitedContexts()) {
706 if (isa<TranslationUnitDecl>(Context)) {
707 Scopes.QueryScopes.push_back("");
708 Scopes.AccessibleScopes.push_back("");
709 } else if (const auto *ND = dyn_cast<NamespaceDecl>(Context)) {
710 Scopes.QueryScopes.push_back(printNamespaceScope(*Context));
711 Scopes.AccessibleScopes.push_back(printQualifiedName(*ND) + "::");
712 }
713 }
714
715 const CXXScopeSpec *SemaSpecifier =
716 CCContext.getCXXScopeSpecifier().value_or(nullptr);
717 // Case 1: unqualified completion.
718 if (!SemaSpecifier) {
719 // Case 2 (exception): sema saw no qualifier, but there appears to be one!
720 // This can happen e.g. in incomplete macro expansions. Use heuristics.
721 if (!HeuristicPrefix.Qualifier.empty()) {
722 vlog("Sema said no scope specifier, but we saw {0} in the source code",
723 HeuristicPrefix.Qualifier);
724 StringRef SpelledSpecifier = HeuristicPrefix.Qualifier;
725 if (SpelledSpecifier.consume_front("::")) {
726 Scopes.AccessibleScopes = {""};
727 Scopes.QueryScopes = {""};
728 }
729 Scopes.UnresolvedQualifier = std::string(SpelledSpecifier);
730 return Scopes;
731 }
732 /// FIXME: When the enclosing namespace contains an inline namespace,
733 /// it's dropped here. This leads to a behavior similar to
734 /// https://github.com/clangd/clangd/issues/1451
735 Scopes.EnclosingNamespace = printNamespaceScope(*CCSema.CurContext);
736 // Allow AllScopes completion as there is no explicit scope qualifier.
737 Scopes.AllowAllScopes = Opts.AllScopes;
738 return Scopes;
739 }
740 // Case 3: sema saw and resolved a scope qualifier.
741 if (SemaSpecifier && SemaSpecifier->isValid())
742 return Scopes;
743
744 // Case 4: There was a qualifier, and Sema didn't resolve it.
745 Scopes.QueryScopes.push_back(""); // Make sure global scope is included.
746 llvm::StringRef SpelledSpecifier = Lexer::getSourceText(
747 CharSourceRange::getCharRange(SemaSpecifier->getRange()),
748 CCSema.SourceMgr, clang::LangOptions());
749 if (SpelledSpecifier.consume_front("::"))
750 Scopes.QueryScopes = {""};
751 Scopes.UnresolvedQualifier = std::string(SpelledSpecifier);
752 // Sema excludes the trailing "::".
753 if (!Scopes.UnresolvedQualifier->empty())
754 *Scopes.UnresolvedQualifier += "::";
755
756 Scopes.AccessibleScopes = Scopes.QueryScopes;
757
758 return Scopes;
759}
760
761// Should we perform index-based completion in a context of the specified kind?
762// FIXME: consider allowing completion, but restricting the result types.
763bool contextAllowsIndex(enum CodeCompletionContext::Kind K) {
764 switch (K) {
765 case CodeCompletionContext::CCC_TopLevel:
766 case CodeCompletionContext::CCC_ObjCInterface:
767 case CodeCompletionContext::CCC_ObjCImplementation:
768 case CodeCompletionContext::CCC_ObjCIvarList:
769 case CodeCompletionContext::CCC_ClassStructUnion:
770 case CodeCompletionContext::CCC_Statement:
771 case CodeCompletionContext::CCC_Expression:
772 case CodeCompletionContext::CCC_ObjCMessageReceiver:
773 case CodeCompletionContext::CCC_EnumTag:
774 case CodeCompletionContext::CCC_UnionTag:
775 case CodeCompletionContext::CCC_ClassOrStructTag:
776 case CodeCompletionContext::CCC_ObjCProtocolName:
777 case CodeCompletionContext::CCC_Namespace:
778 case CodeCompletionContext::CCC_Type:
779 case CodeCompletionContext::CCC_ParenthesizedExpression:
780 case CodeCompletionContext::CCC_ObjCInterfaceName:
781 case CodeCompletionContext::CCC_Symbol:
782 case CodeCompletionContext::CCC_SymbolOrNewName:
783 return true;
784 case CodeCompletionContext::CCC_OtherWithMacros:
785 case CodeCompletionContext::CCC_DotMemberAccess:
786 case CodeCompletionContext::CCC_ArrowMemberAccess:
787 case CodeCompletionContext::CCC_ObjCCategoryName:
788 case CodeCompletionContext::CCC_ObjCPropertyAccess:
789 case CodeCompletionContext::CCC_MacroName:
790 case CodeCompletionContext::CCC_MacroNameUse:
791 case CodeCompletionContext::CCC_PreprocessorExpression:
792 case CodeCompletionContext::CCC_PreprocessorDirective:
793 case CodeCompletionContext::CCC_SelectorName:
794 case CodeCompletionContext::CCC_TypeQualifiers:
795 case CodeCompletionContext::CCC_ObjCInstanceMessage:
796 case CodeCompletionContext::CCC_ObjCClassMessage:
797 case CodeCompletionContext::CCC_IncludedFile:
798 case CodeCompletionContext::CCC_Attribute:
799 // FIXME: Provide identifier based completions for the following contexts:
800 case CodeCompletionContext::CCC_Other: // Be conservative.
801 case CodeCompletionContext::CCC_NaturalLanguage:
802 case CodeCompletionContext::CCC_Recovery:
803 case CodeCompletionContext::CCC_NewName:
804 return false;
805 }
806 llvm_unreachable("unknown code completion context");
807}
808
809static bool isInjectedClass(const NamedDecl &D) {
810 if (auto *R = dyn_cast_or_null<RecordDecl>(&D))
811 if (R->isInjectedClassName())
812 return true;
813 return false;
814}
815
816// Some member calls are excluded because they're so rarely useful.
817static bool isExcludedMember(const NamedDecl &D) {
818 // Destructor completion is rarely useful, and works inconsistently.
819 // (s.^ completes ~string, but s.~st^ is an error).
820 if (D.getKind() == Decl::CXXDestructor)
821 return true;
822 // Injected name may be useful for A::foo(), but who writes A::A::foo()?
823 if (isInjectedClass(D))
824 return true;
825 // Explicit calls to operators are also rare.
826 auto NameKind = D.getDeclName().getNameKind();
827 if (NameKind == DeclarationName::CXXOperatorName ||
828 NameKind == DeclarationName::CXXLiteralOperatorName ||
829 NameKind == DeclarationName::CXXConversionFunctionName)
830 return true;
831 return false;
832}
833
834// The CompletionRecorder captures Sema code-complete output, including context.
835// It filters out ignored results (but doesn't apply fuzzy-filtering yet).
836// It doesn't do scoring or conversion to CompletionItem yet, as we want to
837// merge with index results first.
838// Generally the fields and methods of this object should only be used from
839// within the callback.
840struct CompletionRecorder : public CodeCompleteConsumer {
841 CompletionRecorder(const CodeCompleteOptions &Opts,
842 llvm::unique_function<void()> ResultsCallback)
843 : CodeCompleteConsumer(Opts.getClangCompleteOpts()),
844 CCContext(CodeCompletionContext::CCC_Other), Opts(Opts),
845 CCAllocator(std::make_shared<GlobalCodeCompletionAllocator>()),
846 CCTUInfo(CCAllocator), ResultsCallback(std::move(ResultsCallback)) {
847 assert(this->ResultsCallback);
848 }
849
850 std::vector<CodeCompletionResult> Results;
851 CodeCompletionContext CCContext;
852 Sema *CCSema = nullptr; // Sema that created the results.
853 // FIXME: Sema is scary. Can we store ASTContext and Preprocessor, instead?
854
855 void ProcessCodeCompleteResults(class Sema &S, CodeCompletionContext Context,
856 CodeCompletionResult *InResults,
857 unsigned NumResults) final {
858 // Results from recovery mode are generally useless, and the callback after
859 // recovery (if any) is usually more interesting. To make sure we handle the
860 // future callback from sema, we just ignore all callbacks in recovery mode,
861 // as taking only results from recovery mode results in poor completion
862 // results.
863 // FIXME: in case there is no future sema completion callback after the
864 // recovery mode, we might still want to provide some results (e.g. trivial
865 // identifier-based completion).
866 if (Context.getKind() == CodeCompletionContext::CCC_Recovery) {
867 log("Code complete: Ignoring sema code complete callback with Recovery "
868 "context.");
869 return;
870 }
871 // If a callback is called without any sema result and the context does not
872 // support index-based completion, we simply skip it to give way to
873 // potential future callbacks with results.
874 if (NumResults == 0 && !contextAllowsIndex(Context.getKind()))
875 return;
876 if (CCSema) {
877 log("Multiple code complete callbacks (parser backtracked?). "
878 "Dropping results from context {0}, keeping results from {1}.",
879 getCompletionKindString(Context.getKind()),
880 getCompletionKindString(this->CCContext.getKind()));
881 return;
882 }
883 // Record the completion context.
884 CCSema = &S;
885 CCContext = Context;
886
887 // Retain the results we might want.
888 for (unsigned I = 0; I < NumResults; ++I) {
889 auto &Result = InResults[I];
890 // Class members that are shadowed by subclasses are usually noise.
891 if (Result.Hidden && Result.Declaration &&
892 Result.Declaration->isCXXClassMember())
893 continue;
894 if (!Opts.IncludeIneligibleResults &&
895 (Result.Availability == CXAvailability_NotAvailable ||
896 Result.Availability == CXAvailability_NotAccessible))
897 continue;
898 if (Result.Declaration &&
899 !Context.getBaseType().isNull() // is this a member-access context?
900 && isExcludedMember(*Result.Declaration))
901 continue;
902 // Skip injected class name when no class scope is not explicitly set.
903 // E.g. show injected A::A in `using A::A^` but not in "A^".
904 if (Result.Declaration && !Context.getCXXScopeSpecifier() &&
905 isInjectedClass(*Result.Declaration))
906 continue;
907 // We choose to never append '::' to completion results in clangd.
908 Result.StartsNestedNameSpecifier = false;
909 Results.push_back(Result);
910 }
911 ResultsCallback();
912 }
913
914 CodeCompletionAllocator &getAllocator() override { return *CCAllocator; }
915 CodeCompletionTUInfo &getCodeCompletionTUInfo() override { return CCTUInfo; }
916
917 // Returns the filtering/sorting name for Result, which must be from Results.
918 // Returned string is owned by this recorder (or the AST).
919 llvm::StringRef getName(const CodeCompletionResult &Result) {
920 switch (Result.Kind) {
921 case CodeCompletionResult::RK_Declaration:
922 if (auto *ID = Result.Declaration->getIdentifier())
923 return ID->getName();
924 break;
925 case CodeCompletionResult::RK_Keyword:
926 return Result.Keyword;
927 case CodeCompletionResult::RK_Macro:
928 return Result.Macro->getName();
929 case CodeCompletionResult::RK_Pattern:
930 break;
931 }
932 auto *CCS = codeCompletionString(Result);
933 const CodeCompletionString::Chunk *OnlyText = nullptr;
934 for (auto &C : *CCS) {
935 if (C.Kind != CodeCompletionString::CK_TypedText)
936 continue;
937 if (OnlyText)
938 return CCAllocator->CopyString(CCS->getAllTypedText());
939 OnlyText = &C;
940 }
941 return OnlyText ? OnlyText->Text : llvm::StringRef();
942 }
943
944 // Build a CodeCompletion string for R, which must be from Results.
945 // The CCS will be owned by this recorder.
946 CodeCompletionString *codeCompletionString(const CodeCompletionResult &R) {
947 // CodeCompletionResult doesn't seem to be const-correct. We own it, anyway.
948 return const_cast<CodeCompletionResult &>(R).CreateCodeCompletionString(
949 *CCSema, CCContext, *CCAllocator, CCTUInfo,
950 /*IncludeBriefComments=*/false);
951 }
952
953private:
954 CodeCompleteOptions Opts;
955 std::shared_ptr<GlobalCodeCompletionAllocator> CCAllocator;
956 CodeCompletionTUInfo CCTUInfo;
957 llvm::unique_function<void()> ResultsCallback;
958};
959
960struct ScoredSignature {
961 // When not null, requires documentation to be requested from the index with
962 // this ID.
963 SymbolID IDForDoc;
964 SignatureInformation Signature;
965 SignatureQualitySignals Quality;
966};
967
968// Returns the index of the parameter matching argument number "Arg.
969// This is usually just "Arg", except for variadic functions/templates, where
970// "Arg" might be higher than the number of parameters. When that happens, we
971// assume the last parameter is variadic and assume all further args are
972// part of it.
973int paramIndexForArg(const CodeCompleteConsumer::OverloadCandidate &Candidate,
974 int Arg) {
975 int NumParams = Candidate.getNumParams();
976 if (auto *T = Candidate.getFunctionType()) {
977 if (auto *Proto = T->getAs<FunctionProtoType>()) {
978 if (Proto->isVariadic())
979 ++NumParams;
980 }
981 }
982 return std::min(Arg, std::max(NumParams - 1, 0));
983}
984
985class SignatureHelpCollector final : public CodeCompleteConsumer {
986public:
987 SignatureHelpCollector(const clang::CodeCompleteOptions &CodeCompleteOpts,
988 MarkupKind DocumentationFormat,
989 const SymbolIndex *Index, SignatureHelp &SigHelp)
990 : CodeCompleteConsumer(CodeCompleteOpts), SigHelp(SigHelp),
991 Allocator(std::make_shared<clang::GlobalCodeCompletionAllocator>()),
992 CCTUInfo(Allocator), Index(Index),
993 DocumentationFormat(DocumentationFormat) {}
994
995 void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
996 OverloadCandidate *Candidates,
997 unsigned NumCandidates,
998 SourceLocation OpenParLoc,
999 bool Braced) override {
1000 assert(!OpenParLoc.isInvalid());
1001 SourceManager &SrcMgr = S.getSourceManager();
1002 OpenParLoc = SrcMgr.getFileLoc(OpenParLoc);
1003 if (SrcMgr.isInMainFile(OpenParLoc))
1004 SigHelp.argListStart = sourceLocToPosition(SrcMgr, OpenParLoc);
1005 else
1006 elog("Location oustide main file in signature help: {0}",
1007 OpenParLoc.printToString(SrcMgr));
1008
1009 std::vector<ScoredSignature> ScoredSignatures;
1010 SigHelp.signatures.reserve(NumCandidates);
1011 ScoredSignatures.reserve(NumCandidates);
1012 // FIXME(rwols): How can we determine the "active overload candidate"?
1013 // Right now the overloaded candidates seem to be provided in a "best fit"
1014 // order, so I'm not too worried about this.
1015 SigHelp.activeSignature = 0;
1016 assert(CurrentArg <= (unsigned)std::numeric_limits<int>::max() &&
1017 "too many arguments");
1018
1019 SigHelp.activeParameter = static_cast<int>(CurrentArg);
1020
1021 for (unsigned I = 0; I < NumCandidates; ++I) {
1022 OverloadCandidate Candidate = Candidates[I];
1023 // We want to avoid showing instantiated signatures, because they may be
1024 // long in some cases (e.g. when 'T' is substituted with 'std::string', we
1025 // would get 'std::basic_string<char>').
1026 if (auto *Func = Candidate.getFunction()) {
1027 if (auto *Pattern = Func->getTemplateInstantiationPattern())
1028 Candidate = OverloadCandidate(Pattern);
1029 }
1030 if (static_cast<int>(I) == SigHelp.activeSignature) {
1031 // The activeParameter in LSP relates to the activeSignature. There is
1032 // another, per-signature field, but we currently do not use it and not
1033 // all clients might support it.
1034 // FIXME: Add support for per-signature activeParameter field.
1035 SigHelp.activeParameter =
1036 paramIndexForArg(Candidate, SigHelp.activeParameter);
1037 }
1038
1039 const auto *CCS = Candidate.CreateSignatureString(
1040 CurrentArg, S, *Allocator, CCTUInfo,
1041 /*IncludeBriefComments=*/true, Braced);
1042 assert(CCS && "Expected the CodeCompletionString to be non-null");
1043 ScoredSignatures.push_back(processOverloadCandidate(
1044 Candidate, *CCS,
1045 Candidate.getFunction()
1046 ? getDeclComment(S.getASTContext(), *Candidate.getFunction())
1047 : ""));
1048 }
1049
1050 // Sema does not load the docs from the preamble, so we need to fetch extra
1051 // docs from the index instead.
1052 llvm::DenseMap<SymbolID, std::string> FetchedDocs;
1053 if (Index) {
1054 LookupRequest IndexRequest;
1055 for (const auto &S : ScoredSignatures) {
1056 if (!S.IDForDoc)
1057 continue;
1058 IndexRequest.IDs.insert(S.IDForDoc);
1059 }
1060 Index->lookup(IndexRequest, [&](const Symbol &S) {
1061 if (!S.Documentation.empty())
1062 FetchedDocs[S.ID] = std::string(S.Documentation);
1063 });
1064 vlog("SigHelp: requested docs for {0} symbols from the index, got {1} "
1065 "symbols with non-empty docs in the response",
1066 IndexRequest.IDs.size(), FetchedDocs.size());
1067 }
1068
1069 llvm::sort(ScoredSignatures, [](const ScoredSignature &L,
1070 const ScoredSignature &R) {
1071 // Ordering follows:
1072 // - Less number of parameters is better.
1073 // - Aggregate > Function > FunctionType > FunctionTemplate
1074 // - High score is better.
1075 // - Shorter signature is better.
1076 // - Alphabetically smaller is better.
1077 if (L.Quality.NumberOfParameters != R.Quality.NumberOfParameters)
1078 return L.Quality.NumberOfParameters < R.Quality.NumberOfParameters;
1079 if (L.Quality.NumberOfOptionalParameters !=
1080 R.Quality.NumberOfOptionalParameters)
1081 return L.Quality.NumberOfOptionalParameters <
1082 R.Quality.NumberOfOptionalParameters;
1083 if (L.Quality.Kind != R.Quality.Kind) {
1084 using OC = CodeCompleteConsumer::OverloadCandidate;
1085 auto KindPriority = [&](OC::CandidateKind K) {
1086 switch (K) {
1087 case OC::CK_Aggregate:
1088 return 0;
1089 case OC::CK_Function:
1090 return 1;
1091 case OC::CK_FunctionType:
1092 return 2;
1093 case OC::CK_FunctionProtoTypeLoc:
1094 return 3;
1095 case OC::CK_FunctionTemplate:
1096 return 4;
1097 case OC::CK_Template:
1098 return 5;
1099 }
1100 llvm_unreachable("Unknown overload candidate type.");
1101 };
1102 return KindPriority(L.Quality.Kind) < KindPriority(R.Quality.Kind);
1103 }
1104 if (L.Signature.label.size() != R.Signature.label.size())
1105 return L.Signature.label.size() < R.Signature.label.size();
1106 return L.Signature.label < R.Signature.label;
1107 });
1108
1109 for (auto &SS : ScoredSignatures) {
1110 auto IndexDocIt =
1111 SS.IDForDoc ? FetchedDocs.find(SS.IDForDoc) : FetchedDocs.end();
1112 if (IndexDocIt != FetchedDocs.end()) {
1113 markup::Document SignatureComment;
1114 parseDocumentation(IndexDocIt->second, SignatureComment);
1115 SS.Signature.documentation =
1116 renderDoc(SignatureComment, DocumentationFormat);
1117 }
1118
1119 SigHelp.signatures.push_back(std::move(SS.Signature));
1120 }
1121 }
1122
1123 GlobalCodeCompletionAllocator &getAllocator() override { return *Allocator; }
1124
1125 CodeCompletionTUInfo &getCodeCompletionTUInfo() override { return CCTUInfo; }
1126
1127private:
1128 void processParameterChunk(llvm::StringRef ChunkText,
1129 SignatureInformation &Signature) const {
1130 // (!) this is O(n), should still be fast compared to building ASTs.
1131 unsigned ParamStartOffset = lspLength(Signature.label);
1132 unsigned ParamEndOffset = ParamStartOffset + lspLength(ChunkText);
1133 // A piece of text that describes the parameter that corresponds to
1134 // the code-completion location within a function call, message send,
1135 // macro invocation, etc.
1136 Signature.label += ChunkText;
1137 ParameterInformation Info;
1138 Info.labelOffsets.emplace(ParamStartOffset, ParamEndOffset);
1139 // FIXME: only set 'labelOffsets' when all clients migrate out of it.
1140 Info.labelString = std::string(ChunkText);
1141
1142 Signature.parameters.push_back(std::move(Info));
1143 }
1144
1145 void processOptionalChunk(const CodeCompletionString &CCS,
1146 SignatureInformation &Signature,
1147 SignatureQualitySignals &Signal) const {
1148 for (const auto &Chunk : CCS) {
1149 switch (Chunk.Kind) {
1150 case CodeCompletionString::CK_Optional:
1151 assert(Chunk.Optional &&
1152 "Expected the optional code completion string to be non-null.");
1153 processOptionalChunk(*Chunk.Optional, Signature, Signal);
1154 break;
1155 case CodeCompletionString::CK_VerticalSpace:
1156 break;
1157 case CodeCompletionString::CK_CurrentParameter:
1158 case CodeCompletionString::CK_Placeholder:
1159 processParameterChunk(Chunk.Text, Signature);
1160 Signal.NumberOfOptionalParameters++;
1161 break;
1162 default:
1163 Signature.label += Chunk.Text;
1164 break;
1165 }
1166 }
1167 }
1168
1169 // FIXME(ioeric): consider moving CodeCompletionString logic here to
1170 // CompletionString.h.
1171 ScoredSignature processOverloadCandidate(const OverloadCandidate &Candidate,
1172 const CodeCompletionString &CCS,
1173 llvm::StringRef DocComment) const {
1174 SignatureInformation Signature;
1175 SignatureQualitySignals Signal;
1176 const char *ReturnType = nullptr;
1177
1178 markup::Document OverloadComment;
1179 parseDocumentation(formatDocumentation(CCS, DocComment), OverloadComment);
1180 Signature.documentation = renderDoc(OverloadComment, DocumentationFormat);
1181 Signal.Kind = Candidate.getKind();
1182
1183 for (const auto &Chunk : CCS) {
1184 switch (Chunk.Kind) {
1185 case CodeCompletionString::CK_ResultType:
1186 // A piece of text that describes the type of an entity or,
1187 // for functions and methods, the return type.
1188 assert(!ReturnType && "Unexpected CK_ResultType");
1189 ReturnType = Chunk.Text;
1190 break;
1191 case CodeCompletionString::CK_CurrentParameter:
1192 case CodeCompletionString::CK_Placeholder:
1193 processParameterChunk(Chunk.Text, Signature);
1194 Signal.NumberOfParameters++;
1195 break;
1196 case CodeCompletionString::CK_Optional: {
1197 // The rest of the parameters are defaulted/optional.
1198 assert(Chunk.Optional &&
1199 "Expected the optional code completion string to be non-null.");
1200 processOptionalChunk(*Chunk.Optional, Signature, Signal);
1201 break;
1202 }
1203 case CodeCompletionString::CK_VerticalSpace:
1204 break;
1205 default:
1206 Signature.label += Chunk.Text;
1207 break;
1208 }
1209 }
1210 if (ReturnType) {
1211 Signature.label += " -> ";
1212 Signature.label += ReturnType;
1213 }
1214 dlog("Signal for {0}: {1}", Signature, Signal);
1215 ScoredSignature Result;
1216 Result.Signature = std::move(Signature);
1217 Result.Quality = Signal;
1218 const FunctionDecl *Func = Candidate.getFunction();
1219 if (Func && Result.Signature.documentation.value.empty()) {
1220 // Computing USR caches linkage, which may change after code completion.
1221 if (!hasUnstableLinkage(Func))
1222 Result.IDForDoc = clangd::getSymbolID(Func);
1223 }
1224 return Result;
1225 }
1226
1227 SignatureHelp &SigHelp;
1228 std::shared_ptr<clang::GlobalCodeCompletionAllocator> Allocator;
1229 CodeCompletionTUInfo CCTUInfo;
1230 const SymbolIndex *Index;
1231 MarkupKind DocumentationFormat;
1232}; // SignatureHelpCollector
1233
1234// Used only for completion of C-style comments in function call (i.e.
1235// /*foo=*/7). Similar to SignatureHelpCollector, but needs to do less work.
1236class ParamNameCollector final : public CodeCompleteConsumer {
1237public:
1238 ParamNameCollector(const clang::CodeCompleteOptions &CodeCompleteOpts,
1239 std::set<std::string> &ParamNames)
1240 : CodeCompleteConsumer(CodeCompleteOpts),
1241 Allocator(std::make_shared<clang::GlobalCodeCompletionAllocator>()),
1242 CCTUInfo(Allocator), ParamNames(ParamNames) {}
1243
1244 void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
1245 OverloadCandidate *Candidates,
1246 unsigned NumCandidates,
1247 SourceLocation OpenParLoc,
1248 bool Braced) override {
1249 assert(CurrentArg <= (unsigned)std::numeric_limits<int>::max() &&
1250 "too many arguments");
1251
1252 for (unsigned I = 0; I < NumCandidates; ++I) {
1253 if (const NamedDecl *ND = Candidates[I].getParamDecl(CurrentArg))
1254 if (const auto *II = ND->getIdentifier())
1255 ParamNames.emplace(II->getName());
1256 }
1257 }
1258
1259private:
1260 GlobalCodeCompletionAllocator &getAllocator() override { return *Allocator; }
1261
1262 CodeCompletionTUInfo &getCodeCompletionTUInfo() override { return CCTUInfo; }
1263
1264 std::shared_ptr<clang::GlobalCodeCompletionAllocator> Allocator;
1265 CodeCompletionTUInfo CCTUInfo;
1266 std::set<std::string> &ParamNames;
1267};
1268
1269struct SemaCompleteInput {
1271 size_t Offset;
1272 const PreambleData &Preamble;
1273 const std::optional<PreamblePatch> Patch;
1274 const ParseInputs &ParseInput;
1275};
1276
1277void loadMainFilePreambleMacros(const Preprocessor &PP,
1278 const PreambleData &Preamble) {
1279 // The ExternalPreprocessorSource has our macros, if we know where to look.
1280 // We can read all the macros using PreambleMacros->ReadDefinedMacros(),
1281 // but this includes transitively included files, so may deserialize a lot.
1282 ExternalPreprocessorSource *PreambleMacros = PP.getExternalSource();
1283 // As we have the names of the macros, we can look up their IdentifierInfo
1284 // and then use this to load just the macros we want.
1285 const auto &ITable = PP.getIdentifierTable();
1286 IdentifierInfoLookup *PreambleIdentifiers =
1287 ITable.getExternalIdentifierLookup();
1288
1289 if (!PreambleIdentifiers || !PreambleMacros)
1290 return;
1291 for (const auto &MacroName : Preamble.Macros.Names) {
1292 if (ITable.find(MacroName.getKey()) != ITable.end())
1293 continue;
1294 if (auto *II = PreambleIdentifiers->get(MacroName.getKey()))
1295 if (II->isOutOfDate())
1296 PreambleMacros->updateOutOfDateIdentifier(*II);
1297 }
1298}
1299
1300// Invokes Sema code completion on a file.
1301// If \p Includes is set, it will be updated based on the compiler invocation.
1302bool semaCodeComplete(std::unique_ptr<CodeCompleteConsumer> Consumer,
1303 const clang::CodeCompleteOptions &Options,
1304 const SemaCompleteInput &Input,
1305 IncludeStructure *Includes = nullptr) {
1306 trace::Span Tracer("Sema completion");
1307
1308 IgnoreDiagnostics IgnoreDiags;
1309 auto CI = buildCompilerInvocation(Input.ParseInput, IgnoreDiags);
1310 if (!CI) {
1311 elog("Couldn't create CompilerInvocation");
1312 return false;
1313 }
1314 auto &FrontendOpts = CI->getFrontendOpts();
1315 FrontendOpts.SkipFunctionBodies = true;
1316 // Disable typo correction in Sema.
1317 CI->getLangOpts()->SpellChecking = false;
1318 // Code completion won't trigger in delayed template bodies.
1319 // This is on-by-default in windows to allow parsing SDK headers; we're only
1320 // disabling it for the main-file (not preamble).
1321 CI->getLangOpts()->DelayedTemplateParsing = false;
1322 // Setup code completion.
1323 FrontendOpts.CodeCompleteOpts = Options;
1324 FrontendOpts.CodeCompletionAt.FileName = std::string(Input.FileName);
1325 std::tie(FrontendOpts.CodeCompletionAt.Line,
1326 FrontendOpts.CodeCompletionAt.Column) =
1327 offsetToClangLineColumn(Input.ParseInput.Contents, Input.Offset);
1328
1329 std::unique_ptr<llvm::MemoryBuffer> ContentsBuffer =
1330 llvm::MemoryBuffer::getMemBuffer(Input.ParseInput.Contents,
1331 Input.FileName);
1332 // The diagnostic options must be set before creating a CompilerInstance.
1333 CI->getDiagnosticOpts().IgnoreWarnings = true;
1334 // We reuse the preamble whether it's valid or not. This is a
1335 // correctness/performance tradeoff: building without a preamble is slow, and
1336 // completion is latency-sensitive.
1337 // However, if we're completing *inside* the preamble section of the draft,
1338 // overriding the preamble will break sema completion. Fortunately we can just
1339 // skip all includes in this case; these completions are really simple.
1340 PreambleBounds PreambleRegion =
1341 ComputePreambleBounds(*CI->getLangOpts(), *ContentsBuffer, 0);
1342 bool CompletingInPreamble = Input.Offset < PreambleRegion.Size ||
1343 (!PreambleRegion.PreambleEndsAtStartOfLine &&
1344 Input.Offset == PreambleRegion.Size);
1345 if (Input.Patch)
1346 Input.Patch->apply(*CI);
1347 // NOTE: we must call BeginSourceFile after prepareCompilerInstance. Otherwise
1348 // the remapped buffers do not get freed.
1349 llvm::IntrusiveRefCntPtr<llvm::vfs::FileSystem> VFS =
1350 Input.ParseInput.TFS->view(Input.ParseInput.CompileCommand.Directory);
1351 if (Input.Preamble.StatCache)
1352 VFS = Input.Preamble.StatCache->getConsumingFS(std::move(VFS));
1354 std::move(CI), !CompletingInPreamble ? &Input.Preamble.Preamble : nullptr,
1355 std::move(ContentsBuffer), std::move(VFS), IgnoreDiags);
1356 Clang->getPreprocessorOpts().SingleFileParseMode = CompletingInPreamble;
1357 Clang->setCodeCompletionConsumer(Consumer.release());
1358
1360 if (!Action.BeginSourceFile(*Clang, Clang->getFrontendOpts().Inputs[0])) {
1361 log("BeginSourceFile() failed when running codeComplete for {0}",
1362 Input.FileName);
1363 return false;
1364 }
1365 // Macros can be defined within the preamble region of the main file.
1366 // They don't fall nicely into our index/Sema dichotomy:
1367 // - they're not indexed for completion (they're not available across files)
1368 // - but Sema code complete won't see them: as part of the preamble, they're
1369 // deserialized only when mentioned.
1370 // Force them to be deserialized so SemaCodeComplete sees them.
1371 loadMainFilePreambleMacros(Clang->getPreprocessor(), Input.Preamble);
1372 if (Includes)
1373 Includes->collect(*Clang);
1374 if (llvm::Error Err = Action.Execute()) {
1375 log("Execute() failed when running codeComplete for {0}: {1}",
1376 Input.FileName, toString(std::move(Err)));
1377 return false;
1378 }
1379 Action.EndSourceFile();
1380
1381 return true;
1382}
1383
1384// Should we allow index completions in the specified context?
1385bool allowIndex(CodeCompletionContext &CC) {
1386 if (!contextAllowsIndex(CC.getKind()))
1387 return false;
1388 // We also avoid ClassName::bar (but allow namespace::bar).
1389 auto Scope = CC.getCXXScopeSpecifier();
1390 if (!Scope)
1391 return true;
1392 NestedNameSpecifier *NameSpec = (*Scope)->getScopeRep();
1393 if (!NameSpec)
1394 return true;
1395 // We only query the index when qualifier is a namespace.
1396 // If it's a class, we rely solely on sema completions.
1397 switch (NameSpec->getKind()) {
1398 case NestedNameSpecifier::Global:
1399 case NestedNameSpecifier::Namespace:
1400 case NestedNameSpecifier::NamespaceAlias:
1401 return true;
1402 case NestedNameSpecifier::Super:
1403 case NestedNameSpecifier::TypeSpec:
1404 case NestedNameSpecifier::TypeSpecWithTemplate:
1405 // Unresolved inside a template.
1406 case NestedNameSpecifier::Identifier:
1407 return false;
1408 }
1409 llvm_unreachable("invalid NestedNameSpecifier kind");
1410}
1411
1412// Should we include a symbol from the index given the completion kind?
1413// FIXME: Ideally we can filter in the fuzzy find request itself.
1414bool includeSymbolFromIndex(CodeCompletionContext::Kind Kind,
1415 const Symbol &Sym) {
1416 // Objective-C protocols are only useful in ObjC protocol completions,
1417 // in other places they're confusing, especially when they share the same
1418 // identifier with a class.
1419 if (Sym.SymInfo.Kind == index::SymbolKind::Protocol &&
1420 Sym.SymInfo.Lang == index::SymbolLanguage::ObjC)
1421 return Kind == CodeCompletionContext::CCC_ObjCProtocolName;
1422 else if (Kind == CodeCompletionContext::CCC_ObjCProtocolName)
1423 // Don't show anything else in ObjC protocol completions.
1424 return false;
1425 return true;
1426}
1427
1428std::future<std::pair<bool, SymbolSlab>>
1429startAsyncFuzzyFind(const SymbolIndex &Index, const FuzzyFindRequest &Req) {
1430 return runAsync<std::pair<bool, SymbolSlab>>([&Index, Req]() {
1431 trace::Span Tracer("Async fuzzyFind");
1432 SymbolSlab::Builder Syms;
1433 bool Incomplete =
1434 Index.fuzzyFind(Req, [&Syms](const Symbol &Sym) { Syms.insert(Sym); });
1435 return std::make_pair(Incomplete, std::move(Syms).build());
1436 });
1437}
1438
1439// Creates a `FuzzyFindRequest` based on the cached index request from the
1440// last completion, if any, and the speculated completion filter text in the
1441// source code.
1442FuzzyFindRequest speculativeFuzzyFindRequestForCompletion(
1443 FuzzyFindRequest CachedReq, const CompletionPrefix &HeuristicPrefix) {
1444 CachedReq.Query = std::string(HeuristicPrefix.Name);
1445 return CachedReq;
1446}
1447
1448// Runs Sema-based (AST) and Index-based completion, returns merged results.
1449//
1450// There are a few tricky considerations:
1451// - the AST provides information needed for the index query (e.g. which
1452// namespaces to search in). So Sema must start first.
1453// - we only want to return the top results (Opts.Limit).
1454// Building CompletionItems for everything else is wasteful, so we want to
1455// preserve the "native" format until we're done with scoring.
1456// - the data underlying Sema completion items is owned by the AST and various
1457// other arenas, which must stay alive for us to build CompletionItems.
1458// - we may get duplicate results from Sema and the Index, we need to merge.
1459//
1460// So we start Sema completion first, and do all our work in its callback.
1461// We use the Sema context information to query the index.
1462// Then we merge the two result sets, producing items that are Sema/Index/Both.
1463// These items are scored, and the top N are synthesized into the LSP response.
1464// Finally, we can clean up the data structures created by Sema completion.
1465//
1466// Main collaborators are:
1467// - semaCodeComplete sets up the compiler machinery to run code completion.
1468// - CompletionRecorder captures Sema completion results, including context.
1469// - SymbolIndex (Opts.Index) provides index completion results as Symbols
1470// - CompletionCandidates are the result of merging Sema and Index results.
1471// Each candidate points to an underlying CodeCompletionResult (Sema), a
1472// Symbol (Index), or both. It computes the result quality score.
1473// CompletionCandidate also does conversion to CompletionItem (at the end).
1474// - FuzzyMatcher scores how the candidate matches the partial identifier.
1475// This score is combined with the result quality score for the final score.
1476// - TopN determines the results with the best score.
1477class CodeCompleteFlow {
1479 IncludeStructure Includes; // Complete once the compiler runs.
1480 SpeculativeFuzzyFind *SpecFuzzyFind; // Can be nullptr.
1481 const CodeCompleteOptions &Opts;
1482
1483 // Sema takes ownership of Recorder. Recorder is valid until Sema cleanup.
1484 CompletionRecorder *Recorder = nullptr;
1485 CodeCompletionContext::Kind CCContextKind = CodeCompletionContext::CCC_Other;
1486 bool IsUsingDeclaration = false;
1487 // The snippets will not be generated if the token following completion
1488 // location is an opening parenthesis (tok::l_paren) because this would add
1489 // extra parenthesis.
1490 tok::TokenKind NextTokenKind = tok::eof;
1491 // Counters for logging.
1492 int NSema = 0, NIndex = 0, NSemaAndIndex = 0, NIdent = 0;
1493 bool Incomplete = false; // Would more be available with a higher limit?
1494 CompletionPrefix HeuristicPrefix;
1495 std::optional<FuzzyMatcher> Filter; // Initialized once Sema runs.
1496 Range ReplacedRange;
1497 std::vector<std::string> QueryScopes; // Initialized once Sema runs.
1498 std::vector<std::string> AccessibleScopes; // Initialized once Sema runs.
1499 // Initialized once QueryScopes is initialized, if there are scopes.
1500 std::optional<ScopeDistance> ScopeProximity;
1501 std::optional<OpaqueType> PreferredType; // Initialized once Sema runs.
1502 // Whether to query symbols from any scope. Initialized once Sema runs.
1503 bool AllScopes = false;
1504 llvm::StringSet<> ContextWords;
1505 // Include-insertion and proximity scoring rely on the include structure.
1506 // This is available after Sema has run.
1507 std::optional<IncludeInserter> Inserter; // Available during runWithSema.
1508 std::optional<URIDistance> FileProximity; // Initialized once Sema runs.
1509 /// Speculative request based on the cached request and the filter text before
1510 /// the cursor.
1511 /// Initialized right before sema run. This is only set if `SpecFuzzyFind` is
1512 /// set and contains a cached request.
1513 std::optional<FuzzyFindRequest> SpecReq;
1514
1515public:
1516 // A CodeCompleteFlow object is only useful for calling run() exactly once.
1517 CodeCompleteFlow(PathRef FileName, const IncludeStructure &Includes,
1518 SpeculativeFuzzyFind *SpecFuzzyFind,
1519 const CodeCompleteOptions &Opts)
1520 : FileName(FileName), Includes(Includes), SpecFuzzyFind(SpecFuzzyFind),
1521 Opts(Opts) {}
1522
1523 CodeCompleteResult run(const SemaCompleteInput &SemaCCInput) && {
1524 trace::Span Tracer("CodeCompleteFlow");
1525 HeuristicPrefix = guessCompletionPrefix(SemaCCInput.ParseInput.Contents,
1526 SemaCCInput.Offset);
1527 populateContextWords(SemaCCInput.ParseInput.Contents);
1528 if (Opts.Index && SpecFuzzyFind && SpecFuzzyFind->CachedReq) {
1529 assert(!SpecFuzzyFind->Result.valid());
1530 SpecReq = speculativeFuzzyFindRequestForCompletion(
1531 *SpecFuzzyFind->CachedReq, HeuristicPrefix);
1532 SpecFuzzyFind->Result = startAsyncFuzzyFind(*Opts.Index, *SpecReq);
1533 }
1534
1535 // We run Sema code completion first. It builds an AST and calculates:
1536 // - completion results based on the AST.
1537 // - partial identifier and context. We need these for the index query.
1538 CodeCompleteResult Output;
1539 auto RecorderOwner = std::make_unique<CompletionRecorder>(Opts, [&]() {
1540 assert(Recorder && "Recorder is not set");
1541 CCContextKind = Recorder->CCContext.getKind();
1542 IsUsingDeclaration = Recorder->CCContext.isUsingDeclaration();
1543 auto Style = getFormatStyleForFile(SemaCCInput.FileName,
1544 SemaCCInput.ParseInput.Contents,
1545 *SemaCCInput.ParseInput.TFS);
1546 const auto NextToken = Lexer::findNextToken(
1547 Recorder->CCSema->getPreprocessor().getCodeCompletionLoc(),
1548 Recorder->CCSema->getSourceManager(), Recorder->CCSema->LangOpts);
1549 if (NextToken)
1550 NextTokenKind = NextToken->getKind();
1551 // If preprocessor was run, inclusions from preprocessor callback should
1552 // already be added to Includes.
1553 Inserter.emplace(
1554 SemaCCInput.FileName, SemaCCInput.ParseInput.Contents, Style,
1555 SemaCCInput.ParseInput.CompileCommand.Directory,
1556 &Recorder->CCSema->getPreprocessor().getHeaderSearchInfo());
1557 for (const auto &Inc : Includes.MainFileIncludes)
1558 Inserter->addExisting(Inc);
1559
1560 // Most of the cost of file proximity is in initializing the FileDistance
1561 // structures based on the observed includes, once per query. Conceptually
1562 // that happens here (though the per-URI-scheme initialization is lazy).
1563 // The per-result proximity scoring is (amortized) very cheap.
1564 FileDistanceOptions ProxOpts{}; // Use defaults.
1565 const auto &SM = Recorder->CCSema->getSourceManager();
1566 llvm::StringMap<SourceParams> ProxSources;
1567 auto MainFileID =
1568 Includes.getID(SM.getFileEntryForID(SM.getMainFileID()));
1569 assert(MainFileID);
1570 for (auto &HeaderIDAndDepth : Includes.includeDepth(*MainFileID)) {
1571 auto &Source =
1572 ProxSources[Includes.getRealPath(HeaderIDAndDepth.getFirst())];
1573 Source.Cost = HeaderIDAndDepth.getSecond() * ProxOpts.IncludeCost;
1574 // Symbols near our transitive includes are good, but only consider
1575 // things in the same directory or below it. Otherwise there can be
1576 // many false positives.
1577 if (HeaderIDAndDepth.getSecond() > 0)
1578 Source.MaxUpTraversals = 1;
1579 }
1580 FileProximity.emplace(ProxSources, ProxOpts);
1581
1582 Output = runWithSema();
1583 Inserter.reset(); // Make sure this doesn't out-live Clang.
1584 SPAN_ATTACH(Tracer, "sema_completion_kind",
1585 getCompletionKindString(CCContextKind));
1586 log("Code complete: sema context {0}, query scopes [{1}] (AnyScope={2}), "
1587 "expected type {3}{4}",
1588 getCompletionKindString(CCContextKind),
1589 llvm::join(QueryScopes.begin(), QueryScopes.end(), ","), AllScopes,
1590 PreferredType ? Recorder->CCContext.getPreferredType().getAsString()
1591 : "<none>",
1592 IsUsingDeclaration ? ", inside using declaration" : "");
1593 });
1594
1595 Recorder = RecorderOwner.get();
1596
1597 semaCodeComplete(std::move(RecorderOwner), Opts.getClangCompleteOpts(),
1598 SemaCCInput, &Includes);
1599 logResults(Output, Tracer);
1600 return Output;
1601 }
1602
1603 void logResults(const CodeCompleteResult &Output, const trace::Span &Tracer) {
1604 SPAN_ATTACH(Tracer, "sema_results", NSema);
1605 SPAN_ATTACH(Tracer, "index_results", NIndex);
1606 SPAN_ATTACH(Tracer, "merged_results", NSemaAndIndex);
1607 SPAN_ATTACH(Tracer, "identifier_results", NIdent);
1608 SPAN_ATTACH(Tracer, "returned_results", int64_t(Output.Completions.size()));
1609 SPAN_ATTACH(Tracer, "incomplete", Output.HasMore);
1610 log("Code complete: {0} results from Sema, {1} from Index, "
1611 "{2} matched, {3} from identifiers, {4} returned{5}.",
1612 NSema, NIndex, NSemaAndIndex, NIdent, Output.Completions.size(),
1613 Output.HasMore ? " (incomplete)" : "");
1614 assert(!Opts.Limit || Output.Completions.size() <= Opts.Limit);
1615 // We don't assert that isIncomplete means we hit a limit.
1616 // Indexes may choose to impose their own limits even if we don't have one.
1617 }
1618
1619 CodeCompleteResult runWithoutSema(llvm::StringRef Content, size_t Offset,
1620 const ThreadsafeFS &TFS) && {
1621 trace::Span Tracer("CodeCompleteWithoutSema");
1622 // Fill in fields normally set by runWithSema()
1623 HeuristicPrefix = guessCompletionPrefix(Content, Offset);
1624 populateContextWords(Content);
1625 CCContextKind = CodeCompletionContext::CCC_Recovery;
1626 IsUsingDeclaration = false;
1627 Filter = FuzzyMatcher(HeuristicPrefix.Name);
1628 auto Pos = offsetToPosition(Content, Offset);
1629 ReplacedRange.start = ReplacedRange.end = Pos;
1630 ReplacedRange.start.character -= HeuristicPrefix.Name.size();
1631
1632 llvm::StringMap<SourceParams> ProxSources;
1633 ProxSources[FileName].Cost = 0;
1634 FileProximity.emplace(ProxSources);
1635
1636 auto Style = getFormatStyleForFile(FileName, Content, TFS);
1637 // This will only insert verbatim headers.
1638 Inserter.emplace(FileName, Content, Style,
1639 /*BuildDir=*/"", /*HeaderSearchInfo=*/nullptr);
1640
1641 auto Identifiers = collectIdentifiers(Content, Style);
1642 std::vector<RawIdentifier> IdentifierResults;
1643 for (const auto &IDAndCount : Identifiers) {
1644 RawIdentifier ID;
1645 ID.Name = IDAndCount.first();
1646 ID.References = IDAndCount.second;
1647 // Avoid treating typed filter as an identifier.
1648 if (ID.Name == HeuristicPrefix.Name)
1649 --ID.References;
1650 if (ID.References > 0)
1651 IdentifierResults.push_back(std::move(ID));
1652 }
1653
1654 // Simplified version of getQueryScopes():
1655 // - accessible scopes are determined heuristically.
1656 // - all-scopes query if no qualifier was typed (and it's allowed).
1657 SpecifiedScope Scopes;
1658 Scopes.QueryScopes = visibleNamespaces(
1659 Content.take_front(Offset), format::getFormattingLangOpts(Style));
1660 for (std::string &S : Scopes.QueryScopes)
1661 if (!S.empty())
1662 S.append("::"); // visibleNamespaces doesn't include trailing ::.
1663 if (HeuristicPrefix.Qualifier.empty())
1664 AllScopes = Opts.AllScopes;
1665 else if (HeuristicPrefix.Qualifier.startswith("::")) {
1666 Scopes.QueryScopes = {""};
1667 Scopes.UnresolvedQualifier =
1668 std::string(HeuristicPrefix.Qualifier.drop_front(2));
1669 } else
1670 Scopes.UnresolvedQualifier = std::string(HeuristicPrefix.Qualifier);
1671 // First scope is the (modified) enclosing scope.
1672 QueryScopes = Scopes.scopesForIndexQuery();
1674 ScopeProximity.emplace(QueryScopes);
1675
1676 SymbolSlab IndexResults = Opts.Index ? queryIndex() : SymbolSlab();
1677
1678 CodeCompleteResult Output = toCodeCompleteResult(mergeResults(
1679 /*SemaResults=*/{}, IndexResults, IdentifierResults));
1680 Output.RanParser = false;
1681 logResults(Output, Tracer);
1682 return Output;
1683 }
1684
1685private:
1686 void populateContextWords(llvm::StringRef Content) {
1687 // Take last 3 lines before the completion point.
1688 unsigned RangeEnd = HeuristicPrefix.Qualifier.begin() - Content.data(),
1689 RangeBegin = RangeEnd;
1690 for (size_t I = 0; I < 3 && RangeBegin > 0; ++I) {
1691 auto PrevNL = Content.rfind('\n', RangeBegin);
1692 if (PrevNL == StringRef::npos) {
1693 RangeBegin = 0;
1694 break;
1695 }
1696 RangeBegin = PrevNL;
1697 }
1698
1699 ContextWords = collectWords(Content.slice(RangeBegin, RangeEnd));
1700 dlog("Completion context words: {0}",
1701 llvm::join(ContextWords.keys(), ", "));
1702 }
1703
1704 // This is called by run() once Sema code completion is done, but before the
1705 // Sema data structures are torn down. It does all the real work.
1706 CodeCompleteResult runWithSema() {
1707 const auto &CodeCompletionRange = CharSourceRange::getCharRange(
1708 Recorder->CCSema->getPreprocessor().getCodeCompletionTokenRange());
1709 // When we are getting completions with an empty identifier, for example
1710 // std::vector<int> asdf;
1711 // asdf.^;
1712 // Then the range will be invalid and we will be doing insertion, use
1713 // current cursor position in such cases as range.
1714 if (CodeCompletionRange.isValid()) {
1715 ReplacedRange = halfOpenToRange(Recorder->CCSema->getSourceManager(),
1716 CodeCompletionRange);
1717 } else {
1718 const auto &Pos = sourceLocToPosition(
1719 Recorder->CCSema->getSourceManager(),
1720 Recorder->CCSema->getPreprocessor().getCodeCompletionLoc());
1721 ReplacedRange.start = ReplacedRange.end = Pos;
1722 }
1723 Filter = FuzzyMatcher(
1724 Recorder->CCSema->getPreprocessor().getCodeCompletionFilter());
1725 auto SpecifiedScopes = getQueryScopes(
1726 Recorder->CCContext, *Recorder->CCSema, HeuristicPrefix, Opts);
1727
1728 QueryScopes = SpecifiedScopes.scopesForIndexQuery();
1729 AccessibleScopes = SpecifiedScopes.scopesForQualification();
1730 AllScopes = SpecifiedScopes.AllowAllScopes;
1731 if (!QueryScopes.empty())
1732 ScopeProximity.emplace(QueryScopes);
1733 PreferredType =
1734 OpaqueType::fromType(Recorder->CCSema->getASTContext(),
1735 Recorder->CCContext.getPreferredType());
1736 // Sema provides the needed context to query the index.
1737 // FIXME: in addition to querying for extra/overlapping symbols, we should
1738 // explicitly request symbols corresponding to Sema results.
1739 // We can use their signals even if the index can't suggest them.
1740 // We must copy index results to preserve them, but there are at most Limit.
1741 auto IndexResults = (Opts.Index && allowIndex(Recorder->CCContext))
1742 ? queryIndex()
1743 : SymbolSlab();
1744 trace::Span Tracer("Populate CodeCompleteResult");
1745 // Merge Sema and Index results, score them, and pick the winners.
1746 auto Top =
1747 mergeResults(Recorder->Results, IndexResults, /*Identifiers*/ {});
1748 return toCodeCompleteResult(Top);
1749 }
1750
1751 CodeCompleteResult
1752 toCodeCompleteResult(const std::vector<ScoredBundle> &Scored) {
1753 CodeCompleteResult Output;
1754
1755 // Convert the results to final form, assembling the expensive strings.
1756 for (auto &C : Scored) {
1757 Output.Completions.push_back(toCodeCompletion(C.first));
1758 Output.Completions.back().Score = C.second;
1759 Output.Completions.back().CompletionTokenRange = ReplacedRange;
1760 }
1761 Output.HasMore = Incomplete;
1762 Output.Context = CCContextKind;
1763 Output.CompletionRange = ReplacedRange;
1764 return Output;
1765 }
1766
1767 SymbolSlab queryIndex() {
1768 trace::Span Tracer("Query index");
1769 SPAN_ATTACH(Tracer, "limit", int64_t(Opts.Limit));
1770
1771 // Build the query.
1772 FuzzyFindRequest Req;
1773 if (Opts.Limit)
1774 Req.Limit = Opts.Limit;
1775 Req.Query = std::string(Filter->pattern());
1776 Req.RestrictForCodeCompletion = true;
1777 Req.Scopes = QueryScopes;
1778 Req.AnyScope = AllScopes;
1779 // FIXME: we should send multiple weighted paths here.
1780 Req.ProximityPaths.push_back(std::string(FileName));
1781 if (PreferredType)
1782 Req.PreferredTypes.push_back(std::string(PreferredType->raw()));
1783 vlog("Code complete: fuzzyFind({0:2})", toJSON(Req));
1784
1785 if (SpecFuzzyFind)
1786 SpecFuzzyFind->NewReq = Req;
1787 if (SpecFuzzyFind && SpecFuzzyFind->Result.valid() && (*SpecReq == Req)) {
1788 vlog("Code complete: speculative fuzzy request matches the actual index "
1789 "request. Waiting for the speculative index results.");
1790 SPAN_ATTACH(Tracer, "Speculative results", true);
1791
1792 trace::Span WaitSpec("Wait speculative results");
1793 auto SpecRes = SpecFuzzyFind->Result.get();
1794 Incomplete |= SpecRes.first;
1795 return std::move(SpecRes.second);
1796 }
1797
1798 SPAN_ATTACH(Tracer, "Speculative results", false);
1799
1800 // Run the query against the index.
1801 SymbolSlab::Builder ResultsBuilder;
1802 Incomplete |= Opts.Index->fuzzyFind(
1803 Req, [&](const Symbol &Sym) { ResultsBuilder.insert(Sym); });
1804 return std::move(ResultsBuilder).build();
1805 }
1806
1807 // Merges Sema and Index results where possible, to form CompletionCandidates.
1808 // \p Identifiers is raw identifiers that can also be completion candidates.
1809 // Identifiers are not merged with results from index or sema.
1810 // Groups overloads if desired, to form CompletionCandidate::Bundles. The
1811 // bundles are scored and top results are returned, best to worst.
1812 std::vector<ScoredBundle>
1813 mergeResults(const std::vector<CodeCompletionResult> &SemaResults,
1814 const SymbolSlab &IndexResults,
1815 const std::vector<RawIdentifier> &IdentifierResults) {
1816 trace::Span Tracer("Merge and score results");
1817 std::vector<CompletionCandidate::Bundle> Bundles;
1818 llvm::DenseMap<size_t, size_t> BundleLookup;
1819 auto AddToBundles = [&](const CodeCompletionResult *SemaResult,
1820 const Symbol *IndexResult,
1821 const RawIdentifier *IdentifierResult) {
1822 CompletionCandidate C;
1823 C.SemaResult = SemaResult;
1824 C.IndexResult = IndexResult;
1825 C.IdentifierResult = IdentifierResult;
1826 if (C.IndexResult) {
1827 C.Name = IndexResult->Name;
1828 C.RankedIncludeHeaders = getRankedIncludes(*C.IndexResult);
1829 } else if (C.SemaResult) {
1830 C.Name = Recorder->getName(*SemaResult);
1831 } else {
1832 assert(IdentifierResult);
1833 C.Name = IdentifierResult->Name;
1834 }
1835 if (auto OverloadSet =
1836 C.overloadSet(Opts, FileName, Inserter ? &*Inserter : nullptr)) {
1837 auto Ret = BundleLookup.try_emplace(OverloadSet, Bundles.size());
1838 if (Ret.second)
1839 Bundles.emplace_back();
1840 Bundles[Ret.first->second].push_back(std::move(C));
1841 } else {
1842 Bundles.emplace_back();
1843 Bundles.back().push_back(std::move(C));
1844 }
1845 };
1846 llvm::DenseSet<const Symbol *> UsedIndexResults;
1847 auto CorrespondingIndexResult =
1848 [&](const CodeCompletionResult &SemaResult) -> const Symbol * {
1849 if (auto SymID =
1850 getSymbolID(SemaResult, Recorder->CCSema->getSourceManager())) {
1851 auto I = IndexResults.find(SymID);
1852 if (I != IndexResults.end()) {
1853 UsedIndexResults.insert(&*I);
1854 return &*I;
1855 }
1856 }
1857 return nullptr;
1858 };
1859 // Emit all Sema results, merging them with Index results if possible.
1860 for (auto &SemaResult : SemaResults)
1861 AddToBundles(&SemaResult, CorrespondingIndexResult(SemaResult), nullptr);
1862 // Now emit any Index-only results.
1863 for (const auto &IndexResult : IndexResults) {
1864 if (UsedIndexResults.count(&IndexResult))
1865 continue;
1866 if (!includeSymbolFromIndex(CCContextKind, IndexResult))
1867 continue;
1868 AddToBundles(/*SemaResult=*/nullptr, &IndexResult, nullptr);
1869 }
1870 // Emit identifier results.
1871 for (const auto &Ident : IdentifierResults)
1872 AddToBundles(/*SemaResult=*/nullptr, /*IndexResult=*/nullptr, &Ident);
1873 // We only keep the best N results at any time, in "native" format.
1874 TopN<ScoredBundle, ScoredBundleGreater> Top(
1875 Opts.Limit == 0 ? std::numeric_limits<size_t>::max() : Opts.Limit);
1876 for (auto &Bundle : Bundles)
1877 addCandidate(Top, std::move(Bundle));
1878 return std::move(Top).items();
1879 }
1880
1881 std::optional<float> fuzzyScore(const CompletionCandidate &C) {
1882 // Macros can be very spammy, so we only support prefix completion.
1883 if (((C.SemaResult &&
1884 C.SemaResult->Kind == CodeCompletionResult::RK_Macro) ||
1885 (C.IndexResult &&
1886 C.IndexResult->SymInfo.Kind == index::SymbolKind::Macro)) &&
1887 !C.Name.starts_with_insensitive(Filter->pattern()))
1888 return std::nullopt;
1889 return Filter->match(C.Name);
1890 }
1891
1892 CodeCompletion::Scores
1893 evaluateCompletion(const SymbolQualitySignals &Quality,
1894 const SymbolRelevanceSignals &Relevance) {
1896 CodeCompletion::Scores Scores;
1897 switch (Opts.RankingModel) {
1898 case RM::Heuristics:
1899 Scores.Quality = Quality.evaluateHeuristics();
1900 Scores.Relevance = Relevance.evaluateHeuristics();
1901 Scores.Total =
1902 evaluateSymbolAndRelevance(Scores.Quality, Scores.Relevance);
1903 // NameMatch is in fact a multiplier on total score, so rescoring is
1904 // sound.
1905 Scores.ExcludingName =
1906 Relevance.NameMatch > std::numeric_limits<float>::epsilon()
1907 ? Scores.Total / Relevance.NameMatch
1908 : Scores.Quality;
1909 return Scores;
1910
1911 case RM::DecisionForest:
1912 DecisionForestScores DFScores = Opts.DecisionForestScorer(
1913 Quality, Relevance, Opts.DecisionForestBase);
1914 Scores.ExcludingName = DFScores.ExcludingName;
1915 Scores.Total = DFScores.Total;
1916 return Scores;
1917 }
1918 llvm_unreachable("Unhandled CodeCompletion ranking model.");
1919 }
1920
1921 // Scores a candidate and adds it to the TopN structure.
1922 void addCandidate(TopN<ScoredBundle, ScoredBundleGreater> &Candidates,
1923 CompletionCandidate::Bundle Bundle) {
1924 SymbolQualitySignals Quality;
1925 SymbolRelevanceSignals Relevance;
1926 Relevance.Context = CCContextKind;
1927 Relevance.Name = Bundle.front().Name;
1928 Relevance.FilterLength = HeuristicPrefix.Name.size();
1929 Relevance.Query = SymbolRelevanceSignals::CodeComplete;
1930 Relevance.FileProximityMatch = &*FileProximity;
1931 if (ScopeProximity)
1932 Relevance.ScopeProximityMatch = &*ScopeProximity;
1933 if (PreferredType)
1934 Relevance.HadContextType = true;
1935 Relevance.ContextWords = &ContextWords;
1936 Relevance.MainFileSignals = Opts.MainFileSignals;
1937
1938 auto &First = Bundle.front();
1939 if (auto FuzzyScore = fuzzyScore(First))
1940 Relevance.NameMatch = *FuzzyScore;
1941 else
1942 return;
1944 bool FromIndex = false;
1945 for (const auto &Candidate : Bundle) {
1946 if (Candidate.IndexResult) {
1947 Quality.merge(*Candidate.IndexResult);
1948 Relevance.merge(*Candidate.IndexResult);
1949 Origin |= Candidate.IndexResult->Origin;
1950 FromIndex = true;
1951 if (!Candidate.IndexResult->Type.empty())
1952 Relevance.HadSymbolType |= true;
1953 if (PreferredType &&
1954 PreferredType->raw() == Candidate.IndexResult->Type) {
1955 Relevance.TypeMatchesPreferred = true;
1956 }
1957 }
1958 if (Candidate.SemaResult) {
1959 Quality.merge(*Candidate.SemaResult);
1960 Relevance.merge(*Candidate.SemaResult);
1961 if (PreferredType) {
1962 if (auto CompletionType = OpaqueType::fromCompletionResult(
1963 Recorder->CCSema->getASTContext(), *Candidate.SemaResult)) {
1964 Relevance.HadSymbolType |= true;
1965 if (PreferredType == CompletionType)
1966 Relevance.TypeMatchesPreferred = true;
1967 }
1968 }
1969 Origin |= SymbolOrigin::AST;
1970 }
1971 if (Candidate.IdentifierResult) {
1972 Quality.References = Candidate.IdentifierResult->References;
1973 Relevance.Scope = SymbolRelevanceSignals::FileScope;
1974 Origin |= SymbolOrigin::Identifier;
1975 }
1976 }
1977
1978 CodeCompletion::Scores Scores = evaluateCompletion(Quality, Relevance);
1979 if (Opts.RecordCCResult)
1980 Opts.RecordCCResult(toCodeCompletion(Bundle), Quality, Relevance,
1981 Scores.Total);
1982
1983 dlog("CodeComplete: {0} ({1}) = {2}\n{3}{4}\n", First.Name,
1984 llvm::to_string(Origin), Scores.Total, llvm::to_string(Quality),
1985 llvm::to_string(Relevance));
1986
1987 NSema += bool(Origin & SymbolOrigin::AST);
1988 NIndex += FromIndex;
1989 NSemaAndIndex += bool(Origin & SymbolOrigin::AST) && FromIndex;
1990 NIdent += bool(Origin & SymbolOrigin::Identifier);
1991 if (Candidates.push({std::move(Bundle), Scores}))
1992 Incomplete = true;
1993 }
1994
1995 CodeCompletion toCodeCompletion(const CompletionCandidate::Bundle &Bundle) {
1996 std::optional<CodeCompletionBuilder> Builder;
1997 for (const auto &Item : Bundle) {
1998 CodeCompletionString *SemaCCS =
1999 Item.SemaResult ? Recorder->codeCompletionString(*Item.SemaResult)
2000 : nullptr;
2001 if (!Builder)
2002 Builder.emplace(Recorder ? &Recorder->CCSema->getASTContext() : nullptr,
2003 Item, SemaCCS, AccessibleScopes, *Inserter, FileName,
2004 CCContextKind, Opts, IsUsingDeclaration, NextTokenKind);
2005 else
2006 Builder->add(Item, SemaCCS);
2007 }
2008 return Builder->build();
2009 }
2010};
2011
2012} // namespace
2013
2014clang::CodeCompleteOptions CodeCompleteOptions::getClangCompleteOpts() const {
2015 clang::CodeCompleteOptions Result;
2016 Result.IncludeCodePatterns = EnableSnippets;
2017 Result.IncludeMacros = true;
2018 Result.IncludeGlobals = true;
2019 // We choose to include full comments and not do doxygen parsing in
2020 // completion.
2021 // FIXME: ideally, we should support doxygen in some form, e.g. do markdown
2022 // formatting of the comments.
2023 Result.IncludeBriefComments = false;
2024
2025 // When an is used, Sema is responsible for completing the main file,
2026 // the index can provide results from the preamble.
2027 // Tell Sema not to deserialize the preamble to look for results.
2028 Result.LoadExternal = !Index;
2029 Result.IncludeFixIts = IncludeFixIts;
2030
2031 return Result;
2032}
2033
2035 unsigned Offset) {
2036 assert(Offset <= Content.size());
2037 StringRef Rest = Content.take_front(Offset);
2038 CompletionPrefix Result;
2039
2040 // Consume the unqualified name. We only handle ASCII characters.
2041 // isAsciiIdentifierContinue will let us match "0invalid", but we don't mind.
2042 while (!Rest.empty() && isAsciiIdentifierContinue(Rest.back()))
2043 Rest = Rest.drop_back();
2044 Result.Name = Content.slice(Rest.size(), Offset);
2045
2046 // Consume qualifiers.
2047 while (Rest.consume_back("::") && !Rest.endswith(":")) // reject ::::
2048 while (!Rest.empty() && isAsciiIdentifierContinue(Rest.back()))
2049 Rest = Rest.drop_back();
2050 Result.Qualifier =
2051 Content.slice(Rest.size(), Result.Name.begin() - Content.begin());
2052
2053 return Result;
2054}
2055
2056// Code complete the argument name on "/*" inside function call.
2057// Offset should be pointing to the start of the comment, i.e.:
2058// foo(^/*, rather than foo(/*^) where the cursor probably is.
2060 llvm::StringRef Prefix,
2061 const PreambleData *Preamble,
2062 const ParseInputs &ParseInput) {
2063 if (Preamble == nullptr) // Can't run without Sema.
2064 return CodeCompleteResult();
2065
2066 clang::CodeCompleteOptions Options;
2067 Options.IncludeGlobals = false;
2068 Options.IncludeMacros = false;
2069 Options.IncludeCodePatterns = false;
2070 Options.IncludeBriefComments = false;
2071 std::set<std::string> ParamNames;
2072 // We want to see signatures coming from newly introduced includes, hence a
2073 // full patch.
2074 semaCodeComplete(
2075 std::make_unique<ParamNameCollector>(Options, ParamNames), Options,
2077 PreamblePatch::createFullPatch(FileName, ParseInput, *Preamble),
2078 ParseInput});
2079 if (ParamNames.empty())
2080 return CodeCompleteResult();
2081
2082 CodeCompleteResult Result;
2083 Range CompletionRange;
2084 // Skip /*
2085 Offset += 2;
2086 CompletionRange.start = offsetToPosition(ParseInput.Contents, Offset);
2087 CompletionRange.end =
2088 offsetToPosition(ParseInput.Contents, Offset + Prefix.size());
2089 Result.CompletionRange = CompletionRange;
2090 Result.Context = CodeCompletionContext::CCC_NaturalLanguage;
2091 for (llvm::StringRef Name : ParamNames) {
2092 if (!Name.startswith(Prefix))
2093 continue;
2094 CodeCompletion Item;
2095 Item.Name = Name.str() + "=*/";
2096 Item.FilterText = Item.Name;
2097 Item.Kind = CompletionItemKind::Text;
2098 Item.CompletionTokenRange = CompletionRange;
2099 Item.Origin = SymbolOrigin::AST;
2100 Result.Completions.push_back(Item);
2101 }
2102
2103 return Result;
2104}
2105
2106// If Offset is inside what looks like argument comment (e.g.
2107// "/*^" or "/* foo^"), returns new offset pointing to the start of the /*
2108// (place where semaCodeComplete should run).
2109std::optional<unsigned>
2110maybeFunctionArgumentCommentStart(llvm::StringRef Content) {
2111 while (!Content.empty() && isAsciiIdentifierContinue(Content.back()))
2112 Content = Content.drop_back();
2113 Content = Content.rtrim();
2114 if (Content.endswith("/*"))
2115 return Content.size() - 2;
2116 return std::nullopt;
2117}
2118
2120 const PreambleData *Preamble,
2121 const ParseInputs &ParseInput,
2123 SpeculativeFuzzyFind *SpecFuzzyFind) {
2124 auto Offset = positionToOffset(ParseInput.Contents, Pos);
2125 if (!Offset) {
2126 elog("Code completion position was invalid {0}", Offset.takeError());
2127 return CodeCompleteResult();
2128 }
2129
2130 auto Content = llvm::StringRef(ParseInput.Contents).take_front(*Offset);
2131 if (auto OffsetBeforeComment = maybeFunctionArgumentCommentStart(Content)) {
2132 // We are doing code completion of a comment, where we currently only
2133 // support completing param names in function calls. To do this, we
2134 // require information from Sema, but Sema's comment completion stops at
2135 // parsing, so we must move back the position before running it, extract
2136 // information we need and construct completion items ourselves.
2137 auto CommentPrefix = Content.substr(*OffsetBeforeComment + 2).trim();
2138 return codeCompleteComment(FileName, *OffsetBeforeComment, CommentPrefix,
2140 }
2141
2142 auto Flow = CodeCompleteFlow(
2143 FileName, Preamble ? Preamble->Includes : IncludeStructure(),
2144 SpecFuzzyFind, Opts);
2145 return (!Preamble || Opts.RunParser == CodeCompleteOptions::NeverParse)
2146 ? std::move(Flow).runWithoutSema(ParseInput.Contents, *Offset,
2147 *ParseInput.TFS)
2148 : std::move(Flow).run({FileName, *Offset, *Preamble,
2149 /*PreamblePatch=*/
2150 PreamblePatch::createMacroPatch(
2152 ParseInput});
2153}
2154
2156 const PreambleData &Preamble,
2157 const ParseInputs &ParseInput,
2158 MarkupKind DocumentationFormat) {
2159 auto Offset = positionToOffset(ParseInput.Contents, Pos);
2160 if (!Offset) {
2161 elog("Signature help position was invalid {0}", Offset.takeError());
2162 return SignatureHelp();
2163 }
2164 SignatureHelp Result;
2165 clang::CodeCompleteOptions Options;
2166 Options.IncludeGlobals = false;
2167 Options.IncludeMacros = false;
2168 Options.IncludeCodePatterns = false;
2169 Options.IncludeBriefComments = false;
2170 semaCodeComplete(
2171 std::make_unique<SignatureHelpCollector>(Options, DocumentationFormat,
2172 ParseInput.Index, Result),
2173 Options,
2174 {FileName, *Offset, Preamble,
2175 PreamblePatch::createFullPatch(FileName, ParseInput, Preamble),
2176 ParseInput});
2177 return Result;
2178}
2179
2180bool isIndexedForCodeCompletion(const NamedDecl &ND, ASTContext &ASTCtx) {
2181 auto InTopLevelScope = [](const NamedDecl &ND) {
2182 switch (ND.getDeclContext()->getDeclKind()) {
2183 case Decl::TranslationUnit:
2184 case Decl::Namespace:
2185 case Decl::LinkageSpec:
2186 return true;
2187 default:
2188 break;
2189 };
2190 return false;
2191 };
2192 auto InClassScope = [](const NamedDecl &ND) {
2193 return ND.getDeclContext()->getDeclKind() == Decl::CXXRecord;
2194 };
2195 // We only complete symbol's name, which is the same as the name of the
2196 // *primary* template in case of template specializations.
2198 return false;
2199
2200 // Category decls are not useful on their own outside the interface or
2201 // implementation blocks. Moreover, sema already provides completion for
2202 // these, even if it requires preamble deserialization. So by excluding them
2203 // from the index, we reduce the noise in all the other completion scopes.
2204 if (llvm::isa<ObjCCategoryDecl>(&ND) || llvm::isa<ObjCCategoryImplDecl>(&ND))
2205 return false;
2206
2207 if (InTopLevelScope(ND))
2208 return true;
2209
2210 // Always index enum constants, even if they're not in the top level scope:
2211 // when
2212 // --all-scopes-completion is set, we'll want to complete those as well.
2213 if (const auto *EnumDecl = dyn_cast<clang::EnumDecl>(ND.getDeclContext()))
2214 return (InTopLevelScope(*EnumDecl) || InClassScope(*EnumDecl));
2215
2216 return false;
2217}
2218
2219CompletionItem CodeCompletion::render(const CodeCompleteOptions &Opts) const {
2220 CompletionItem LSP;
2221 const auto *InsertInclude = Includes.empty() ? nullptr : &Includes[0];
2222 LSP.label = ((InsertInclude && InsertInclude->Insertion)
2223 ? Opts.IncludeIndicator.Insert
2224 : Opts.IncludeIndicator.NoInsert) +
2225 (Opts.ShowOrigins ? "[" + llvm::to_string(Origin) + "]" : "") +
2226 RequiredQualifier + Name + Signature;
2227
2228 LSP.kind = Kind;
2229 LSP.detail = BundleSize > 1
2230 ? std::string(llvm::formatv("[{0} overloads]", BundleSize))
2231 : ReturnType;
2232 LSP.deprecated = Deprecated;
2233 // Combine header information and documentation in LSP `documentation` field.
2234 // This is not quite right semantically, but tends to display well in editors.
2235 if (InsertInclude || Documentation) {
2236 markup::Document Doc;
2237 if (InsertInclude)
2238 Doc.addParagraph().appendText("From ").appendCode(InsertInclude->Header);
2239 if (Documentation)
2240 Doc.append(*Documentation);
2241 LSP.documentation = renderDoc(Doc, Opts.DocumentationFormat);
2242 }
2243 LSP.sortText = sortText(Score.Total, FilterText);
2244 LSP.filterText = FilterText;
2245 LSP.textEdit = {CompletionTokenRange, RequiredQualifier + Name, ""};
2246 // Merge continuous additionalTextEdits into main edit. The main motivation
2247 // behind this is to help LSP clients, it seems most of them are confused when
2248 // they are provided with additionalTextEdits that are consecutive to main
2249 // edit.
2250 // Note that we store additional text edits from back to front in a line. That
2251 // is mainly to help LSP clients again, so that changes do not effect each
2252 // other.
2253 for (const auto &FixIt : FixIts) {
2254 if (FixIt.range.end == LSP.textEdit->range.start) {
2255 LSP.textEdit->newText = FixIt.newText + LSP.textEdit->newText;
2256 LSP.textEdit->range.start = FixIt.range.start;
2257 } else {
2258 LSP.additionalTextEdits.push_back(FixIt);
2259 }
2260 }
2261 if (Opts.EnableSnippets)
2262 LSP.textEdit->newText += SnippetSuffix;
2263
2264 // FIXME(kadircet): Do not even fill insertText after making sure textEdit is
2265 // compatible with most of the editors.
2266 LSP.insertText = LSP.textEdit->newText;
2267 // Some clients support snippets but work better with plaintext.
2268 // So if the snippet is trivial, let the client know.
2269 // https://github.com/clangd/clangd/issues/922
2270 LSP.insertTextFormat = (Opts.EnableSnippets && !SnippetSuffix.empty())
2271 ? InsertTextFormat::Snippet
2272 : InsertTextFormat::PlainText;
2273 if (InsertInclude && InsertInclude->Insertion)
2274 LSP.additionalTextEdits.push_back(*InsertInclude->Insertion);
2275
2276 LSP.score = Score.ExcludingName;
2277
2278 return LSP;
2279}
2280
2281llvm::raw_ostream &operator<<(llvm::raw_ostream &OS, const CodeCompletion &C) {
2282 // For now just lean on CompletionItem.
2283 return OS << C.render(CodeCompleteOptions());
2284}
2285
2286llvm::raw_ostream &operator<<(llvm::raw_ostream &OS,
2287 const CodeCompleteResult &R) {
2288 OS << "CodeCompleteResult: " << R.Completions.size() << (R.HasMore ? "+" : "")
2289 << " (" << getCompletionKindString(R.Context) << ")"
2290 << " items:\n";
2291 for (const auto &C : R.Completions)
2292 OS << C << "\n";
2293 return OS;
2294}
2295
2296// Heuristically detect whether the `Line` is an unterminated include filename.
2297bool isIncludeFile(llvm::StringRef Line) {
2298 Line = Line.ltrim();
2299 if (!Line.consume_front("#"))
2300 return false;
2301 Line = Line.ltrim();
2302 if (!(Line.consume_front("include_next") || Line.consume_front("include") ||
2303 Line.consume_front("import")))
2304 return false;
2305 Line = Line.ltrim();
2306 if (Line.consume_front("<"))
2307 return Line.count('>') == 0;
2308 if (Line.consume_front("\""))
2309 return Line.count('"') == 0;
2310 return false;
2311}
2312
2313bool allowImplicitCompletion(llvm::StringRef Content, unsigned Offset) {
2314 // Look at last line before completion point only.
2315 Content = Content.take_front(Offset);
2316 auto Pos = Content.rfind('\n');
2317 if (Pos != llvm::StringRef::npos)
2318 Content = Content.substr(Pos + 1);
2319
2320 // Complete after scope operators.
2321 if (Content.endswith(".") || Content.endswith("->") ||
2322 Content.endswith("::") || Content.endswith("/*"))
2323 return true;
2324 // Complete after `#include <` and #include `<foo/`.
2325 if ((Content.endswith("<") || Content.endswith("\"") ||
2326 Content.endswith("/")) &&
2327 isIncludeFile(Content))
2328 return true;
2329
2330 // Complete words. Give non-ascii characters the benefit of the doubt.
2331 return !Content.empty() && (isAsciiIdentifierContinue(Content.back()) ||
2332 !llvm::isASCII(Content.back()));
2333}
2334
2335} // namespace clangd
2336} // namespace clang
const Expr * E
const FunctionDecl * Decl
BindArgumentKind Kind
unsigned References
const ParseInputs & ParseInput
std::string Signature
std::vector< std::string > AccessibleScopes
std::optional< std::string > UnresolvedQualifier
CodeCompletionContext CCContext
size_t Offset
llvm::SmallVector< SymbolInclude, 1 > RankedIncludeHeaders
const RawIdentifier * IdentifierResult
const Symbol * IndexResult
std::vector< std::string > QueryScopes
SymbolID IDForDoc
std::vector< CodeCompletionResult > Results
std::string ReturnType
Sema * CCSema
std::optional< std::string > EnclosingNamespace
const std::optional< PreamblePatch > Patch
bool AllowAllScopes
std::string SnippetSuffix
SignatureQualitySignals Quality
const PreambleData & Preamble
const CodeCompletionResult * SemaResult
CodeCompletionBuilder Builder
const Criteria C
CognitiveComplexity CC
ExpectedMatch Candidate
std::optional< float > Score
IgnoringDiagConsumer IgnoreDiags
std::unique_ptr< CompilerInstance > Clang
CharSourceRange Range
SourceRange for the file name.
StringRef FileName
int X
#define dlog(...)
Definition: Logger.h:101
const MacroDirective * Directive
Token Name
FieldAction Action
size_t Pos
std::string MacroName
Definition: Preamble.cpp:230
Kind K
Definition: Rename.cpp:454
std::unique_ptr< CompilerInvocation > CI
std::string Output
Definition: TraceTests.cpp:159
llvm::raw_string_ostream OS
Definition: TraceTests.cpp:160
#define SPAN_ATTACH(S, Name, Expr)
Attach a key-value pair to a Span event.
Definition: Trace.h:164
std::optional< FixItHint > FixIt
void collect(const CompilerInstance &CI)
Definition: Headers.cpp:175
static std::optional< OpaqueType > fromCompletionResult(ASTContext &Ctx, const CodeCompletionResult &R)
Create a type from a code completion result.
static std::optional< OpaqueType > fromType(ASTContext &Ctx, QualType Type)
Construct an instance from a clang::QualType.
virtual bool fuzzyFind(const FuzzyFindRequest &Req, llvm::function_ref< void(const Symbol &)> Callback) const =0
Matches symbols in the index fuzzily and applies Callback on each matched symbol before returning.
static llvm::Expected< std::string > resolve(const URI &U, llvm::StringRef HintPath="")
Resolves the absolute path of U.
Definition: URI.cpp:245
A format-agnostic representation for structured text.
Definition: Markup.h:97
Paragraph & addParagraph()
Adds a semantical block that will be separate from others.
Definition: Markup.cpp:473
void append(Document Other)
Definition: Markup.cpp:468
Paragraph & appendText(llvm::StringRef Text)
Append plain text to the end of the string.
Definition: Markup.cpp:423
Paragraph & appendCode(llvm::StringRef Code, bool Preserve=false)
Append inline code, this translates to the ` block in markdown.
Definition: Markup.cpp:436
std::pair< StringRef, StringRef > splitQualifiedName(StringRef QName)
Definition: SourceCode.cpp:493
@ Info
An information message.
SymbolID getSymbolID(const Decl *D)
Gets the symbol ID for a declaration. Returned SymbolID might be null.
Definition: AST.cpp:348
std::string formatDocumentation(const CodeCompletionString &CCS, llvm::StringRef DocComment)
Assembles formatted documentation for a completion result.
Range halfOpenToRange(const SourceManager &SM, CharSourceRange R)
Definition: SourceCode.cpp:468
std::string sortText(float Score, llvm::StringRef Name)
Returns a string that sorts in the same order as (-Score, Tiebreak), for LSP.
Definition: Quality.cpp:548
std::string getDeclComment(const ASTContext &Ctx, const NamedDecl &Decl)
Similar to getDocComment, but returns the comment for a NamedDecl.
bool isIncludeFile(llvm::StringRef Line)
TextEdit toTextEdit(const FixItHint &FixIt, const SourceManager &M, const LangOptions &L)
Definition: SourceCode.cpp:552
Position offsetToPosition(llvm::StringRef Code, size_t Offset)
Turn an offset in Code into a [line, column] pair.
Definition: SourceCode.cpp:202
size_t lspLength(llvm::StringRef Code)
Definition: SourceCode.cpp:149
CompletionPrefix guessCompletionPrefix(llvm::StringRef Content, unsigned Offset)
std::unique_ptr< CompilerInvocation > buildCompilerInvocation(const ParseInputs &Inputs, clang::DiagnosticConsumer &D, std::vector< std::string > *CC1Args)
Builds compiler invocation that could be used to build AST or preamble.
Definition: Compiler.cpp:95
bool isExplicitTemplateSpecialization(const NamedDecl *D)
Indicates if D is an explicit template specialization, e.g.
Definition: AST.cpp:163
format::FormatStyle getFormatStyleForFile(llvm::StringRef File, llvm::StringRef Content, const ThreadsafeFS &TFS)
Choose the clang-format style we should apply to a certain file.
Definition: SourceCode.cpp:579
CompletionItemKind
The kind of a completion entry.
Definition: Protocol.h:338
bool allowImplicitCompletion(llvm::StringRef Content, unsigned Offset)
void vlog(const char *Fmt, Ts &&... Vals)
Definition: Logger.h:72
static const char * toString(OffsetEncoding OE)
Definition: Protocol.cpp:1477
CodeCompleteResult codeCompleteComment(PathRef FileName, unsigned Offset, llvm::StringRef Prefix, const PreambleData *Preamble, const ParseInputs &ParseInput)
llvm::Error error(std::error_code EC, const char *Fmt, Ts &&... Vals)
Definition: Logger.h:79
llvm::raw_ostream & operator<<(llvm::raw_ostream &OS, const CodeCompletion &C)
std::string getReturnType(const CodeCompletionString &CCS)
Gets detail to be used as the detail field in an LSP completion item.
Position sourceLocToPosition(const SourceManager &SM, SourceLocation Loc)
Turn a SourceLocation into a [line, column] pair.
Definition: SourceCode.cpp:214
llvm::StringMap< unsigned > collectIdentifiers(llvm::StringRef Content, const format::FormatStyle &Style)
Collects identifiers with counts in the source code.
Definition: SourceCode.cpp:614
bool hasUnstableLinkage(const Decl *D)
Whether we must avoid computing linkage for D during code completion.
Definition: AST.cpp:710
llvm::json::Value toJSON(const FuzzyFindRequest &Request)
Definition: Index.cpp:45
std::vector< std::string > visibleNamespaces(llvm::StringRef Code, const LangOptions &LangOpts)
Heuristically determine namespaces visible at a point, without parsing Code.
Definition: SourceCode.cpp:805
llvm::Expected< HeaderFile > toHeaderFile(llvm::StringRef Header, llvm::StringRef HintPath)
Creates a HeaderFile from Header which can be either a URI or a literal include.
Definition: Headers.cpp:140
std::unique_ptr< CompilerInstance > prepareCompilerInstance(std::unique_ptr< clang::CompilerInvocation > CI, const PrecompiledPreamble *Preamble, std::unique_ptr< llvm::MemoryBuffer > Buffer, llvm::IntrusiveRefCntPtr< llvm::vfs::FileSystem > VFS, DiagnosticConsumer &DiagsClient)
Definition: Compiler.cpp:129
void log(const char *Fmt, Ts &&... Vals)
Definition: Logger.h:67
llvm::Expected< size_t > positionToOffset(llvm::StringRef Code, Position P, bool AllowColumnsBeyondLineLength)
Turn a [line, column] pair into an offset in Code.
Definition: SourceCode.cpp:173
std::optional< unsigned > maybeFunctionArgumentCommentStart(llvm::StringRef Content)
llvm::StringSet collectWords(llvm::StringRef Content)
Collects words from the source code.
Definition: SourceCode.cpp:853
void getSignature(const CodeCompletionString &CCS, std::string *Signature, std::string *Snippet, CodeCompletionResult::ResultKind ResultKind, CXCursorKind CursorKind, std::string *RequiredQualifiers)
Formats the signature for an item, as a display string and snippet.
llvm::SmallVector< SymbolInclude, 1 > getRankedIncludes(const Symbol &Sym)
Definition: Headers.cpp:160
std::pair< size_t, size_t > offsetToClangLineColumn(llvm::StringRef Code, size_t Offset)
Definition: SourceCode.cpp:483
@ Deprecated
Deprecated or obsolete code.
Definition: Protocol.h:901
void parseDocumentation(llvm::StringRef Input, markup::Document &Output)
Definition: Hover.cpp:1596
float evaluateSymbolAndRelevance(float SymbolQuality, float SymbolRelevance)
Combine symbol quality and relevance into a single score.
Definition: Quality.cpp:530
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.
std::string printQualifiedName(const NamedDecl &ND)
Returns the qualified name of ND.
Definition: AST.cpp:182
llvm::StringRef PathRef
A typedef to represent a ref to file path.
Definition: Path.h:29
SignatureHelp signatureHelp(PathRef FileName, Position Pos, const PreambleData &Preamble, const ParseInputs &ParseInput, MarkupKind DocumentationFormat)
Get signature help at a specified Pos in FileName.
void elog(const char *Fmt, Ts &&... Vals)
Definition: Logger.h:61
std::string getDocComment(const ASTContext &Ctx, const CodeCompletionResult &Result, bool CommentsFromHeaders)
Gets a minimally formatted documentation comment of Result, with comment markers stripped.
std::string printNamespaceScope(const DeclContext &DC)
Returns the first enclosing namespace scope starting from DC.
Definition: AST.cpp:294
bool isIndexedForCodeCompletion(const NamedDecl &ND, ASTContext &ASTCtx)
std::array< uint8_t, 20 > SymbolID
===– Representation.cpp - ClangDoc Representation --------—*- C++ -*-===//
-clang-tidy
Symbol::IncludeDirective InsertionDirective
Preferred preprocessor directive to use for inclusions by the file.
Definition: ASTSignals.h:34
static const CodeCompletionRankingModel DefaultRankingModel
Definition: CodeComplete.h:138
CodeCompletionRankingModel
Model to use for ranking code completion candidates.
Definition: CodeComplete.h:134
const ASTSignals * MainFileSignals
Definition: CodeComplete.h:94
bool ImportInsertions
Whether include insertions for Objective-C code should use #import instead of #include.
Definition: CodeComplete.h:75
bool AllScopes
Whether to include index symbols that are not defined in the scopes visible from the code completion ...
Definition: CodeComplete.h:108
std::vector< CodeCompletion > Completions
Definition: CodeComplete.h:246
CodeCompletionContext::Kind Context
Definition: CodeComplete.h:248
Range CompletionTokenRange
Holds the range of the token we are going to replace with this completion.
Definition: CodeComplete.h:213
std::string sortText
A string that should be used when comparing this item with other items.
Definition: Protocol.h:1298
std::optional< TextEdit > textEdit
An edit which is applied to a document when selecting this completion.
Definition: Protocol.h:1317
std::string filterText
A string that should be used when filtering a set of completion items.
Definition: Protocol.h:1302
std::string detail
A human-readable string with additional information about this item, like type or symbol information.
Definition: Protocol.h:1291
InsertTextFormat insertTextFormat
The format of the insert text.
Definition: Protocol.h:1310
CompletionItemKind kind
The kind of this completion item.
Definition: Protocol.h:1287
std::vector< TextEdit > additionalTextEdits
An optional array of additional text edits that are applied when selecting this completion.
Definition: Protocol.h:1322
std::optional< MarkupContent > documentation
A human-readable string that represents a doc-comment.
Definition: Protocol.h:1294
std::string insertText
A string that should be inserted to a document when selecting this completion.
Definition: Protocol.h:1306
bool deprecated
Indicates if this item is deprecated.
Definition: Protocol.h:1325
float score
The score that clangd calculates to rank the returned completions.
Definition: Protocol.h:1332
std::string label
The label of this completion item.
Definition: Protocol.h:1283
Information required to run clang, e.g. to parse AST or do code completion.
Definition: Compiler.h:48
The parsed preamble and associated data.
Definition: Preamble.h:55
Position start
The range's start position.
Definition: Protocol.h:187
Position end
The range's end position.
Definition: Protocol.h:190
Represents the signature of a callable.
Definition: Protocol.h:1392
A speculative and asynchronous fuzzy find index request (based on cached request) that can be sent be...
Definition: CodeComplete.h:263
@ Deprecated
Indicates if the symbol is deprecated.
Definition: Symbol.h:143
@ Include
#include "header.h"
Definition: Symbol.h:93
@ Import
#import "header.h"
Definition: Symbol.h:95