xref: /freebsd/contrib/llvm-project/clang/include/clang/Sema/CodeCompleteConsumer.h (revision 725a9f47324d42037db93c27ceb40d4956872f3e)
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 
35 namespace clang {
36 
37 class ASTContext;
38 class Decl;
39 class DeclContext;
40 class FunctionDecl;
41 class FunctionTemplateDecl;
42 class IdentifierInfo;
43 class LangOptions;
44 class NamedDecl;
45 class NestedNameSpecifier;
46 class Preprocessor;
47 class RawComment;
48 class Sema;
49 class UsingShadowDecl;
50 
51 /// Default priority values for code-completion results based
52 /// on their kind.
53 enum {
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.
104 enum {
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.
135 enum {
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.
148 enum 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.
161 SimplifiedTypeClass 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.
165 QualType 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.
176 unsigned getMacroUsagePriority(StringRef MacroName,
177                                const LangOptions &LangOpts,
178                                bool PreferredTypeIsPointer = false);
179 
180 /// Determine the libclang cursor kind associated with the given
181 /// declaration.
182 CXCursorKind 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.
186 class CodeCompletionContext {
187 public:
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 
349 private:
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 
375 public:
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(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.
440 llvm::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.
449 class CodeCompletionString {
450 public:
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 
570 private:
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   unsigned Availability : 2;
585 
586   /// The name of the parent context.
587   StringRef ParentName;
588 
589   /// A brief documentation comment attached to the declaration of
590   /// entity being completed by this result.
591   const char *BriefComment;
592 
593   CodeCompletionString(const Chunk *Chunks, unsigned NumChunks,
594                        unsigned Priority, CXAvailabilityKind Availability,
595                        const char **Annotations, unsigned NumAnnotations,
596                        StringRef ParentName,
597                        const char *BriefComment);
598   ~CodeCompletionString() = default;
599 
600 public:
601   CodeCompletionString(const CodeCompletionString &) = delete;
602   CodeCompletionString &operator=(const CodeCompletionString &) = delete;
603 
604   using iterator = const Chunk *;
605 
606   iterator begin() const { return reinterpret_cast<const Chunk *>(this + 1); }
607   iterator end() const { return begin() + NumChunks; }
608   bool empty() const { return NumChunks == 0; }
609   unsigned size() const { return NumChunks; }
610 
611   const Chunk &operator[](unsigned I) const {
612     assert(I < size() && "Chunk index out-of-range");
613     return begin()[I];
614   }
615 
616   /// Returns the text in the first TypedText chunk.
617   const char *getTypedText() const;
618 
619   /// Returns the combined text from all TypedText chunks.
620   std::string getAllTypedText() const;
621 
622   /// Retrieve the priority of this code completion result.
623   unsigned getPriority() const { return Priority; }
624 
625   /// Retrieve the availability of this code completion result.
626   unsigned getAvailability() const { return Availability; }
627 
628   /// Retrieve the number of annotations for this code completion result.
629   unsigned getAnnotationCount() const;
630 
631   /// Retrieve the annotation string specified by \c AnnotationNr.
632   const char *getAnnotation(unsigned AnnotationNr) const;
633 
634   /// Retrieve the name of the parent context.
635   StringRef getParentContextName() const {
636     return ParentName;
637   }
638 
639   const char *getBriefComment() const {
640     return BriefComment;
641   }
642 
643   /// Retrieve a string representation of the code completion string,
644   /// which is mainly useful for debugging.
645   std::string getAsString() const;
646 };
647 
648 /// An allocator used specifically for the purpose of code completion.
649 class CodeCompletionAllocator : public llvm::BumpPtrAllocator {
650 public:
651   /// Copy the given string into this allocator.
652   const char *CopyString(const Twine &String);
653 };
654 
655 /// Allocator for a cached set of global code completions.
656 class GlobalCodeCompletionAllocator : public CodeCompletionAllocator {};
657 
658 class CodeCompletionTUInfo {
659   llvm::DenseMap<const DeclContext *, StringRef> ParentNames;
660   std::shared_ptr<GlobalCodeCompletionAllocator> AllocatorRef;
661 
662 public:
663   explicit CodeCompletionTUInfo(
664       std::shared_ptr<GlobalCodeCompletionAllocator> Allocator)
665       : AllocatorRef(std::move(Allocator)) {}
666 
667   std::shared_ptr<GlobalCodeCompletionAllocator> getAllocatorRef() const {
668     return AllocatorRef;
669   }
670 
671   CodeCompletionAllocator &getAllocator() const {
672     assert(AllocatorRef);
673     return *AllocatorRef;
674   }
675 
676   StringRef getParentName(const DeclContext *DC);
677 };
678 
679 } // namespace clang
680 
681 namespace clang {
682 
683 /// A builder class used to construct new code-completion strings.
684 class CodeCompletionBuilder {
685 public:
686   using Chunk = CodeCompletionString::Chunk;
687 
688 private:
689   CodeCompletionAllocator &Allocator;
690   CodeCompletionTUInfo &CCTUInfo;
691   unsigned Priority = 0;
692   CXAvailabilityKind Availability = CXAvailability_Available;
693   StringRef ParentName;
694   const char *BriefComment = nullptr;
695 
696   /// The chunks stored in this string.
697   SmallVector<Chunk, 4> Chunks;
698 
699   SmallVector<const char *, 2> Annotations;
700 
701 public:
702   CodeCompletionBuilder(CodeCompletionAllocator &Allocator,
703                         CodeCompletionTUInfo &CCTUInfo)
704       : Allocator(Allocator), CCTUInfo(CCTUInfo) {}
705 
706   CodeCompletionBuilder(CodeCompletionAllocator &Allocator,
707                         CodeCompletionTUInfo &CCTUInfo,
708                         unsigned Priority, CXAvailabilityKind Availability)
709       : Allocator(Allocator), CCTUInfo(CCTUInfo), Priority(Priority),
710         Availability(Availability) {}
711 
712   /// Retrieve the allocator into which the code completion
713   /// strings should be allocated.
714   CodeCompletionAllocator &getAllocator() const { return Allocator; }
715 
716   CodeCompletionTUInfo &getCodeCompletionTUInfo() const { return CCTUInfo; }
717 
718   /// Take the resulting completion string.
719   ///
720   /// This operation can only be performed once.
721   CodeCompletionString *TakeString();
722 
723   /// Add a new typed-text chunk.
724   void AddTypedTextChunk(const char *Text);
725 
726   /// Add a new text chunk.
727   void AddTextChunk(const char *Text);
728 
729   /// Add a new optional chunk.
730   void AddOptionalChunk(CodeCompletionString *Optional);
731 
732   /// Add a new placeholder chunk.
733   void AddPlaceholderChunk(const char *Placeholder);
734 
735   /// Add a new informative chunk.
736   void AddInformativeChunk(const char *Text);
737 
738   /// Add a new result-type chunk.
739   void AddResultTypeChunk(const char *ResultType);
740 
741   /// Add a new current-parameter chunk.
742   void AddCurrentParameterChunk(const char *CurrentParameter);
743 
744   /// Add a new chunk.
745   void AddChunk(CodeCompletionString::ChunkKind CK, const char *Text = "");
746 
747   void AddAnnotation(const char *A) { Annotations.push_back(A); }
748 
749   /// Add the parent context information to this code completion.
750   void addParentContext(const DeclContext *DC);
751 
752   const char *getBriefComment() const { return BriefComment; }
753   void addBriefComment(StringRef Comment);
754 
755   StringRef getParentName() const { return ParentName; }
756 };
757 
758 /// Captures a result of code completion.
759 class CodeCompletionResult {
760 public:
761   /// Describes the kind of result generated.
762   enum ResultKind {
763     /// Refers to a declaration.
764     RK_Declaration = 0,
765 
766     /// Refers to a keyword or symbol.
767     RK_Keyword,
768 
769     /// Refers to a macro.
770     RK_Macro,
771 
772     /// Refers to a precomputed pattern.
773     RK_Pattern
774   };
775 
776   /// When Kind == RK_Declaration or RK_Pattern, the declaration we are
777   /// referring to. In the latter case, the declaration might be NULL.
778   const NamedDecl *Declaration = nullptr;
779 
780   union {
781     /// When Kind == RK_Keyword, the string representing the keyword
782     /// or symbol's spelling.
783     const char *Keyword;
784 
785     /// When Kind == RK_Pattern, the code-completion string that
786     /// describes the completion text to insert.
787     CodeCompletionString *Pattern;
788 
789     /// When Kind == RK_Macro, the identifier that refers to a macro.
790     const IdentifierInfo *Macro;
791   };
792 
793   /// The priority of this particular code-completion result.
794   unsigned Priority;
795 
796   /// Specifies which parameter (of a function, Objective-C method,
797   /// macro, etc.) we should start with when formatting the result.
798   unsigned StartParameter = 0;
799 
800   /// The kind of result stored here.
801   ResultKind Kind;
802 
803   /// The cursor kind that describes this result.
804   CXCursorKind CursorKind;
805 
806   /// The availability of this result.
807   CXAvailabilityKind Availability = CXAvailability_Available;
808 
809   /// Fix-its that *must* be applied before inserting the text for the
810   /// corresponding completion.
811   ///
812   /// By default, CodeCompletionBuilder only returns completions with empty
813   /// fix-its. Extra completions with non-empty fix-its should be explicitly
814   /// requested by setting CompletionOptions::IncludeFixIts.
815   ///
816   /// For the clients to be able to compute position of the cursor after
817   /// applying fix-its, the following conditions are guaranteed to hold for
818   /// RemoveRange of the stored fix-its:
819   ///  - Ranges in the fix-its are guaranteed to never contain the completion
820   ///  point (or identifier under completion point, if any) inside them, except
821   ///  at the start or at the end of the range.
822   ///  - If a fix-it range starts or ends with completion point (or starts or
823   ///  ends after the identifier under completion point), it will contain at
824   ///  least one character. It allows to unambiguously recompute completion
825   ///  point after applying the fix-it.
826   ///
827   /// The intuition is that provided fix-its change code around the identifier
828   /// we complete, but are not allowed to touch the identifier itself or the
829   /// completion point. One example of completions with corrections are the ones
830   /// replacing '.' with '->' and vice versa:
831   ///
832   /// std::unique_ptr<std::vector<int>> vec_ptr;
833   /// In 'vec_ptr.^', one of the completions is 'push_back', it requires
834   /// replacing '.' with '->'.
835   /// In 'vec_ptr->^', one of the completions is 'release', it requires
836   /// replacing '->' with '.'.
837   std::vector<FixItHint> FixIts;
838 
839   /// Whether this result is hidden by another name.
840   bool Hidden : 1;
841 
842   /// Whether this is a class member from base class.
843   bool InBaseClass : 1;
844 
845   /// Whether this result was found via lookup into a base class.
846   bool QualifierIsInformative : 1;
847 
848   /// Whether this declaration is the beginning of a
849   /// nested-name-specifier and, therefore, should be followed by '::'.
850   bool StartsNestedNameSpecifier : 1;
851 
852   /// Whether all parameters (of a function, Objective-C
853   /// method, etc.) should be considered "informative".
854   bool AllParametersAreInformative : 1;
855 
856   /// Whether we're completing a declaration of the given entity,
857   /// rather than a use of that entity.
858   bool DeclaringEntity : 1;
859 
860   /// When completing a function, whether it can be a call. This will usually be
861   /// true, but we have some heuristics, e.g. when a pointer to a non-static
862   /// member function is completed outside of that class' scope, it can never
863   /// be a call.
864   bool FunctionCanBeCall : 1;
865 
866   /// If the result should have a nested-name-specifier, this is it.
867   /// When \c QualifierIsInformative, the nested-name-specifier is
868   /// informative rather than required.
869   NestedNameSpecifier *Qualifier = nullptr;
870 
871   /// If this Decl was unshadowed by using declaration, this can store a
872   /// pointer to the UsingShadowDecl which was used in the unshadowing process.
873   /// This information can be used to uprank CodeCompletionResults / which have
874   /// corresponding `using decl::qualified::name;` nearby.
875   const UsingShadowDecl *ShadowDecl = nullptr;
876 
877   /// If the result is RK_Macro, this can store the information about the macro
878   /// definition. This should be set in most cases but can be missing when
879   /// the macro has been undefined.
880   const MacroInfo *MacroDefInfo = nullptr;
881 
882   /// Build a result that refers to a declaration.
883   CodeCompletionResult(const NamedDecl *Declaration, unsigned Priority,
884                        NestedNameSpecifier *Qualifier = nullptr,
885                        bool QualifierIsInformative = false,
886                        bool Accessible = true,
887                        std::vector<FixItHint> FixIts = std::vector<FixItHint>())
888       : Declaration(Declaration), Priority(Priority), Kind(RK_Declaration),
889         FixIts(std::move(FixIts)), Hidden(false), InBaseClass(false),
890         QualifierIsInformative(QualifierIsInformative),
891         StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
892         DeclaringEntity(false), FunctionCanBeCall(true), Qualifier(Qualifier) {
893     // FIXME: Add assert to check FixIts range requirements.
894     computeCursorKindAndAvailability(Accessible);
895   }
896 
897   /// Build a result that refers to a keyword or symbol.
898   CodeCompletionResult(const char *Keyword, unsigned Priority = CCP_Keyword)
899       : Keyword(Keyword), Priority(Priority), Kind(RK_Keyword),
900         CursorKind(CXCursor_NotImplemented), Hidden(false), InBaseClass(false),
901         QualifierIsInformative(false), StartsNestedNameSpecifier(false),
902         AllParametersAreInformative(false), DeclaringEntity(false),
903         FunctionCanBeCall(true) {}
904 
905   /// Build a result that refers to a macro.
906   CodeCompletionResult(const IdentifierInfo *Macro,
907                        const MacroInfo *MI = nullptr,
908                        unsigned Priority = CCP_Macro)
909       : Macro(Macro), Priority(Priority), Kind(RK_Macro),
910         CursorKind(CXCursor_MacroDefinition), Hidden(false), InBaseClass(false),
911         QualifierIsInformative(false), StartsNestedNameSpecifier(false),
912         AllParametersAreInformative(false), DeclaringEntity(false),
913         FunctionCanBeCall(true), MacroDefInfo(MI) {}
914 
915   /// Build a result that refers to a pattern.
916   CodeCompletionResult(
917       CodeCompletionString *Pattern, unsigned Priority = CCP_CodePattern,
918       CXCursorKind CursorKind = CXCursor_NotImplemented,
919       CXAvailabilityKind Availability = CXAvailability_Available,
920       const NamedDecl *D = nullptr)
921       : Declaration(D), Pattern(Pattern), Priority(Priority), Kind(RK_Pattern),
922         CursorKind(CursorKind), Availability(Availability), Hidden(false),
923         InBaseClass(false), QualifierIsInformative(false),
924         StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
925         DeclaringEntity(false), FunctionCanBeCall(true) {}
926 
927   /// Build a result that refers to a pattern with an associated
928   /// declaration.
929   CodeCompletionResult(CodeCompletionString *Pattern, const NamedDecl *D,
930                        unsigned Priority)
931       : Declaration(D), Pattern(Pattern), Priority(Priority), Kind(RK_Pattern),
932         Hidden(false), InBaseClass(false), QualifierIsInformative(false),
933         StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
934         DeclaringEntity(false), FunctionCanBeCall(true) {
935     computeCursorKindAndAvailability();
936   }
937 
938   /// Retrieve the declaration stored in this result. This might be nullptr if
939   /// Kind is RK_Pattern.
940   const NamedDecl *getDeclaration() const {
941     assert(((Kind == RK_Declaration) || (Kind == RK_Pattern)) &&
942            "Not a declaration or pattern result");
943     return Declaration;
944   }
945 
946   /// Retrieve the keyword stored in this result.
947   const char *getKeyword() const {
948     assert(Kind == RK_Keyword && "Not a keyword result");
949     return Keyword;
950   }
951 
952   /// Create a new code-completion string that describes how to insert
953   /// this result into a program.
954   ///
955   /// \param S The semantic analysis that created the result.
956   ///
957   /// \param Allocator The allocator that will be used to allocate the
958   /// string itself.
959   CodeCompletionString *CreateCodeCompletionString(Sema &S,
960                                          const CodeCompletionContext &CCContext,
961                                            CodeCompletionAllocator &Allocator,
962                                            CodeCompletionTUInfo &CCTUInfo,
963                                            bool IncludeBriefComments);
964   CodeCompletionString *CreateCodeCompletionString(ASTContext &Ctx,
965                                                    Preprocessor &PP,
966                                          const CodeCompletionContext &CCContext,
967                                            CodeCompletionAllocator &Allocator,
968                                            CodeCompletionTUInfo &CCTUInfo,
969                                            bool IncludeBriefComments);
970   /// Creates a new code-completion string for the macro result. Similar to the
971   /// above overloads, except this only requires preprocessor information.
972   /// The result kind must be `RK_Macro`.
973   CodeCompletionString *
974   CreateCodeCompletionStringForMacro(Preprocessor &PP,
975                                      CodeCompletionAllocator &Allocator,
976                                      CodeCompletionTUInfo &CCTUInfo);
977 
978   CodeCompletionString *createCodeCompletionStringForDecl(
979       Preprocessor &PP, ASTContext &Ctx, CodeCompletionBuilder &Result,
980       bool IncludeBriefComments, const CodeCompletionContext &CCContext,
981       PrintingPolicy &Policy);
982 
983   CodeCompletionString *createCodeCompletionStringForOverride(
984       Preprocessor &PP, ASTContext &Ctx, CodeCompletionBuilder &Result,
985       bool IncludeBriefComments, const CodeCompletionContext &CCContext,
986       PrintingPolicy &Policy);
987 
988   /// Retrieve the name that should be used to order a result.
989   ///
990   /// If the name needs to be constructed as a string, that string will be
991   /// saved into Saved and the returned StringRef will refer to it.
992   StringRef getOrderedName(std::string &Saved) const;
993 
994 private:
995   void computeCursorKindAndAvailability(bool Accessible = true);
996 };
997 
998 bool operator<(const CodeCompletionResult &X, const CodeCompletionResult &Y);
999 
1000 inline bool operator>(const CodeCompletionResult &X,
1001                       const CodeCompletionResult &Y) {
1002   return Y < X;
1003 }
1004 
1005 inline bool operator<=(const CodeCompletionResult &X,
1006                       const CodeCompletionResult &Y) {
1007   return !(Y < X);
1008 }
1009 
1010 inline bool operator>=(const CodeCompletionResult &X,
1011                        const CodeCompletionResult &Y) {
1012   return !(X < Y);
1013 }
1014 
1015 /// Abstract interface for a consumer of code-completion
1016 /// information.
1017 class CodeCompleteConsumer {
1018 protected:
1019   const CodeCompleteOptions CodeCompleteOpts;
1020 
1021 public:
1022   class OverloadCandidate {
1023   public:
1024     /// Describes the type of overload candidate.
1025     enum CandidateKind {
1026       /// The candidate is a function declaration.
1027       CK_Function,
1028 
1029       /// The candidate is a function template, arguments are being completed.
1030       CK_FunctionTemplate,
1031 
1032       /// The "candidate" is actually a variable, expression, or block
1033       /// for which we only have a function prototype.
1034       CK_FunctionType,
1035 
1036       /// The candidate is a variable or expression of function type
1037       /// for which we have the location of the prototype declaration.
1038       CK_FunctionProtoTypeLoc,
1039 
1040       /// The candidate is a template, template arguments are being completed.
1041       CK_Template,
1042 
1043       /// The candidate is aggregate initialization of a record type.
1044       CK_Aggregate,
1045     };
1046 
1047   private:
1048     /// The kind of overload candidate.
1049     CandidateKind Kind;
1050 
1051     union {
1052       /// The function overload candidate, available when
1053       /// Kind == CK_Function.
1054       FunctionDecl *Function;
1055 
1056       /// The function template overload candidate, available when
1057       /// Kind == CK_FunctionTemplate.
1058       FunctionTemplateDecl *FunctionTemplate;
1059 
1060       /// The function type that describes the entity being called,
1061       /// when Kind == CK_FunctionType.
1062       const FunctionType *Type;
1063 
1064       /// The location of the function prototype that describes the entity being
1065       /// called, when Kind == CK_FunctionProtoTypeLoc.
1066       FunctionProtoTypeLoc ProtoTypeLoc;
1067 
1068       /// The template overload candidate, available when
1069       /// Kind == CK_Template.
1070       const TemplateDecl *Template;
1071 
1072       /// The class being aggregate-initialized,
1073       /// when Kind == CK_Aggregate
1074       const RecordDecl *AggregateType;
1075     };
1076 
1077   public:
1078     OverloadCandidate(FunctionDecl *Function)
1079         : Kind(CK_Function), Function(Function) {
1080       assert(Function != nullptr);
1081     }
1082 
1083     OverloadCandidate(FunctionTemplateDecl *FunctionTemplateDecl)
1084         : Kind(CK_FunctionTemplate), FunctionTemplate(FunctionTemplateDecl) {
1085       assert(FunctionTemplateDecl != nullptr);
1086     }
1087 
1088     OverloadCandidate(const FunctionType *Type)
1089         : Kind(CK_FunctionType), Type(Type) {
1090       assert(Type != nullptr);
1091     }
1092 
1093     OverloadCandidate(FunctionProtoTypeLoc Prototype)
1094         : Kind(CK_FunctionProtoTypeLoc), ProtoTypeLoc(Prototype) {
1095       assert(!Prototype.isNull());
1096     }
1097 
1098     OverloadCandidate(const RecordDecl *Aggregate)
1099         : Kind(CK_Aggregate), AggregateType(Aggregate) {
1100       assert(Aggregate != nullptr);
1101     }
1102 
1103     OverloadCandidate(const TemplateDecl *Template)
1104         : Kind(CK_Template), Template(Template) {}
1105 
1106     /// Determine the kind of overload candidate.
1107     CandidateKind getKind() const { return Kind; }
1108 
1109     /// Retrieve the function overload candidate or the templated
1110     /// function declaration for a function template.
1111     FunctionDecl *getFunction() const;
1112 
1113     /// Retrieve the function template overload candidate.
1114     FunctionTemplateDecl *getFunctionTemplate() const {
1115       assert(getKind() == CK_FunctionTemplate && "Not a function template");
1116       return FunctionTemplate;
1117     }
1118 
1119     /// Retrieve the function type of the entity, regardless of how the
1120     /// function is stored.
1121     const FunctionType *getFunctionType() const;
1122 
1123     /// Retrieve the function ProtoTypeLoc candidate.
1124     /// This can be called for any Kind, but returns null for kinds
1125     /// other than CK_FunctionProtoTypeLoc.
1126     const FunctionProtoTypeLoc getFunctionProtoTypeLoc() const;
1127 
1128     const TemplateDecl *getTemplate() const {
1129       assert(getKind() == CK_Template && "Not a template");
1130       return Template;
1131     }
1132 
1133     /// Retrieve the aggregate type being initialized.
1134     const RecordDecl *getAggregate() const {
1135       assert(getKind() == CK_Aggregate);
1136       return AggregateType;
1137     }
1138 
1139     /// Get the number of parameters in this signature.
1140     unsigned getNumParams() const;
1141 
1142     /// Get the type of the Nth parameter.
1143     /// Returns null if the type is unknown or N is out of range.
1144     QualType getParamType(unsigned N) const;
1145 
1146     /// Get the declaration of the Nth parameter.
1147     /// Returns null if the decl is unknown or N is out of range.
1148     const NamedDecl *getParamDecl(unsigned N) const;
1149 
1150     /// Create a new code-completion string that describes the function
1151     /// signature of this overload candidate.
1152     CodeCompletionString *
1153     CreateSignatureString(unsigned CurrentArg, Sema &S,
1154                           CodeCompletionAllocator &Allocator,
1155                           CodeCompletionTUInfo &CCTUInfo,
1156                           bool IncludeBriefComments, bool Braced) const;
1157   };
1158 
1159   CodeCompleteConsumer(const CodeCompleteOptions &CodeCompleteOpts)
1160       : CodeCompleteOpts(CodeCompleteOpts) {}
1161 
1162   /// Whether the code-completion consumer wants to see macros.
1163   bool includeMacros() const {
1164     return CodeCompleteOpts.IncludeMacros;
1165   }
1166 
1167   /// Whether the code-completion consumer wants to see code patterns.
1168   bool includeCodePatterns() const {
1169     return CodeCompleteOpts.IncludeCodePatterns;
1170   }
1171 
1172   /// Whether to include global (top-level) declaration results.
1173   bool includeGlobals() const { return CodeCompleteOpts.IncludeGlobals; }
1174 
1175   /// Whether to include declarations in namespace contexts (including
1176   /// the global namespace). If this is false, `includeGlobals()` will be
1177   /// ignored.
1178   bool includeNamespaceLevelDecls() const {
1179     return CodeCompleteOpts.IncludeNamespaceLevelDecls;
1180   }
1181 
1182   /// Whether to include brief documentation comments within the set of
1183   /// code completions returned.
1184   bool includeBriefComments() const {
1185     return CodeCompleteOpts.IncludeBriefComments;
1186   }
1187 
1188   /// Whether to include completion items with small fix-its, e.g. change
1189   /// '.' to '->' on member access, etc.
1190   bool includeFixIts() const { return CodeCompleteOpts.IncludeFixIts; }
1191 
1192   /// Hint whether to load data from the external AST in order to provide
1193   /// full results. If false, declarations from the preamble may be omitted.
1194   bool loadExternal() const {
1195     return CodeCompleteOpts.LoadExternal;
1196   }
1197 
1198   /// Deregisters and destroys this code-completion consumer.
1199   virtual ~CodeCompleteConsumer();
1200 
1201   /// \name Code-completion filtering
1202   /// Check if the result should be filtered out.
1203   virtual bool isResultFilteredOut(StringRef Filter,
1204                                    CodeCompletionResult Results) {
1205     return false;
1206   }
1207 
1208   /// \name Code-completion callbacks
1209   //@{
1210   /// Process the finalized code-completion results.
1211   virtual void ProcessCodeCompleteResults(Sema &S,
1212                                           CodeCompletionContext Context,
1213                                           CodeCompletionResult *Results,
1214                                           unsigned NumResults) {}
1215 
1216   /// \param S the semantic-analyzer object for which code-completion is being
1217   /// done.
1218   ///
1219   /// \param CurrentArg the index of the current argument.
1220   ///
1221   /// \param Candidates an array of overload candidates.
1222   ///
1223   /// \param NumCandidates the number of overload candidates
1224   ///
1225   /// \param OpenParLoc location of the opening parenthesis of the argument
1226   ///        list.
1227   virtual void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
1228                                          OverloadCandidate *Candidates,
1229                                          unsigned NumCandidates,
1230                                          SourceLocation OpenParLoc,
1231                                          bool Braced) {}
1232   //@}
1233 
1234   /// Retrieve the allocator that will be used to allocate
1235   /// code completion strings.
1236   virtual CodeCompletionAllocator &getAllocator() = 0;
1237 
1238   virtual CodeCompletionTUInfo &getCodeCompletionTUInfo() = 0;
1239 };
1240 
1241 /// Get the documentation comment used to produce
1242 /// CodeCompletionString::BriefComment for RK_Declaration.
1243 const RawComment *getCompletionComment(const ASTContext &Ctx,
1244                                        const NamedDecl *Decl);
1245 
1246 /// Get the documentation comment used to produce
1247 /// CodeCompletionString::BriefComment for RK_Pattern.
1248 const RawComment *getPatternCompletionComment(const ASTContext &Ctx,
1249                                               const NamedDecl *Decl);
1250 
1251 /// Get the documentation comment used to produce
1252 /// CodeCompletionString::BriefComment for OverloadCandidate.
1253 const RawComment *
1254 getParameterComment(const ASTContext &Ctx,
1255                     const CodeCompleteConsumer::OverloadCandidate &Result,
1256                     unsigned ArgIndex);
1257 
1258 /// A simple code-completion consumer that prints the results it
1259 /// receives in a simple format.
1260 class PrintingCodeCompleteConsumer : public CodeCompleteConsumer {
1261   /// The raw output stream.
1262   raw_ostream &OS;
1263 
1264   CodeCompletionTUInfo CCTUInfo;
1265 
1266 public:
1267   /// Create a new printing code-completion consumer that prints its
1268   /// results to the given raw output stream.
1269   PrintingCodeCompleteConsumer(const CodeCompleteOptions &CodeCompleteOpts,
1270                                raw_ostream &OS)
1271       : CodeCompleteConsumer(CodeCompleteOpts), OS(OS),
1272         CCTUInfo(std::make_shared<GlobalCodeCompletionAllocator>()) {}
1273 
1274   /// Prints the finalized code-completion results.
1275   void ProcessCodeCompleteResults(Sema &S, CodeCompletionContext Context,
1276                                   CodeCompletionResult *Results,
1277                                   unsigned NumResults) override;
1278 
1279   void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
1280                                  OverloadCandidate *Candidates,
1281                                  unsigned NumCandidates,
1282                                  SourceLocation OpenParLoc,
1283                                  bool Braced) override;
1284 
1285   bool isResultFilteredOut(StringRef Filter, CodeCompletionResult Results) override;
1286 
1287   CodeCompletionAllocator &getAllocator() override {
1288     return CCTUInfo.getAllocator();
1289   }
1290 
1291   CodeCompletionTUInfo &getCodeCompletionTUInfo() override { return CCTUInfo; }
1292 };
1293 
1294 } // namespace clang
1295 
1296 #endif // LLVM_CLANG_SEMA_CODECOMPLETECONSUMER_H
1297