• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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     /// An unknown context, in which we are recovering from a parsing
333     /// error and don't know which completions we should give.
334     CCC_Recovery
335   };
336 
337   using VisitedContextSet = llvm::SmallPtrSet<DeclContext *, 8>;
338 
339 private:
340   Kind CCKind;
341 
342   /// Indicates whether we are completing a name of a using declaration, e.g.
343   ///     using ^;
344   ///     using a::^;
345   bool IsUsingDeclaration;
346 
347   /// The type that would prefer to see at this point (e.g., the type
348   /// of an initializer or function parameter).
349   QualType PreferredType;
350 
351   /// The type of the base object in a member access expression.
352   QualType BaseType;
353 
354   /// The identifiers for Objective-C selector parts.
355   ArrayRef<IdentifierInfo *> SelIdents;
356 
357   /// The scope specifier that comes before the completion token e.g.
358   /// "a::b::"
359   llvm::Optional<CXXScopeSpec> ScopeSpecifier;
360 
361   /// A set of declaration contexts visited by Sema when doing lookup for
362   /// code completion.
363   VisitedContextSet VisitedContexts;
364 
365 public:
366   /// Construct a new code-completion context of the given kind.
CodeCompletionContext(Kind CCKind)367   CodeCompletionContext(Kind CCKind)
368       : CCKind(CCKind), IsUsingDeclaration(false), SelIdents(None) {}
369 
370   /// Construct a new code-completion context of the given kind.
371   CodeCompletionContext(Kind CCKind, QualType T,
372                         ArrayRef<IdentifierInfo *> SelIdents = None)
CCKind(CCKind)373       : CCKind(CCKind), IsUsingDeclaration(false), SelIdents(SelIdents) {
374     if (CCKind == CCC_DotMemberAccess || CCKind == CCC_ArrowMemberAccess ||
375         CCKind == CCC_ObjCPropertyAccess || CCKind == CCC_ObjCClassMessage ||
376         CCKind == CCC_ObjCInstanceMessage)
377       BaseType = T;
378     else
379       PreferredType = T;
380   }
381 
isUsingDeclaration()382   bool isUsingDeclaration() const { return IsUsingDeclaration; }
setIsUsingDeclaration(bool V)383   void setIsUsingDeclaration(bool V) { IsUsingDeclaration = V; }
384 
385   /// Retrieve the kind of code-completion context.
getKind()386   Kind getKind() const { return CCKind; }
387 
388   /// Retrieve the type that this expression would prefer to have, e.g.,
389   /// if the expression is a variable initializer or a function argument, the
390   /// type of the corresponding variable or function parameter.
getPreferredType()391   QualType getPreferredType() const { return PreferredType; }
setPreferredType(QualType T)392   void setPreferredType(QualType T) { PreferredType = T; }
393 
394   /// Retrieve the type of the base object in a member-access
395   /// expression.
getBaseType()396   QualType getBaseType() const { return BaseType; }
397 
398   /// Retrieve the Objective-C selector identifiers.
getSelIdents()399   ArrayRef<IdentifierInfo *> getSelIdents() const { return SelIdents; }
400 
401   /// Determines whether we want C++ constructors as results within this
402   /// context.
403   bool wantConstructorResults() const;
404 
405   /// Sets the scope specifier that comes before the completion token.
406   /// This is expected to be set in code completions on qualfied specifiers
407   /// (e.g. "a::b::").
setCXXScopeSpecifier(CXXScopeSpec SS)408   void setCXXScopeSpecifier(CXXScopeSpec SS) {
409     this->ScopeSpecifier = std::move(SS);
410   }
411 
412   /// Adds a visited context.
addVisitedContext(DeclContext * Ctx)413   void addVisitedContext(DeclContext *Ctx) {
414     VisitedContexts.insert(Ctx);
415   }
416 
417   /// Retrieves all visited contexts.
getVisitedContexts()418   const VisitedContextSet &getVisitedContexts() const {
419     return VisitedContexts;
420   }
421 
getCXXScopeSpecifier()422   llvm::Optional<const CXXScopeSpec *> getCXXScopeSpecifier() {
423     if (ScopeSpecifier)
424       return ScopeSpecifier.getPointer();
425     return llvm::None;
426   }
427 };
428 
429 /// Get string representation of \p Kind, useful for for debugging.
430 llvm::StringRef getCompletionKindString(CodeCompletionContext::Kind Kind);
431 
432 /// A "string" used to describe how code completion can
433 /// be performed for an entity.
434 ///
435 /// A code completion string typically shows how a particular entity can be
436 /// used. For example, the code completion string for a function would show
437 /// the syntax to call it, including the parentheses, placeholders for the
438 /// arguments, etc.
439 class CodeCompletionString {
440 public:
441   /// The different kinds of "chunks" that can occur within a code
442   /// completion string.
443   enum ChunkKind {
444     /// The piece of text that the user is expected to type to
445     /// match the code-completion string, typically a keyword or the name of a
446     /// declarator or macro.
447     CK_TypedText,
448 
449     /// A piece of text that should be placed in the buffer, e.g.,
450     /// parentheses or a comma in a function call.
451     CK_Text,
452 
453     /// A code completion string that is entirely optional. For example,
454     /// an optional code completion string that describes the default arguments
455     /// in a function call.
456     CK_Optional,
457 
458     /// A string that acts as a placeholder for, e.g., a function
459     /// call argument.
460     CK_Placeholder,
461 
462     /// A piece of text that describes something about the result but
463     /// should not be inserted into the buffer.
464     CK_Informative,
465     /// A piece of text that describes the type of an entity or, for
466     /// functions and methods, the return type.
467     CK_ResultType,
468 
469     /// A piece of text that describes the parameter that corresponds
470     /// to the code-completion location within a function call, message send,
471     /// macro invocation, etc.
472     CK_CurrentParameter,
473 
474     /// A left parenthesis ('(').
475     CK_LeftParen,
476 
477     /// A right parenthesis (')').
478     CK_RightParen,
479 
480     /// A left bracket ('[').
481     CK_LeftBracket,
482 
483     /// A right bracket (']').
484     CK_RightBracket,
485 
486     /// A left brace ('{').
487     CK_LeftBrace,
488 
489     /// A right brace ('}').
490     CK_RightBrace,
491 
492     /// A left angle bracket ('<').
493     CK_LeftAngle,
494 
495     /// A right angle bracket ('>').
496     CK_RightAngle,
497 
498     /// A comma separator (',').
499     CK_Comma,
500 
501     /// A colon (':').
502     CK_Colon,
503 
504     /// A semicolon (';').
505     CK_SemiColon,
506 
507     /// An '=' sign.
508     CK_Equal,
509 
510     /// Horizontal whitespace (' ').
511     CK_HorizontalSpace,
512 
513     /// Vertical whitespace ('\\n' or '\\r\\n', depending on the
514     /// platform).
515     CK_VerticalSpace
516   };
517 
518   /// One piece of the code completion string.
519   struct Chunk {
520     /// The kind of data stored in this piece of the code completion
521     /// string.
522     ChunkKind Kind = CK_Text;
523 
524     union {
525       /// The text string associated with a CK_Text, CK_Placeholder,
526       /// CK_Informative, or CK_Comma chunk.
527       /// The string is owned by the chunk and will be deallocated
528       /// (with delete[]) when the chunk is destroyed.
529       const char *Text;
530 
531       /// The code completion string associated with a CK_Optional chunk.
532       /// The optional code completion string is owned by the chunk, and will
533       /// be deallocated (with delete) when the chunk is destroyed.
534       CodeCompletionString *Optional;
535     };
536 
ChunkChunk537     Chunk() : Text(nullptr) {}
538 
539     explicit Chunk(ChunkKind Kind, const char *Text = "");
540 
541     /// Create a new text chunk.
542     static Chunk CreateText(const char *Text);
543 
544     /// Create a new optional chunk.
545     static Chunk CreateOptional(CodeCompletionString *Optional);
546 
547     /// Create a new placeholder chunk.
548     static Chunk CreatePlaceholder(const char *Placeholder);
549 
550     /// Create a new informative chunk.
551     static Chunk CreateInformative(const char *Informative);
552 
553     /// Create a new result type chunk.
554     static Chunk CreateResultType(const char *ResultType);
555 
556     /// Create a new current-parameter chunk.
557     static Chunk CreateCurrentParameter(const char *CurrentParameter);
558   };
559 
560 private:
561   friend class CodeCompletionBuilder;
562   friend class CodeCompletionResult;
563 
564   /// The number of chunks stored in this string.
565   unsigned NumChunks : 16;
566 
567   /// The number of annotations for this code-completion result.
568   unsigned NumAnnotations : 16;
569 
570   /// The priority of this code-completion string.
571   unsigned Priority : 16;
572 
573   /// The availability of this code-completion result.
574   unsigned Availability : 2;
575 
576   /// The name of the parent context.
577   StringRef ParentName;
578 
579   /// A brief documentation comment attached to the declaration of
580   /// entity being completed by this result.
581   const char *BriefComment;
582 
583   CodeCompletionString(const Chunk *Chunks, unsigned NumChunks,
584                        unsigned Priority, CXAvailabilityKind Availability,
585                        const char **Annotations, unsigned NumAnnotations,
586                        StringRef ParentName,
587                        const char *BriefComment);
588   ~CodeCompletionString() = default;
589 
590 public:
591   CodeCompletionString(const CodeCompletionString &) = delete;
592   CodeCompletionString &operator=(const CodeCompletionString &) = delete;
593 
594   using iterator = const Chunk *;
595 
begin()596   iterator begin() const { return reinterpret_cast<const Chunk *>(this + 1); }
end()597   iterator end() const { return begin() + NumChunks; }
empty()598   bool empty() const { return NumChunks == 0; }
size()599   unsigned size() const { return NumChunks; }
600 
601   const Chunk &operator[](unsigned I) const {
602     assert(I < size() && "Chunk index out-of-range");
603     return begin()[I];
604   }
605 
606   /// Returns the text in the TypedText chunk.
607   const char *getTypedText() const;
608 
609   /// Retrieve the priority of this code completion result.
getPriority()610   unsigned getPriority() const { return Priority; }
611 
612   /// Retrieve the availability of this code completion result.
getAvailability()613   unsigned getAvailability() const { return Availability; }
614 
615   /// Retrieve the number of annotations for this code completion result.
616   unsigned getAnnotationCount() const;
617 
618   /// Retrieve the annotation string specified by \c AnnotationNr.
619   const char *getAnnotation(unsigned AnnotationNr) const;
620 
621   /// Retrieve the name of the parent context.
getParentContextName()622   StringRef getParentContextName() const {
623     return ParentName;
624   }
625 
getBriefComment()626   const char *getBriefComment() const {
627     return BriefComment;
628   }
629 
630   /// Retrieve a string representation of the code completion string,
631   /// which is mainly useful for debugging.
632   std::string getAsString() const;
633 };
634 
635 /// An allocator used specifically for the purpose of code completion.
636 class CodeCompletionAllocator : public llvm::BumpPtrAllocator {
637 public:
638   /// Copy the given string into this allocator.
639   const char *CopyString(const Twine &String);
640 };
641 
642 /// Allocator for a cached set of global code completions.
643 class GlobalCodeCompletionAllocator : public CodeCompletionAllocator {};
644 
645 class CodeCompletionTUInfo {
646   llvm::DenseMap<const DeclContext *, StringRef> ParentNames;
647   std::shared_ptr<GlobalCodeCompletionAllocator> AllocatorRef;
648 
649 public:
CodeCompletionTUInfo(std::shared_ptr<GlobalCodeCompletionAllocator> Allocator)650   explicit CodeCompletionTUInfo(
651       std::shared_ptr<GlobalCodeCompletionAllocator> Allocator)
652       : AllocatorRef(std::move(Allocator)) {}
653 
getAllocatorRef()654   std::shared_ptr<GlobalCodeCompletionAllocator> getAllocatorRef() const {
655     return AllocatorRef;
656   }
657 
getAllocator()658   CodeCompletionAllocator &getAllocator() const {
659     assert(AllocatorRef);
660     return *AllocatorRef;
661   }
662 
663   StringRef getParentName(const DeclContext *DC);
664 };
665 
666 } // namespace clang
667 
668 namespace clang {
669 
670 /// A builder class used to construct new code-completion strings.
671 class CodeCompletionBuilder {
672 public:
673   using Chunk = CodeCompletionString::Chunk;
674 
675 private:
676   CodeCompletionAllocator &Allocator;
677   CodeCompletionTUInfo &CCTUInfo;
678   unsigned Priority = 0;
679   CXAvailabilityKind Availability = CXAvailability_Available;
680   StringRef ParentName;
681   const char *BriefComment = nullptr;
682 
683   /// The chunks stored in this string.
684   SmallVector<Chunk, 4> Chunks;
685 
686   SmallVector<const char *, 2> Annotations;
687 
688 public:
CodeCompletionBuilder(CodeCompletionAllocator & Allocator,CodeCompletionTUInfo & CCTUInfo)689   CodeCompletionBuilder(CodeCompletionAllocator &Allocator,
690                         CodeCompletionTUInfo &CCTUInfo)
691       : Allocator(Allocator), CCTUInfo(CCTUInfo) {}
692 
CodeCompletionBuilder(CodeCompletionAllocator & Allocator,CodeCompletionTUInfo & CCTUInfo,unsigned Priority,CXAvailabilityKind Availability)693   CodeCompletionBuilder(CodeCompletionAllocator &Allocator,
694                         CodeCompletionTUInfo &CCTUInfo,
695                         unsigned Priority, CXAvailabilityKind Availability)
696       : Allocator(Allocator), CCTUInfo(CCTUInfo), Priority(Priority),
697         Availability(Availability) {}
698 
699   /// Retrieve the allocator into which the code completion
700   /// strings should be allocated.
getAllocator()701   CodeCompletionAllocator &getAllocator() const { return Allocator; }
702 
getCodeCompletionTUInfo()703   CodeCompletionTUInfo &getCodeCompletionTUInfo() const { return CCTUInfo; }
704 
705   /// Take the resulting completion string.
706   ///
707   /// This operation can only be performed once.
708   CodeCompletionString *TakeString();
709 
710   /// Add a new typed-text chunk.
711   void AddTypedTextChunk(const char *Text);
712 
713   /// Add a new text chunk.
714   void AddTextChunk(const char *Text);
715 
716   /// Add a new optional chunk.
717   void AddOptionalChunk(CodeCompletionString *Optional);
718 
719   /// Add a new placeholder chunk.
720   void AddPlaceholderChunk(const char *Placeholder);
721 
722   /// Add a new informative chunk.
723   void AddInformativeChunk(const char *Text);
724 
725   /// Add a new result-type chunk.
726   void AddResultTypeChunk(const char *ResultType);
727 
728   /// Add a new current-parameter chunk.
729   void AddCurrentParameterChunk(const char *CurrentParameter);
730 
731   /// Add a new chunk.
732   void AddChunk(CodeCompletionString::ChunkKind CK, const char *Text = "");
733 
AddAnnotation(const char * A)734   void AddAnnotation(const char *A) { Annotations.push_back(A); }
735 
736   /// Add the parent context information to this code completion.
737   void addParentContext(const DeclContext *DC);
738 
getBriefComment()739   const char *getBriefComment() const { return BriefComment; }
740   void addBriefComment(StringRef Comment);
741 
getParentName()742   StringRef getParentName() const { return ParentName; }
743 };
744 
745 /// Captures a result of code completion.
746 class CodeCompletionResult {
747 public:
748   /// Describes the kind of result generated.
749   enum ResultKind {
750     /// Refers to a declaration.
751     RK_Declaration = 0,
752 
753     /// Refers to a keyword or symbol.
754     RK_Keyword,
755 
756     /// Refers to a macro.
757     RK_Macro,
758 
759     /// Refers to a precomputed pattern.
760     RK_Pattern
761   };
762 
763   /// When Kind == RK_Declaration or RK_Pattern, the declaration we are
764   /// referring to. In the latter case, the declaration might be NULL.
765   const NamedDecl *Declaration = nullptr;
766 
767   union {
768     /// When Kind == RK_Keyword, the string representing the keyword
769     /// or symbol's spelling.
770     const char *Keyword;
771 
772     /// When Kind == RK_Pattern, the code-completion string that
773     /// describes the completion text to insert.
774     CodeCompletionString *Pattern;
775 
776     /// When Kind == RK_Macro, the identifier that refers to a macro.
777     const IdentifierInfo *Macro;
778   };
779 
780   /// The priority of this particular code-completion result.
781   unsigned Priority;
782 
783   /// Specifies which parameter (of a function, Objective-C method,
784   /// macro, etc.) we should start with when formatting the result.
785   unsigned StartParameter = 0;
786 
787   /// The kind of result stored here.
788   ResultKind Kind;
789 
790   /// The cursor kind that describes this result.
791   CXCursorKind CursorKind;
792 
793   /// The availability of this result.
794   CXAvailabilityKind Availability = CXAvailability_Available;
795 
796   /// Fix-its that *must* be applied before inserting the text for the
797   /// corresponding completion.
798   ///
799   /// By default, CodeCompletionBuilder only returns completions with empty
800   /// fix-its. Extra completions with non-empty fix-its should be explicitly
801   /// requested by setting CompletionOptions::IncludeFixIts.
802   ///
803   /// For the clients to be able to compute position of the cursor after
804   /// applying fix-its, the following conditions are guaranteed to hold for
805   /// RemoveRange of the stored fix-its:
806   ///  - Ranges in the fix-its are guaranteed to never contain the completion
807   ///  point (or identifier under completion point, if any) inside them, except
808   ///  at the start or at the end of the range.
809   ///  - If a fix-it range starts or ends with completion point (or starts or
810   ///  ends after the identifier under completion point), it will contain at
811   ///  least one character. It allows to unambiguously recompute completion
812   ///  point after applying the fix-it.
813   ///
814   /// The intuition is that provided fix-its change code around the identifier
815   /// we complete, but are not allowed to touch the identifier itself or the
816   /// completion point. One example of completions with corrections are the ones
817   /// replacing '.' with '->' and vice versa:
818   ///
819   /// std::unique_ptr<std::vector<int>> vec_ptr;
820   /// In 'vec_ptr.^', one of the completions is 'push_back', it requires
821   /// replacing '.' with '->'.
822   /// In 'vec_ptr->^', one of the completions is 'release', it requires
823   /// replacing '->' with '.'.
824   std::vector<FixItHint> FixIts;
825 
826   /// Whether this result is hidden by another name.
827   bool Hidden : 1;
828 
829   /// Whether this is a class member from base class.
830   bool InBaseClass : 1;
831 
832   /// Whether this result was found via lookup into a base class.
833   bool QualifierIsInformative : 1;
834 
835   /// Whether this declaration is the beginning of a
836   /// nested-name-specifier and, therefore, should be followed by '::'.
837   bool StartsNestedNameSpecifier : 1;
838 
839   /// Whether all parameters (of a function, Objective-C
840   /// method, etc.) should be considered "informative".
841   bool AllParametersAreInformative : 1;
842 
843   /// Whether we're completing a declaration of the given entity,
844   /// rather than a use of that entity.
845   bool DeclaringEntity : 1;
846 
847   /// If the result should have a nested-name-specifier, this is it.
848   /// When \c QualifierIsInformative, the nested-name-specifier is
849   /// informative rather than required.
850   NestedNameSpecifier *Qualifier = nullptr;
851 
852   /// If this Decl was unshadowed by using declaration, this can store a
853   /// pointer to the UsingShadowDecl which was used in the unshadowing process.
854   /// This information can be used to uprank CodeCompletionResults / which have
855   /// corresponding `using decl::qualified::name;` nearby.
856   const UsingShadowDecl *ShadowDecl = nullptr;
857 
858   /// If the result is RK_Macro, this can store the information about the macro
859   /// definition. This should be set in most cases but can be missing when
860   /// the macro has been undefined.
861   const MacroInfo *MacroDefInfo = nullptr;
862 
863   /// Build a result that refers to a declaration.
864   CodeCompletionResult(const NamedDecl *Declaration, unsigned Priority,
865                        NestedNameSpecifier *Qualifier = nullptr,
866                        bool QualifierIsInformative = false,
867                        bool Accessible = true,
868                        std::vector<FixItHint> FixIts = std::vector<FixItHint>())
Declaration(Declaration)869       : Declaration(Declaration), Priority(Priority), Kind(RK_Declaration),
870         FixIts(std::move(FixIts)), Hidden(false), InBaseClass(false),
871         QualifierIsInformative(QualifierIsInformative),
872         StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
873         DeclaringEntity(false), Qualifier(Qualifier) {
874     // FIXME: Add assert to check FixIts range requirements.
875     computeCursorKindAndAvailability(Accessible);
876   }
877 
878   /// Build a result that refers to a keyword or symbol.
879   CodeCompletionResult(const char *Keyword, unsigned Priority = CCP_Keyword)
Keyword(Keyword)880       : Keyword(Keyword), Priority(Priority), Kind(RK_Keyword),
881         CursorKind(CXCursor_NotImplemented), Hidden(false), InBaseClass(false),
882         QualifierIsInformative(false), StartsNestedNameSpecifier(false),
883         AllParametersAreInformative(false), DeclaringEntity(false) {}
884 
885   /// Build a result that refers to a macro.
886   CodeCompletionResult(const IdentifierInfo *Macro,
887                        const MacroInfo *MI = nullptr,
888                        unsigned Priority = CCP_Macro)
Macro(Macro)889       : Macro(Macro), Priority(Priority), Kind(RK_Macro),
890         CursorKind(CXCursor_MacroDefinition), Hidden(false), InBaseClass(false),
891         QualifierIsInformative(false), StartsNestedNameSpecifier(false),
892         AllParametersAreInformative(false), DeclaringEntity(false),
893         MacroDefInfo(MI) {}
894 
895   /// Build a result that refers to a pattern.
896   CodeCompletionResult(
897       CodeCompletionString *Pattern, unsigned Priority = CCP_CodePattern,
898       CXCursorKind CursorKind = CXCursor_NotImplemented,
899       CXAvailabilityKind Availability = CXAvailability_Available,
900       const NamedDecl *D = nullptr)
Declaration(D)901       : Declaration(D), Pattern(Pattern), Priority(Priority), Kind(RK_Pattern),
902         CursorKind(CursorKind), Availability(Availability), Hidden(false),
903         InBaseClass(false), QualifierIsInformative(false),
904         StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
905         DeclaringEntity(false) {}
906 
907   /// Build a result that refers to a pattern with an associated
908   /// declaration.
CodeCompletionResult(CodeCompletionString * Pattern,const NamedDecl * D,unsigned Priority)909   CodeCompletionResult(CodeCompletionString *Pattern, const NamedDecl *D,
910                        unsigned Priority)
911       : Declaration(D), Pattern(Pattern), Priority(Priority), Kind(RK_Pattern),
912         Hidden(false), InBaseClass(false), QualifierIsInformative(false),
913         StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
914         DeclaringEntity(false) {
915     computeCursorKindAndAvailability();
916   }
917 
918   /// Retrieve the declaration stored in this result. This might be nullptr if
919   /// Kind is RK_Pattern.
getDeclaration()920   const NamedDecl *getDeclaration() const {
921     assert(((Kind == RK_Declaration) || (Kind == RK_Pattern)) &&
922            "Not a declaration or pattern result");
923     return Declaration;
924   }
925 
926   /// Retrieve the keyword stored in this result.
getKeyword()927   const char *getKeyword() const {
928     assert(Kind == RK_Keyword && "Not a keyword result");
929     return Keyword;
930   }
931 
932   /// Create a new code-completion string that describes how to insert
933   /// this result into a program.
934   ///
935   /// \param S The semantic analysis that created the result.
936   ///
937   /// \param Allocator The allocator that will be used to allocate the
938   /// string itself.
939   CodeCompletionString *CreateCodeCompletionString(Sema &S,
940                                          const CodeCompletionContext &CCContext,
941                                            CodeCompletionAllocator &Allocator,
942                                            CodeCompletionTUInfo &CCTUInfo,
943                                            bool IncludeBriefComments);
944   CodeCompletionString *CreateCodeCompletionString(ASTContext &Ctx,
945                                                    Preprocessor &PP,
946                                          const CodeCompletionContext &CCContext,
947                                            CodeCompletionAllocator &Allocator,
948                                            CodeCompletionTUInfo &CCTUInfo,
949                                            bool IncludeBriefComments);
950   /// Creates a new code-completion string for the macro result. Similar to the
951   /// above overloads, except this only requires preprocessor information.
952   /// The result kind must be `RK_Macro`.
953   CodeCompletionString *
954   CreateCodeCompletionStringForMacro(Preprocessor &PP,
955                                      CodeCompletionAllocator &Allocator,
956                                      CodeCompletionTUInfo &CCTUInfo);
957 
958   CodeCompletionString *createCodeCompletionStringForDecl(
959       Preprocessor &PP, ASTContext &Ctx, CodeCompletionBuilder &Result,
960       bool IncludeBriefComments, const CodeCompletionContext &CCContext,
961       PrintingPolicy &Policy);
962 
963   CodeCompletionString *createCodeCompletionStringForOverride(
964       Preprocessor &PP, ASTContext &Ctx, CodeCompletionBuilder &Result,
965       bool IncludeBriefComments, const CodeCompletionContext &CCContext,
966       PrintingPolicy &Policy);
967 
968   /// Retrieve the name that should be used to order a result.
969   ///
970   /// If the name needs to be constructed as a string, that string will be
971   /// saved into Saved and the returned StringRef will refer to it.
972   StringRef getOrderedName(std::string &Saved) const;
973 
974 private:
975   void computeCursorKindAndAvailability(bool Accessible = true);
976 };
977 
978 bool operator<(const CodeCompletionResult &X, const CodeCompletionResult &Y);
979 
980 inline bool operator>(const CodeCompletionResult &X,
981                       const CodeCompletionResult &Y) {
982   return Y < X;
983 }
984 
985 inline bool operator<=(const CodeCompletionResult &X,
986                       const CodeCompletionResult &Y) {
987   return !(Y < X);
988 }
989 
990 inline bool operator>=(const CodeCompletionResult &X,
991                        const CodeCompletionResult &Y) {
992   return !(X < Y);
993 }
994 
995 /// Abstract interface for a consumer of code-completion
996 /// information.
997 class CodeCompleteConsumer {
998 protected:
999   const CodeCompleteOptions CodeCompleteOpts;
1000 
1001 public:
1002   class OverloadCandidate {
1003   public:
1004     /// Describes the type of overload candidate.
1005     enum CandidateKind {
1006       /// The candidate is a function declaration.
1007       CK_Function,
1008 
1009       /// The candidate is a function template.
1010       CK_FunctionTemplate,
1011 
1012       /// The "candidate" is actually a variable, expression, or block
1013       /// for which we only have a function prototype.
1014       CK_FunctionType
1015     };
1016 
1017   private:
1018     /// The kind of overload candidate.
1019     CandidateKind Kind;
1020 
1021     union {
1022       /// The function overload candidate, available when
1023       /// Kind == CK_Function.
1024       FunctionDecl *Function;
1025 
1026       /// The function template overload candidate, available when
1027       /// Kind == CK_FunctionTemplate.
1028       FunctionTemplateDecl *FunctionTemplate;
1029 
1030       /// The function type that describes the entity being called,
1031       /// when Kind == CK_FunctionType.
1032       const FunctionType *Type;
1033     };
1034 
1035   public:
OverloadCandidate(FunctionDecl * Function)1036     OverloadCandidate(FunctionDecl *Function)
1037         : Kind(CK_Function), Function(Function) {}
1038 
OverloadCandidate(FunctionTemplateDecl * FunctionTemplateDecl)1039     OverloadCandidate(FunctionTemplateDecl *FunctionTemplateDecl)
1040         : Kind(CK_FunctionTemplate), FunctionTemplate(FunctionTemplateDecl) {}
1041 
OverloadCandidate(const FunctionType * Type)1042     OverloadCandidate(const FunctionType *Type)
1043         : Kind(CK_FunctionType), Type(Type) {}
1044 
1045     /// Determine the kind of overload candidate.
getKind()1046     CandidateKind getKind() const { return Kind; }
1047 
1048     /// Retrieve the function overload candidate or the templated
1049     /// function declaration for a function template.
1050     FunctionDecl *getFunction() const;
1051 
1052     /// Retrieve the function template overload candidate.
getFunctionTemplate()1053     FunctionTemplateDecl *getFunctionTemplate() const {
1054       assert(getKind() == CK_FunctionTemplate && "Not a function template");
1055       return FunctionTemplate;
1056     }
1057 
1058     /// Retrieve the function type of the entity, regardless of how the
1059     /// function is stored.
1060     const FunctionType *getFunctionType() const;
1061 
1062     /// Create a new code-completion string that describes the function
1063     /// signature of this overload candidate.
1064     CodeCompletionString *CreateSignatureString(unsigned CurrentArg,
1065                                                 Sema &S,
1066                                       CodeCompletionAllocator &Allocator,
1067                                       CodeCompletionTUInfo &CCTUInfo,
1068                                       bool IncludeBriefComments) const;
1069   };
1070 
CodeCompleteConsumer(const CodeCompleteOptions & CodeCompleteOpts)1071   CodeCompleteConsumer(const CodeCompleteOptions &CodeCompleteOpts)
1072       : CodeCompleteOpts(CodeCompleteOpts) {}
1073 
1074   /// Whether the code-completion consumer wants to see macros.
includeMacros()1075   bool includeMacros() const {
1076     return CodeCompleteOpts.IncludeMacros;
1077   }
1078 
1079   /// Whether the code-completion consumer wants to see code patterns.
includeCodePatterns()1080   bool includeCodePatterns() const {
1081     return CodeCompleteOpts.IncludeCodePatterns;
1082   }
1083 
1084   /// Whether to include global (top-level) declaration results.
includeGlobals()1085   bool includeGlobals() const { return CodeCompleteOpts.IncludeGlobals; }
1086 
1087   /// Whether to include declarations in namespace contexts (including
1088   /// the global namespace). If this is false, `includeGlobals()` will be
1089   /// ignored.
includeNamespaceLevelDecls()1090   bool includeNamespaceLevelDecls() const {
1091     return CodeCompleteOpts.IncludeNamespaceLevelDecls;
1092   }
1093 
1094   /// Whether to include brief documentation comments within the set of
1095   /// code completions returned.
includeBriefComments()1096   bool includeBriefComments() const {
1097     return CodeCompleteOpts.IncludeBriefComments;
1098   }
1099 
1100   /// Whether to include completion items with small fix-its, e.g. change
1101   /// '.' to '->' on member access, etc.
includeFixIts()1102   bool includeFixIts() const { return CodeCompleteOpts.IncludeFixIts; }
1103 
1104   /// Hint whether to load data from the external AST in order to provide
1105   /// full results. If false, declarations from the preamble may be omitted.
loadExternal()1106   bool loadExternal() const {
1107     return CodeCompleteOpts.LoadExternal;
1108   }
1109 
1110   /// Deregisters and destroys this code-completion consumer.
1111   virtual ~CodeCompleteConsumer();
1112 
1113   /// \name Code-completion filtering
1114   /// Check if the result should be filtered out.
isResultFilteredOut(StringRef Filter,CodeCompletionResult Results)1115   virtual bool isResultFilteredOut(StringRef Filter,
1116                                    CodeCompletionResult Results) {
1117     return false;
1118   }
1119 
1120   /// \name Code-completion callbacks
1121   //@{
1122   /// Process the finalized code-completion results.
ProcessCodeCompleteResults(Sema & S,CodeCompletionContext Context,CodeCompletionResult * Results,unsigned NumResults)1123   virtual void ProcessCodeCompleteResults(Sema &S,
1124                                           CodeCompletionContext Context,
1125                                           CodeCompletionResult *Results,
1126                                           unsigned NumResults) {}
1127 
1128   /// \param S the semantic-analyzer object for which code-completion is being
1129   /// done.
1130   ///
1131   /// \param CurrentArg the index of the current argument.
1132   ///
1133   /// \param Candidates an array of overload candidates.
1134   ///
1135   /// \param NumCandidates the number of overload candidates
1136   ///
1137   /// \param OpenParLoc location of the opening parenthesis of the argument
1138   ///        list.
ProcessOverloadCandidates(Sema & S,unsigned CurrentArg,OverloadCandidate * Candidates,unsigned NumCandidates,SourceLocation OpenParLoc)1139   virtual void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
1140                                          OverloadCandidate *Candidates,
1141                                          unsigned NumCandidates,
1142                                          SourceLocation OpenParLoc) {}
1143   //@}
1144 
1145   /// Retrieve the allocator that will be used to allocate
1146   /// code completion strings.
1147   virtual CodeCompletionAllocator &getAllocator() = 0;
1148 
1149   virtual CodeCompletionTUInfo &getCodeCompletionTUInfo() = 0;
1150 };
1151 
1152 /// Get the documentation comment used to produce
1153 /// CodeCompletionString::BriefComment for RK_Declaration.
1154 const RawComment *getCompletionComment(const ASTContext &Ctx,
1155                                        const NamedDecl *Decl);
1156 
1157 /// Get the documentation comment used to produce
1158 /// CodeCompletionString::BriefComment for RK_Pattern.
1159 const RawComment *getPatternCompletionComment(const ASTContext &Ctx,
1160                                               const NamedDecl *Decl);
1161 
1162 /// Get the documentation comment used to produce
1163 /// CodeCompletionString::BriefComment for OverloadCandidate.
1164 const RawComment *
1165 getParameterComment(const ASTContext &Ctx,
1166                     const CodeCompleteConsumer::OverloadCandidate &Result,
1167                     unsigned ArgIndex);
1168 
1169 /// A simple code-completion consumer that prints the results it
1170 /// receives in a simple format.
1171 class PrintingCodeCompleteConsumer : public CodeCompleteConsumer {
1172   /// The raw output stream.
1173   raw_ostream &OS;
1174 
1175   CodeCompletionTUInfo CCTUInfo;
1176 
1177 public:
1178   /// Create a new printing code-completion consumer that prints its
1179   /// results to the given raw output stream.
PrintingCodeCompleteConsumer(const CodeCompleteOptions & CodeCompleteOpts,raw_ostream & OS)1180   PrintingCodeCompleteConsumer(const CodeCompleteOptions &CodeCompleteOpts,
1181                                raw_ostream &OS)
1182       : CodeCompleteConsumer(CodeCompleteOpts), OS(OS),
1183         CCTUInfo(std::make_shared<GlobalCodeCompletionAllocator>()) {}
1184 
1185   /// Prints the finalized code-completion results.
1186   void ProcessCodeCompleteResults(Sema &S, CodeCompletionContext Context,
1187                                   CodeCompletionResult *Results,
1188                                   unsigned NumResults) override;
1189 
1190   void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
1191                                  OverloadCandidate *Candidates,
1192                                  unsigned NumCandidates,
1193                                  SourceLocation OpenParLoc) override;
1194 
1195   bool isResultFilteredOut(StringRef Filter, CodeCompletionResult Results) override;
1196 
getAllocator()1197   CodeCompletionAllocator &getAllocator() override {
1198     return CCTUInfo.getAllocator();
1199   }
1200 
getCodeCompletionTUInfo()1201   CodeCompletionTUInfo &getCodeCompletionTUInfo() override { return CCTUInfo; }
1202 };
1203 
1204 } // namespace clang
1205 
1206 #endif // LLVM_CLANG_SEMA_CODECOMPLETECONSUMER_H
1207