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