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