1//===- CodeCompleteConsumer.h - Code Completion Interface -------*- 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// This file defines the CodeCompleteConsumer class.
10//
11//===----------------------------------------------------------------------===//
12
13#ifndef LLVM_CLANG_SEMA_CODECOMPLETECONSUMER_H
14#define LLVM_CLANG_SEMA_CODECOMPLETECONSUMER_H
15
16#include "clang-c/Index.h"
17#include "clang/AST/Type.h"
18#include "clang/Basic/LLVM.h"
19#include "clang/Lex/MacroInfo.h"
20#include "clang/Sema/CodeCompleteOptions.h"
21#include "clang/Sema/DeclSpec.h"
22#include "llvm/ADT/ArrayRef.h"
23#include "llvm/ADT/DenseMap.h"
24#include "llvm/ADT/SmallPtrSet.h"
25#include "llvm/ADT/SmallVector.h"
26#include "llvm/ADT/StringRef.h"
27#include "llvm/Support/Allocator.h"
28#include "llvm/Support/type_traits.h"
29#include <cassert>
30#include <memory>
31#include <optional>
32#include <string>
33#include <utility>
34
35namespace clang {
36
37class ASTContext;
38class Decl;
39class DeclContext;
40class FunctionDecl;
41class FunctionTemplateDecl;
42class IdentifierInfo;
43class LangOptions;
44class NamedDecl;
45class NestedNameSpecifier;
46class Preprocessor;
47class RawComment;
48class Sema;
49class UsingShadowDecl;
50
51/// Default priority values for code-completion results based
52/// on their kind.
53enum {
54 /// Priority for the next initialization in a constructor initializer
55 /// list.
56 CCP_NextInitializer = 7,
57
58 /// Priority for an enumeration constant inside a switch whose
59 /// condition is of the enumeration type.
60 CCP_EnumInCase = 7,
61
62 /// Priority for a send-to-super completion.
63 CCP_SuperCompletion = 20,
64
65 /// Priority for a declaration that is in the local scope.
66 CCP_LocalDeclaration = 34,
67
68 /// Priority for a member declaration found from the current
69 /// method or member function.
70 CCP_MemberDeclaration = 35,
71
72 /// Priority for a language keyword (that isn't any of the other
73 /// categories).
74 CCP_Keyword = 40,
75
76 /// Priority for a code pattern.
77 CCP_CodePattern = 40,
78
79 /// Priority for a non-type declaration.
80 CCP_Declaration = 50,
81
82 /// Priority for a type.
83 CCP_Type = CCP_Declaration,
84
85 /// Priority for a constant value (e.g., enumerator).
86 CCP_Constant = 65,
87
88 /// Priority for a preprocessor macro.
89 CCP_Macro = 70,
90
91 /// Priority for a nested-name-specifier.
92 CCP_NestedNameSpecifier = 75,
93
94 /// Priority for a result that isn't likely to be what the user wants,
95 /// but is included for completeness.
96 CCP_Unlikely = 80,
97
98 /// Priority for the Objective-C "_cmd" implicit parameter.
99 CCP_ObjC_cmd = CCP_Unlikely
100};
101
102/// Priority value deltas that are added to code-completion results
103/// based on the context of the result.
104enum {
105 /// The result is in a base class.
106 CCD_InBaseClass = 2,
107
108 /// The result is a C++ non-static member function whose qualifiers
109 /// exactly match the object type on which the member function can be called.
110 CCD_ObjectQualifierMatch = -1,
111
112 /// The selector of the given message exactly matches the selector
113 /// of the current method, which might imply that some kind of delegation
114 /// is occurring.
115 CCD_SelectorMatch = -3,
116
117 /// Adjustment to the "bool" type in Objective-C, where the typedef
118 /// "BOOL" is preferred.
119 CCD_bool_in_ObjC = 1,
120
121 /// Adjustment for KVC code pattern priorities when it doesn't look
122 /// like the
123 CCD_ProbablyNotObjCCollection = 15,
124
125 /// An Objective-C method being used as a property.
126 CCD_MethodAsProperty = 2,
127
128 /// An Objective-C block property completed as a setter with a
129 /// block placeholder.
130 CCD_BlockPropertySetter = 3
131};
132
133/// Priority value factors by which we will divide or multiply the
134/// priority of a code-completion result.
135enum {
136 /// Divide by this factor when a code-completion result's type exactly
137 /// matches the type we expect.
138 CCF_ExactTypeMatch = 4,
139
140 /// Divide by this factor when a code-completion result's type is
141 /// similar to the type we expect (e.g., both arithmetic types, both
142 /// Objective-C object pointer types).
143 CCF_SimilarTypeMatch = 2
144};
145
146/// A simplified classification of types used when determining
147/// "similar" types for code completion.
148enum SimplifiedTypeClass {
149 STC_Arithmetic,
150 STC_Array,
151 STC_Block,
152 STC_Function,
153 STC_ObjectiveC,
154 STC_Other,
155 STC_Pointer,
156 STC_Record,
157 STC_Void
158};
159
160/// Determine the simplified type class of the given canonical type.
161SimplifiedTypeClass getSimplifiedTypeClass(CanQualType T);
162
163/// Determine the type that this declaration will have if it is used
164/// as a type or in an expression.
165QualType getDeclUsageType(ASTContext &C, const NamedDecl *ND);
166
167/// Determine the priority to be given to a macro code completion result
168/// with the given name.
169///
170/// \param MacroName The name of the macro.
171///
172/// \param LangOpts Options describing the current language dialect.
173///
174/// \param PreferredTypeIsPointer Whether the preferred type for the context
175/// of this macro is a pointer type.
176unsigned getMacroUsagePriority(StringRef MacroName,
177 const LangOptions &LangOpts,
178 bool PreferredTypeIsPointer = false);
179
180/// Determine the libclang cursor kind associated with the given
181/// declaration.
182CXCursorKind getCursorKindForDecl(const Decl *D);
183
184/// The context in which code completion occurred, so that the
185/// code-completion consumer can process the results accordingly.
186class CodeCompletionContext {
187public:
188 enum Kind {
189 /// An unspecified code-completion context.
190 CCC_Other,
191
192 /// An unspecified code-completion context where we should also add
193 /// macro completions.
194 CCC_OtherWithMacros,
195
196 /// Code completion occurred within a "top-level" completion context,
197 /// e.g., at namespace or global scope.
198 CCC_TopLevel,
199
200 /// Code completion occurred within an Objective-C interface,
201 /// protocol, or category interface.
202 CCC_ObjCInterface,
203
204 /// Code completion occurred within an Objective-C implementation
205 /// or category implementation.
206 CCC_ObjCImplementation,
207
208 /// Code completion occurred within the instance variable list of
209 /// an Objective-C interface, implementation, or category implementation.
210 CCC_ObjCIvarList,
211
212 /// Code completion occurred within a class, struct, or union.
213 CCC_ClassStructUnion,
214
215 /// Code completion occurred where a statement (or declaration) is
216 /// expected in a function, method, or block.
217 CCC_Statement,
218
219 /// Code completion occurred where an expression is expected.
220 CCC_Expression,
221
222 /// Code completion occurred where an Objective-C message receiver
223 /// is expected.
224 CCC_ObjCMessageReceiver,
225
226 /// Code completion occurred on the right-hand side of a member
227 /// access expression using the dot operator.
228 ///
229 /// The results of this completion are the members of the type being
230 /// accessed. The type itself is available via
231 /// \c CodeCompletionContext::getType().
232 CCC_DotMemberAccess,
233
234 /// Code completion occurred on the right-hand side of a member
235 /// access expression using the arrow operator.
236 ///
237 /// The results of this completion are the members of the type being
238 /// accessed. The type itself is available via
239 /// \c CodeCompletionContext::getType().
240 CCC_ArrowMemberAccess,
241
242 /// Code completion occurred on the right-hand side of an Objective-C
243 /// property access expression.
244 ///
245 /// The results of this completion are the members of the type being
246 /// accessed. The type itself is available via
247 /// \c CodeCompletionContext::getType().
248 CCC_ObjCPropertyAccess,
249
250 /// Code completion occurred after the "enum" keyword, to indicate
251 /// an enumeration name.
252 CCC_EnumTag,
253
254 /// Code completion occurred after the "union" keyword, to indicate
255 /// a union name.
256 CCC_UnionTag,
257
258 /// Code completion occurred after the "struct" or "class" keyword,
259 /// to indicate a struct or class name.
260 CCC_ClassOrStructTag,
261
262 /// Code completion occurred where a protocol name is expected.
263 CCC_ObjCProtocolName,
264
265 /// Code completion occurred where a namespace or namespace alias
266 /// is expected.
267 CCC_Namespace,
268
269 /// Code completion occurred where a type name is expected.
270 CCC_Type,
271
272 /// Code completion occurred where a new name is expected.
273 CCC_NewName,
274
275 /// Code completion occurred where both a new name and an existing symbol is
276 /// permissible.
277 CCC_SymbolOrNewName,
278
279 /// Code completion occurred where an existing name(such as type, function
280 /// or variable) is expected.
281 CCC_Symbol,
282
283 /// Code completion occurred where an macro is being defined.
284 CCC_MacroName,
285
286 /// Code completion occurred where a macro name is expected
287 /// (without any arguments, in the case of a function-like macro).
288 CCC_MacroNameUse,
289
290 /// Code completion occurred within a preprocessor expression.
291 CCC_PreprocessorExpression,
292
293 /// Code completion occurred where a preprocessor directive is
294 /// expected.
295 CCC_PreprocessorDirective,
296
297 /// Code completion occurred in a context where natural language is
298 /// expected, e.g., a comment or string literal.
299 ///
300 /// This context usually implies that no completions should be added,
301 /// unless they come from an appropriate natural-language dictionary.
302 CCC_NaturalLanguage,
303
304 /// Code completion for a selector, as in an \@selector expression.
305 CCC_SelectorName,
306
307 /// Code completion within a type-qualifier list.
308 CCC_TypeQualifiers,
309
310 /// Code completion in a parenthesized expression, which means that
311 /// we may also have types here in C and Objective-C (as well as in C++).
312 CCC_ParenthesizedExpression,
313
314 /// Code completion where an Objective-C instance message is
315 /// expected.
316 CCC_ObjCInstanceMessage,
317
318 /// Code completion where an Objective-C class message is expected.
319 CCC_ObjCClassMessage,
320
321 /// Code completion where the name of an Objective-C class is
322 /// expected.
323 CCC_ObjCInterfaceName,
324
325 /// Code completion where an Objective-C category name is expected.
326 CCC_ObjCCategoryName,
327
328 /// Code completion inside the filename part of a #include directive.
329 CCC_IncludedFile,
330
331 /// Code completion of an attribute name.
332 CCC_Attribute,
333
334 /// An unknown context, in which we are recovering from a parsing
335 /// error and don't know which completions we should give.
336 CCC_Recovery,
337
338 /// Code completion in a @class forward declaration.
339 CCC_ObjCClassForwardDecl,
340
341 /// Code completion at a top level, i.e. in a namespace or global scope,
342 /// but also in expression statements. This is because REPL inputs can be
343 /// declarations or expression statements.
344 CCC_TopLevelOrExpression,
345 };
346
347 using VisitedContextSet = llvm::SmallPtrSet<DeclContext *, 8>;
348
349private:
350 Kind CCKind;
351
352 /// Indicates whether we are completing a name of a using declaration, e.g.
353 /// using ^;
354 /// using a::^;
355 bool IsUsingDeclaration;
356
357 /// The type that would prefer to see at this point (e.g., the type
358 /// of an initializer or function parameter).
359 QualType PreferredType;
360
361 /// The type of the base object in a member access expression.
362 QualType BaseType;
363
364 /// The identifiers for Objective-C selector parts.
365 ArrayRef<IdentifierInfo *> SelIdents;
366
367 /// The scope specifier that comes before the completion token e.g.
368 /// "a::b::"
369 std::optional<CXXScopeSpec> ScopeSpecifier;
370
371 /// A set of declaration contexts visited by Sema when doing lookup for
372 /// code completion.
373 VisitedContextSet VisitedContexts;
374
375public:
376 /// Construct a new code-completion context of the given kind.
377 CodeCompletionContext(Kind CCKind)
378 : CCKind(CCKind), IsUsingDeclaration(false), SelIdents(std::nullopt) {}
379
380 /// Construct a new code-completion context of the given kind.
381 CodeCompletionContext(Kind CCKind, QualType T,
382 ArrayRef<IdentifierInfo *> SelIdents = std::nullopt)
383 : CCKind(CCKind), IsUsingDeclaration(false), SelIdents(SelIdents) {
384 if (CCKind == CCC_DotMemberAccess || CCKind == CCC_ArrowMemberAccess ||
385 CCKind == CCC_ObjCPropertyAccess || CCKind == CCC_ObjCClassMessage ||
386 CCKind == CCC_ObjCInstanceMessage)
387 BaseType = T;
388 else
389 PreferredType = T;
390 }
391
392 bool isUsingDeclaration() const { return IsUsingDeclaration; }
393 void setIsUsingDeclaration(bool V) { IsUsingDeclaration = V; }
394
395 /// Retrieve the kind of code-completion context.
396 Kind getKind() const { return CCKind; }
397
398 /// Retrieve the type that this expression would prefer to have, e.g.,
399 /// if the expression is a variable initializer or a function argument, the
400 /// type of the corresponding variable or function parameter.
401 QualType getPreferredType() const { return PreferredType; }
402 void setPreferredType(QualType T) { PreferredType = T; }
403
404 /// Retrieve the type of the base object in a member-access
405 /// expression.
406 QualType getBaseType() const { return BaseType; }
407
408 /// Retrieve the Objective-C selector identifiers.
409 ArrayRef<IdentifierInfo *> getSelIdents() const { return SelIdents; }
410
411 /// Determines whether we want C++ constructors as results within this
412 /// context.
413 bool wantConstructorResults() const;
414
415 /// Sets the scope specifier that comes before the completion token.
416 /// This is expected to be set in code completions on qualfied specifiers
417 /// (e.g. "a::b::").
418 void setCXXScopeSpecifier(CXXScopeSpec SS) {
419 this->ScopeSpecifier = std::move(SS);
420 }
421
422 /// Adds a visited context.
423 void addVisitedContext(DeclContext *Ctx) {
424 VisitedContexts.insert(Ptr: Ctx);
425 }
426
427 /// Retrieves all visited contexts.
428 const VisitedContextSet &getVisitedContexts() const {
429 return VisitedContexts;
430 }
431
432 std::optional<const CXXScopeSpec *> getCXXScopeSpecifier() {
433 if (ScopeSpecifier)
434 return &*ScopeSpecifier;
435 return std::nullopt;
436 }
437};
438
439/// Get string representation of \p Kind, useful for debugging.
440llvm::StringRef getCompletionKindString(CodeCompletionContext::Kind Kind);
441
442/// A "string" used to describe how code completion can
443/// be performed for an entity.
444///
445/// A code completion string typically shows how a particular entity can be
446/// used. For example, the code completion string for a function would show
447/// the syntax to call it, including the parentheses, placeholders for the
448/// arguments, etc.
449class CodeCompletionString {
450public:
451 /// The different kinds of "chunks" that can occur within a code
452 /// completion string.
453 enum ChunkKind {
454 /// The piece of text that the user is expected to type to
455 /// match the code-completion string, typically a keyword or the name of a
456 /// declarator or macro.
457 CK_TypedText,
458
459 /// A piece of text that should be placed in the buffer, e.g.,
460 /// parentheses or a comma in a function call.
461 CK_Text,
462
463 /// A code completion string that is entirely optional. For example,
464 /// an optional code completion string that describes the default arguments
465 /// in a function call.
466 CK_Optional,
467
468 /// A string that acts as a placeholder for, e.g., a function
469 /// call argument.
470 CK_Placeholder,
471
472 /// A piece of text that describes something about the result but
473 /// should not be inserted into the buffer.
474 CK_Informative,
475 /// A piece of text that describes the type of an entity or, for
476 /// functions and methods, the return type.
477 CK_ResultType,
478
479 /// A piece of text that describes the parameter that corresponds
480 /// to the code-completion location within a function call, message send,
481 /// macro invocation, etc.
482 CK_CurrentParameter,
483
484 /// A left parenthesis ('(').
485 CK_LeftParen,
486
487 /// A right parenthesis (')').
488 CK_RightParen,
489
490 /// A left bracket ('[').
491 CK_LeftBracket,
492
493 /// A right bracket (']').
494 CK_RightBracket,
495
496 /// A left brace ('{').
497 CK_LeftBrace,
498
499 /// A right brace ('}').
500 CK_RightBrace,
501
502 /// A left angle bracket ('<').
503 CK_LeftAngle,
504
505 /// A right angle bracket ('>').
506 CK_RightAngle,
507
508 /// A comma separator (',').
509 CK_Comma,
510
511 /// A colon (':').
512 CK_Colon,
513
514 /// A semicolon (';').
515 CK_SemiColon,
516
517 /// An '=' sign.
518 CK_Equal,
519
520 /// Horizontal whitespace (' ').
521 CK_HorizontalSpace,
522
523 /// Vertical whitespace ('\\n' or '\\r\\n', depending on the
524 /// platform).
525 CK_VerticalSpace
526 };
527
528 /// One piece of the code completion string.
529 struct Chunk {
530 /// The kind of data stored in this piece of the code completion
531 /// string.
532 ChunkKind Kind = CK_Text;
533
534 union {
535 /// The text string associated with a CK_Text, CK_Placeholder,
536 /// CK_Informative, or CK_Comma chunk.
537 /// The string is owned by the chunk and will be deallocated
538 /// (with delete[]) when the chunk is destroyed.
539 const char *Text;
540
541 /// The code completion string associated with a CK_Optional chunk.
542 /// The optional code completion string is owned by the chunk, and will
543 /// be deallocated (with delete) when the chunk is destroyed.
544 CodeCompletionString *Optional;
545 };
546
547 Chunk() : Text(nullptr) {}
548
549 explicit Chunk(ChunkKind Kind, const char *Text = "");
550
551 /// Create a new text chunk.
552 static Chunk CreateText(const char *Text);
553
554 /// Create a new optional chunk.
555 static Chunk CreateOptional(CodeCompletionString *Optional);
556
557 /// Create a new placeholder chunk.
558 static Chunk CreatePlaceholder(const char *Placeholder);
559
560 /// Create a new informative chunk.
561 static Chunk CreateInformative(const char *Informative);
562
563 /// Create a new result type chunk.
564 static Chunk CreateResultType(const char *ResultType);
565
566 /// Create a new current-parameter chunk.
567 static Chunk CreateCurrentParameter(const char *CurrentParameter);
568 };
569
570private:
571 friend class CodeCompletionBuilder;
572 friend class CodeCompletionResult;
573
574 /// The number of chunks stored in this string.
575 unsigned NumChunks : 16;
576
577 /// The number of annotations for this code-completion result.
578 unsigned NumAnnotations : 16;
579
580 /// The priority of this code-completion string.
581 unsigned Priority : 16;
582
583 /// The availability of this code-completion result.
584 LLVM_PREFERRED_TYPE(CXAvailabilityKind)
585 unsigned Availability : 2;
586
587 /// The name of the parent context.
588 StringRef ParentName;
589
590 /// A brief documentation comment attached to the declaration of
591 /// entity being completed by this result.
592 const char *BriefComment;
593
594 CodeCompletionString(const Chunk *Chunks, unsigned NumChunks,
595 unsigned Priority, CXAvailabilityKind Availability,
596 const char **Annotations, unsigned NumAnnotations,
597 StringRef ParentName,
598 const char *BriefComment);
599 ~CodeCompletionString() = default;
600
601public:
602 CodeCompletionString(const CodeCompletionString &) = delete;
603 CodeCompletionString &operator=(const CodeCompletionString &) = delete;
604
605 using iterator = const Chunk *;
606
607 iterator begin() const { return reinterpret_cast<const Chunk *>(this + 1); }
608 iterator end() const { return begin() + NumChunks; }
609 bool empty() const { return NumChunks == 0; }
610 unsigned size() const { return NumChunks; }
611
612 const Chunk &operator[](unsigned I) const {
613 assert(I < size() && "Chunk index out-of-range");
614 return begin()[I];
615 }
616
617 /// Returns the text in the first TypedText chunk.
618 const char *getTypedText() const;
619
620 /// Returns the combined text from all TypedText chunks.
621 std::string getAllTypedText() const;
622
623 /// Retrieve the priority of this code completion result.
624 unsigned getPriority() const { return Priority; }
625
626 /// Retrieve the availability of this code completion result.
627 unsigned getAvailability() const { return Availability; }
628
629 /// Retrieve the number of annotations for this code completion result.
630 unsigned getAnnotationCount() const;
631
632 /// Retrieve the annotation string specified by \c AnnotationNr.
633 const char *getAnnotation(unsigned AnnotationNr) const;
634
635 /// Retrieve the name of the parent context.
636 StringRef getParentContextName() const {
637 return ParentName;
638 }
639
640 const char *getBriefComment() const {
641 return BriefComment;
642 }
643
644 /// Retrieve a string representation of the code completion string,
645 /// which is mainly useful for debugging.
646 std::string getAsString() const;
647};
648
649/// An allocator used specifically for the purpose of code completion.
650class CodeCompletionAllocator : public llvm::BumpPtrAllocator {
651public:
652 /// Copy the given string into this allocator.
653 const char *CopyString(const Twine &String);
654};
655
656/// Allocator for a cached set of global code completions.
657class GlobalCodeCompletionAllocator : public CodeCompletionAllocator {};
658
659class CodeCompletionTUInfo {
660 llvm::DenseMap<const DeclContext *, StringRef> ParentNames;
661 std::shared_ptr<GlobalCodeCompletionAllocator> AllocatorRef;
662
663public:
664 explicit CodeCompletionTUInfo(
665 std::shared_ptr<GlobalCodeCompletionAllocator> Allocator)
666 : AllocatorRef(std::move(Allocator)) {}
667
668 std::shared_ptr<GlobalCodeCompletionAllocator> getAllocatorRef() const {
669 return AllocatorRef;
670 }
671
672 CodeCompletionAllocator &getAllocator() const {
673 assert(AllocatorRef);
674 return *AllocatorRef;
675 }
676
677 StringRef getParentName(const DeclContext *DC);
678};
679
680} // namespace clang
681
682namespace clang {
683
684/// A builder class used to construct new code-completion strings.
685class CodeCompletionBuilder {
686public:
687 using Chunk = CodeCompletionString::Chunk;
688
689private:
690 CodeCompletionAllocator &Allocator;
691 CodeCompletionTUInfo &CCTUInfo;
692 unsigned Priority = 0;
693 CXAvailabilityKind Availability = CXAvailability_Available;
694 StringRef ParentName;
695 const char *BriefComment = nullptr;
696
697 /// The chunks stored in this string.
698 SmallVector<Chunk, 4> Chunks;
699
700 SmallVector<const char *, 2> Annotations;
701
702public:
703 CodeCompletionBuilder(CodeCompletionAllocator &Allocator,
704 CodeCompletionTUInfo &CCTUInfo)
705 : Allocator(Allocator), CCTUInfo(CCTUInfo) {}
706
707 CodeCompletionBuilder(CodeCompletionAllocator &Allocator,
708 CodeCompletionTUInfo &CCTUInfo,
709 unsigned Priority, CXAvailabilityKind Availability)
710 : Allocator(Allocator), CCTUInfo(CCTUInfo), Priority(Priority),
711 Availability(Availability) {}
712
713 /// Retrieve the allocator into which the code completion
714 /// strings should be allocated.
715 CodeCompletionAllocator &getAllocator() const { return Allocator; }
716
717 CodeCompletionTUInfo &getCodeCompletionTUInfo() const { return CCTUInfo; }
718
719 /// Take the resulting completion string.
720 ///
721 /// This operation can only be performed once.
722 CodeCompletionString *TakeString();
723
724 /// Add a new typed-text chunk.
725 void AddTypedTextChunk(const char *Text);
726
727 /// Add a new text chunk.
728 void AddTextChunk(const char *Text);
729
730 /// Add a new optional chunk.
731 void AddOptionalChunk(CodeCompletionString *Optional);
732
733 /// Add a new placeholder chunk.
734 void AddPlaceholderChunk(const char *Placeholder);
735
736 /// Add a new informative chunk.
737 void AddInformativeChunk(const char *Text);
738
739 /// Add a new result-type chunk.
740 void AddResultTypeChunk(const char *ResultType);
741
742 /// Add a new current-parameter chunk.
743 void AddCurrentParameterChunk(const char *CurrentParameter);
744
745 /// Add a new chunk.
746 void AddChunk(CodeCompletionString::ChunkKind CK, const char *Text = "");
747
748 void AddAnnotation(const char *A) { Annotations.push_back(Elt: A); }
749
750 /// Add the parent context information to this code completion.
751 void addParentContext(const DeclContext *DC);
752
753 const char *getBriefComment() const { return BriefComment; }
754 void addBriefComment(StringRef Comment);
755
756 StringRef getParentName() const { return ParentName; }
757};
758
759/// Captures a result of code completion.
760class CodeCompletionResult {
761public:
762 /// Describes the kind of result generated.
763 enum ResultKind {
764 /// Refers to a declaration.
765 RK_Declaration = 0,
766
767 /// Refers to a keyword or symbol.
768 RK_Keyword,
769
770 /// Refers to a macro.
771 RK_Macro,
772
773 /// Refers to a precomputed pattern.
774 RK_Pattern
775 };
776
777 /// When Kind == RK_Declaration or RK_Pattern, the declaration we are
778 /// referring to. In the latter case, the declaration might be NULL.
779 const NamedDecl *Declaration = nullptr;
780
781 union {
782 /// When Kind == RK_Keyword, the string representing the keyword
783 /// or symbol's spelling.
784 const char *Keyword;
785
786 /// When Kind == RK_Pattern, the code-completion string that
787 /// describes the completion text to insert.
788 CodeCompletionString *Pattern;
789
790 /// When Kind == RK_Macro, the identifier that refers to a macro.
791 const IdentifierInfo *Macro;
792 };
793
794 /// The priority of this particular code-completion result.
795 unsigned Priority;
796
797 /// Specifies which parameter (of a function, Objective-C method,
798 /// macro, etc.) we should start with when formatting the result.
799 unsigned StartParameter = 0;
800
801 /// The kind of result stored here.
802 ResultKind Kind;
803
804 /// The cursor kind that describes this result.
805 CXCursorKind CursorKind;
806
807 /// The availability of this result.
808 CXAvailabilityKind Availability = CXAvailability_Available;
809
810 /// Fix-its that *must* be applied before inserting the text for the
811 /// corresponding completion.
812 ///
813 /// By default, CodeCompletionBuilder only returns completions with empty
814 /// fix-its. Extra completions with non-empty fix-its should be explicitly
815 /// requested by setting CompletionOptions::IncludeFixIts.
816 ///
817 /// For the clients to be able to compute position of the cursor after
818 /// applying fix-its, the following conditions are guaranteed to hold for
819 /// RemoveRange of the stored fix-its:
820 /// - Ranges in the fix-its are guaranteed to never contain the completion
821 /// point (or identifier under completion point, if any) inside them, except
822 /// at the start or at the end of the range.
823 /// - If a fix-it range starts or ends with completion point (or starts or
824 /// ends after the identifier under completion point), it will contain at
825 /// least one character. It allows to unambiguously recompute completion
826 /// point after applying the fix-it.
827 ///
828 /// The intuition is that provided fix-its change code around the identifier
829 /// we complete, but are not allowed to touch the identifier itself or the
830 /// completion point. One example of completions with corrections are the ones
831 /// replacing '.' with '->' and vice versa:
832 ///
833 /// std::unique_ptr<std::vector<int>> vec_ptr;
834 /// In 'vec_ptr.^', one of the completions is 'push_back', it requires
835 /// replacing '.' with '->'.
836 /// In 'vec_ptr->^', one of the completions is 'release', it requires
837 /// replacing '->' with '.'.
838 std::vector<FixItHint> FixIts;
839
840 /// Whether this result is hidden by another name.
841 bool Hidden : 1;
842
843 /// Whether this is a class member from base class.
844 bool InBaseClass : 1;
845
846 /// Whether this result was found via lookup into a base class.
847 bool QualifierIsInformative : 1;
848
849 /// Whether this declaration is the beginning of a
850 /// nested-name-specifier and, therefore, should be followed by '::'.
851 bool StartsNestedNameSpecifier : 1;
852
853 /// Whether all parameters (of a function, Objective-C
854 /// method, etc.) should be considered "informative".
855 bool AllParametersAreInformative : 1;
856
857 /// Whether we're completing a declaration of the given entity,
858 /// rather than a use of that entity.
859 bool DeclaringEntity : 1;
860
861 /// When completing a function, whether it can be a call. This will usually be
862 /// true, but we have some heuristics, e.g. when a pointer to a non-static
863 /// member function is completed outside of that class' scope, it can never
864 /// be a call.
865 bool FunctionCanBeCall : 1;
866
867 /// If the result should have a nested-name-specifier, this is it.
868 /// When \c QualifierIsInformative, the nested-name-specifier is
869 /// informative rather than required.
870 NestedNameSpecifier *Qualifier = nullptr;
871
872 /// If this Decl was unshadowed by using declaration, this can store a
873 /// pointer to the UsingShadowDecl which was used in the unshadowing process.
874 /// This information can be used to uprank CodeCompletionResults / which have
875 /// corresponding `using decl::qualified::name;` nearby.
876 const UsingShadowDecl *ShadowDecl = nullptr;
877
878 /// If the result is RK_Macro, this can store the information about the macro
879 /// definition. This should be set in most cases but can be missing when
880 /// the macro has been undefined.
881 const MacroInfo *MacroDefInfo = nullptr;
882
883 /// Build a result that refers to a declaration.
884 CodeCompletionResult(const NamedDecl *Declaration, unsigned Priority,
885 NestedNameSpecifier *Qualifier = nullptr,
886 bool QualifierIsInformative = false,
887 bool Accessible = true,
888 std::vector<FixItHint> FixIts = std::vector<FixItHint>())
889 : Declaration(Declaration), Priority(Priority), Kind(RK_Declaration),
890 FixIts(std::move(FixIts)), Hidden(false), InBaseClass(false),
891 QualifierIsInformative(QualifierIsInformative),
892 StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
893 DeclaringEntity(false), FunctionCanBeCall(true), Qualifier(Qualifier) {
894 // FIXME: Add assert to check FixIts range requirements.
895 computeCursorKindAndAvailability(Accessible);
896 }
897
898 /// Build a result that refers to a keyword or symbol.
899 CodeCompletionResult(const char *Keyword, unsigned Priority = CCP_Keyword)
900 : Keyword(Keyword), Priority(Priority), Kind(RK_Keyword),
901 CursorKind(CXCursor_NotImplemented), Hidden(false), InBaseClass(false),
902 QualifierIsInformative(false), StartsNestedNameSpecifier(false),
903 AllParametersAreInformative(false), DeclaringEntity(false),
904 FunctionCanBeCall(true) {}
905
906 /// Build a result that refers to a macro.
907 CodeCompletionResult(const IdentifierInfo *Macro,
908 const MacroInfo *MI = nullptr,
909 unsigned Priority = CCP_Macro)
910 : Macro(Macro), Priority(Priority), Kind(RK_Macro),
911 CursorKind(CXCursor_MacroDefinition), Hidden(false), InBaseClass(false),
912 QualifierIsInformative(false), StartsNestedNameSpecifier(false),
913 AllParametersAreInformative(false), DeclaringEntity(false),
914 FunctionCanBeCall(true), MacroDefInfo(MI) {}
915
916 /// Build a result that refers to a pattern.
917 CodeCompletionResult(
918 CodeCompletionString *Pattern, unsigned Priority = CCP_CodePattern,
919 CXCursorKind CursorKind = CXCursor_NotImplemented,
920 CXAvailabilityKind Availability = CXAvailability_Available,
921 const NamedDecl *D = nullptr)
922 : Declaration(D), Pattern(Pattern), Priority(Priority), Kind(RK_Pattern),
923 CursorKind(CursorKind), Availability(Availability), Hidden(false),
924 InBaseClass(false), QualifierIsInformative(false),
925 StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
926 DeclaringEntity(false), FunctionCanBeCall(true) {}
927
928 /// Build a result that refers to a pattern with an associated
929 /// declaration.
930 CodeCompletionResult(CodeCompletionString *Pattern, const NamedDecl *D,
931 unsigned Priority)
932 : Declaration(D), Pattern(Pattern), Priority(Priority), Kind(RK_Pattern),
933 Hidden(false), InBaseClass(false), QualifierIsInformative(false),
934 StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
935 DeclaringEntity(false), FunctionCanBeCall(true) {
936 computeCursorKindAndAvailability();
937 }
938
939 /// Retrieve the declaration stored in this result. This might be nullptr if
940 /// Kind is RK_Pattern.
941 const NamedDecl *getDeclaration() const {
942 assert(((Kind == RK_Declaration) || (Kind == RK_Pattern)) &&
943 "Not a declaration or pattern result");
944 return Declaration;
945 }
946
947 /// Retrieve the keyword stored in this result.
948 const char *getKeyword() const {
949 assert(Kind == RK_Keyword && "Not a keyword result");
950 return Keyword;
951 }
952
953 /// Create a new code-completion string that describes how to insert
954 /// this result into a program.
955 ///
956 /// \param S The semantic analysis that created the result.
957 ///
958 /// \param Allocator The allocator that will be used to allocate the
959 /// string itself.
960 CodeCompletionString *CreateCodeCompletionString(Sema &S,
961 const CodeCompletionContext &CCContext,
962 CodeCompletionAllocator &Allocator,
963 CodeCompletionTUInfo &CCTUInfo,
964 bool IncludeBriefComments);
965 CodeCompletionString *CreateCodeCompletionString(ASTContext &Ctx,
966 Preprocessor &PP,
967 const CodeCompletionContext &CCContext,
968 CodeCompletionAllocator &Allocator,
969 CodeCompletionTUInfo &CCTUInfo,
970 bool IncludeBriefComments);
971 /// Creates a new code-completion string for the macro result. Similar to the
972 /// above overloads, except this only requires preprocessor information.
973 /// The result kind must be `RK_Macro`.
974 CodeCompletionString *
975 CreateCodeCompletionStringForMacro(Preprocessor &PP,
976 CodeCompletionAllocator &Allocator,
977 CodeCompletionTUInfo &CCTUInfo);
978
979 CodeCompletionString *createCodeCompletionStringForDecl(
980 Preprocessor &PP, ASTContext &Ctx, CodeCompletionBuilder &Result,
981 bool IncludeBriefComments, const CodeCompletionContext &CCContext,
982 PrintingPolicy &Policy);
983
984 CodeCompletionString *createCodeCompletionStringForOverride(
985 Preprocessor &PP, ASTContext &Ctx, CodeCompletionBuilder &Result,
986 bool IncludeBriefComments, const CodeCompletionContext &CCContext,
987 PrintingPolicy &Policy);
988
989 /// Retrieve the name that should be used to order a result.
990 ///
991 /// If the name needs to be constructed as a string, that string will be
992 /// saved into Saved and the returned StringRef will refer to it.
993 StringRef getOrderedName(std::string &Saved) const;
994
995private:
996 void computeCursorKindAndAvailability(bool Accessible = true);
997};
998
999bool operator<(const CodeCompletionResult &X, const CodeCompletionResult &Y);
1000
1001inline bool operator>(const CodeCompletionResult &X,
1002 const CodeCompletionResult &Y) {
1003 return Y < X;
1004}
1005
1006inline bool operator<=(const CodeCompletionResult &X,
1007 const CodeCompletionResult &Y) {
1008 return !(Y < X);
1009}
1010
1011inline bool operator>=(const CodeCompletionResult &X,
1012 const CodeCompletionResult &Y) {
1013 return !(X < Y);
1014}
1015
1016/// Abstract interface for a consumer of code-completion
1017/// information.
1018class CodeCompleteConsumer {
1019protected:
1020 const CodeCompleteOptions CodeCompleteOpts;
1021
1022public:
1023 class OverloadCandidate {
1024 public:
1025 /// Describes the type of overload candidate.
1026 enum CandidateKind {
1027 /// The candidate is a function declaration.
1028 CK_Function,
1029
1030 /// The candidate is a function template, arguments are being completed.
1031 CK_FunctionTemplate,
1032
1033 /// The "candidate" is actually a variable, expression, or block
1034 /// for which we only have a function prototype.
1035 CK_FunctionType,
1036
1037 /// The candidate is a variable or expression of function type
1038 /// for which we have the location of the prototype declaration.
1039 CK_FunctionProtoTypeLoc,
1040
1041 /// The candidate is a template, template arguments are being completed.
1042 CK_Template,
1043
1044 /// The candidate is aggregate initialization of a record type.
1045 CK_Aggregate,
1046 };
1047
1048 private:
1049 /// The kind of overload candidate.
1050 CandidateKind Kind;
1051
1052 union {
1053 /// The function overload candidate, available when
1054 /// Kind == CK_Function.
1055 FunctionDecl *Function;
1056
1057 /// The function template overload candidate, available when
1058 /// Kind == CK_FunctionTemplate.
1059 FunctionTemplateDecl *FunctionTemplate;
1060
1061 /// The function type that describes the entity being called,
1062 /// when Kind == CK_FunctionType.
1063 const FunctionType *Type;
1064
1065 /// The location of the function prototype that describes the entity being
1066 /// called, when Kind == CK_FunctionProtoTypeLoc.
1067 FunctionProtoTypeLoc ProtoTypeLoc;
1068
1069 /// The template overload candidate, available when
1070 /// Kind == CK_Template.
1071 const TemplateDecl *Template;
1072
1073 /// The class being aggregate-initialized,
1074 /// when Kind == CK_Aggregate
1075 const RecordDecl *AggregateType;
1076 };
1077
1078 public:
1079 OverloadCandidate(FunctionDecl *Function)
1080 : Kind(CK_Function), Function(Function) {
1081 assert(Function != nullptr);
1082 }
1083
1084 OverloadCandidate(FunctionTemplateDecl *FunctionTemplateDecl)
1085 : Kind(CK_FunctionTemplate), FunctionTemplate(FunctionTemplateDecl) {
1086 assert(FunctionTemplateDecl != nullptr);
1087 }
1088
1089 OverloadCandidate(const FunctionType *Type)
1090 : Kind(CK_FunctionType), Type(Type) {
1091 assert(Type != nullptr);
1092 }
1093
1094 OverloadCandidate(FunctionProtoTypeLoc Prototype)
1095 : Kind(CK_FunctionProtoTypeLoc), ProtoTypeLoc(Prototype) {
1096 assert(!Prototype.isNull());
1097 }
1098
1099 OverloadCandidate(const RecordDecl *Aggregate)
1100 : Kind(CK_Aggregate), AggregateType(Aggregate) {
1101 assert(Aggregate != nullptr);
1102 }
1103
1104 OverloadCandidate(const TemplateDecl *Template)
1105 : Kind(CK_Template), Template(Template) {}
1106
1107 /// Determine the kind of overload candidate.
1108 CandidateKind getKind() const { return Kind; }
1109
1110 /// Retrieve the function overload candidate or the templated
1111 /// function declaration for a function template.
1112 FunctionDecl *getFunction() const;
1113
1114 /// Retrieve the function template overload candidate.
1115 FunctionTemplateDecl *getFunctionTemplate() const {
1116 assert(getKind() == CK_FunctionTemplate && "Not a function template");
1117 return FunctionTemplate;
1118 }
1119
1120 /// Retrieve the function type of the entity, regardless of how the
1121 /// function is stored.
1122 const FunctionType *getFunctionType() const;
1123
1124 /// Retrieve the function ProtoTypeLoc candidate.
1125 /// This can be called for any Kind, but returns null for kinds
1126 /// other than CK_FunctionProtoTypeLoc.
1127 const FunctionProtoTypeLoc getFunctionProtoTypeLoc() const;
1128
1129 const TemplateDecl *getTemplate() const {
1130 assert(getKind() == CK_Template && "Not a template");
1131 return Template;
1132 }
1133
1134 /// Retrieve the aggregate type being initialized.
1135 const RecordDecl *getAggregate() const {
1136 assert(getKind() == CK_Aggregate);
1137 return AggregateType;
1138 }
1139
1140 /// Get the number of parameters in this signature.
1141 unsigned getNumParams() const;
1142
1143 /// Get the type of the Nth parameter.
1144 /// Returns null if the type is unknown or N is out of range.
1145 QualType getParamType(unsigned N) const;
1146
1147 /// Get the declaration of the Nth parameter.
1148 /// Returns null if the decl is unknown or N is out of range.
1149 const NamedDecl *getParamDecl(unsigned N) const;
1150
1151 /// Create a new code-completion string that describes the function
1152 /// signature of this overload candidate.
1153 CodeCompletionString *
1154 CreateSignatureString(unsigned CurrentArg, Sema &S,
1155 CodeCompletionAllocator &Allocator,
1156 CodeCompletionTUInfo &CCTUInfo,
1157 bool IncludeBriefComments, bool Braced) const;
1158 };
1159
1160 CodeCompleteConsumer(const CodeCompleteOptions &CodeCompleteOpts)
1161 : CodeCompleteOpts(CodeCompleteOpts) {}
1162
1163 /// Whether the code-completion consumer wants to see macros.
1164 bool includeMacros() const {
1165 return CodeCompleteOpts.IncludeMacros;
1166 }
1167
1168 /// Whether the code-completion consumer wants to see code patterns.
1169 bool includeCodePatterns() const {
1170 return CodeCompleteOpts.IncludeCodePatterns;
1171 }
1172
1173 /// Whether to include global (top-level) declaration results.
1174 bool includeGlobals() const { return CodeCompleteOpts.IncludeGlobals; }
1175
1176 /// Whether to include declarations in namespace contexts (including
1177 /// the global namespace). If this is false, `includeGlobals()` will be
1178 /// ignored.
1179 bool includeNamespaceLevelDecls() const {
1180 return CodeCompleteOpts.IncludeNamespaceLevelDecls;
1181 }
1182
1183 /// Whether to include brief documentation comments within the set of
1184 /// code completions returned.
1185 bool includeBriefComments() const {
1186 return CodeCompleteOpts.IncludeBriefComments;
1187 }
1188
1189 /// Whether to include completion items with small fix-its, e.g. change
1190 /// '.' to '->' on member access, etc.
1191 bool includeFixIts() const { return CodeCompleteOpts.IncludeFixIts; }
1192
1193 /// Hint whether to load data from the external AST in order to provide
1194 /// full results. If false, declarations from the preamble may be omitted.
1195 bool loadExternal() const {
1196 return CodeCompleteOpts.LoadExternal;
1197 }
1198
1199 /// Deregisters and destroys this code-completion consumer.
1200 virtual ~CodeCompleteConsumer();
1201
1202 /// \name Code-completion filtering
1203 /// Check if the result should be filtered out.
1204 virtual bool isResultFilteredOut(StringRef Filter,
1205 CodeCompletionResult Results) {
1206 return false;
1207 }
1208
1209 /// \name Code-completion callbacks
1210 //@{
1211 /// Process the finalized code-completion results.
1212 virtual void ProcessCodeCompleteResults(Sema &S,
1213 CodeCompletionContext Context,
1214 CodeCompletionResult *Results,
1215 unsigned NumResults) {}
1216
1217 /// \param S the semantic-analyzer object for which code-completion is being
1218 /// done.
1219 ///
1220 /// \param CurrentArg the index of the current argument.
1221 ///
1222 /// \param Candidates an array of overload candidates.
1223 ///
1224 /// \param NumCandidates the number of overload candidates
1225 ///
1226 /// \param OpenParLoc location of the opening parenthesis of the argument
1227 /// list.
1228 virtual void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
1229 OverloadCandidate *Candidates,
1230 unsigned NumCandidates,
1231 SourceLocation OpenParLoc,
1232 bool Braced) {}
1233 //@}
1234
1235 /// Retrieve the allocator that will be used to allocate
1236 /// code completion strings.
1237 virtual CodeCompletionAllocator &getAllocator() = 0;
1238
1239 virtual CodeCompletionTUInfo &getCodeCompletionTUInfo() = 0;
1240};
1241
1242/// Get the documentation comment used to produce
1243/// CodeCompletionString::BriefComment for RK_Declaration.
1244const RawComment *getCompletionComment(const ASTContext &Ctx,
1245 const NamedDecl *Decl);
1246
1247/// Get the documentation comment used to produce
1248/// CodeCompletionString::BriefComment for RK_Pattern.
1249const RawComment *getPatternCompletionComment(const ASTContext &Ctx,
1250 const NamedDecl *Decl);
1251
1252/// Get the documentation comment used to produce
1253/// CodeCompletionString::BriefComment for OverloadCandidate.
1254const RawComment *
1255getParameterComment(const ASTContext &Ctx,
1256 const CodeCompleteConsumer::OverloadCandidate &Result,
1257 unsigned ArgIndex);
1258
1259/// A simple code-completion consumer that prints the results it
1260/// receives in a simple format.
1261class PrintingCodeCompleteConsumer : public CodeCompleteConsumer {
1262 /// The raw output stream.
1263 raw_ostream &OS;
1264
1265 CodeCompletionTUInfo CCTUInfo;
1266
1267public:
1268 /// Create a new printing code-completion consumer that prints its
1269 /// results to the given raw output stream.
1270 PrintingCodeCompleteConsumer(const CodeCompleteOptions &CodeCompleteOpts,
1271 raw_ostream &OS)
1272 : CodeCompleteConsumer(CodeCompleteOpts), OS(OS),
1273 CCTUInfo(std::make_shared<GlobalCodeCompletionAllocator>()) {}
1274
1275 /// Prints the finalized code-completion results.
1276 void ProcessCodeCompleteResults(Sema &S, CodeCompletionContext Context,
1277 CodeCompletionResult *Results,
1278 unsigned NumResults) override;
1279
1280 void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
1281 OverloadCandidate *Candidates,
1282 unsigned NumCandidates,
1283 SourceLocation OpenParLoc,
1284 bool Braced) override;
1285
1286 bool isResultFilteredOut(StringRef Filter, CodeCompletionResult Results) override;
1287
1288 CodeCompletionAllocator &getAllocator() override {
1289 return CCTUInfo.getAllocator();
1290 }
1291
1292 CodeCompletionTUInfo &getCodeCompletionTUInfo() override { return CCTUInfo; }
1293};
1294
1295} // namespace clang
1296
1297#endif // LLVM_CLANG_SEMA_CODECOMPLETECONSUMER_H
1298

source code of clang/include/clang/Sema/CodeCompleteConsumer.h