CodeCompleteConsumer.h revision 360784 
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
36namespace clang {
37
38class ASTContext;
39class Decl;
40class DeclContext;
41class FunctionDecl;
42class FunctionTemplateDecl;
43class IdentifierInfo;
44class LangOptions;
45class NamedDecl;
46class NestedNameSpecifier;
47class Preprocessor;
48class RawComment;
49class Sema;
50class UsingShadowDecl;
51
52/// Default priority values for code-completion results based
53/// on their kind.
54enum {
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.
105enum {
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.
136enum {
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.
149enum 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.
162SimplifiedTypeClass 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.
166QualType 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.
177unsigned getMacroUsagePriority(StringRef MacroName,
178                               const LangOptions &LangOpts,
179                               bool PreferredTypeIsPointer = false);
180
181/// Determine the libclang cursor kind associated with the given
182/// declaration.
183CXCursorKind 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.
187class CodeCompletionContext {
188public:
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
339private:
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
365public:
366  /// Construct a new code-completion context of the given kind.
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)
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
382  bool isUsingDeclaration() const { return IsUsingDeclaration; }
383  void setIsUsingDeclaration(bool V) { IsUsingDeclaration = V; }
384
385  /// Retrieve the kind of code-completion context.
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.
391  QualType getPreferredType() const { return PreferredType; }
392  void setPreferredType(QualType T) { PreferredType = T; }
393
394  /// Retrieve the type of the base object in a member-access
395  /// expression.
396  QualType getBaseType() const { return BaseType; }
397
398  /// Retrieve the Objective-C selector identifiers.
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::").
408  void setCXXScopeSpecifier(CXXScopeSpec SS) {
409    this->ScopeSpecifier = std::move(SS);
410  }
411
412  /// Adds a visited context.
413  void addVisitedContext(DeclContext *Ctx) {
414    VisitedContexts.insert(Ctx);
415  }
416
417  /// Retrieves all visited contexts.
418  const VisitedContextSet &getVisitedContexts() const {
419    return VisitedContexts;
420  }
421
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.
430llvm::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.
439class CodeCompletionString {
440public:
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
537    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
560private:
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
590public:
591  CodeCompletionString(const CodeCompletionString &) = delete;
592  CodeCompletionString &operator=(const CodeCompletionString &) = delete;
593
594  using iterator = const Chunk *;
595
596  iterator begin() const { return reinterpret_cast<const Chunk *>(this + 1); }
597  iterator end() const { return begin() + NumChunks; }
598  bool empty() const { return NumChunks == 0; }
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.
610  unsigned getPriority() const { return Priority; }
611
612  /// Retrieve the availability of this code completion result.
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.
622  StringRef getParentContextName() const {
623    return ParentName;
624  }
625
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.
636class CodeCompletionAllocator : public llvm::BumpPtrAllocator {
637public:
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.
643class GlobalCodeCompletionAllocator : public CodeCompletionAllocator {};
644
645class CodeCompletionTUInfo {
646  llvm::DenseMap<const DeclContext *, StringRef> ParentNames;
647  std::shared_ptr<GlobalCodeCompletionAllocator> AllocatorRef;
648
649public:
650  explicit CodeCompletionTUInfo(
651      std::shared_ptr<GlobalCodeCompletionAllocator> Allocator)
652      : AllocatorRef(std::move(Allocator)) {}
653
654  std::shared_ptr<GlobalCodeCompletionAllocator> getAllocatorRef() const {
655    return AllocatorRef;
656  }
657
658  CodeCompletionAllocator &getAllocator() const {
659    assert(AllocatorRef);
660    return *AllocatorRef;
661  }
662
663  StringRef getParentName(const DeclContext *DC);
664};
665
666} // namespace clang
667
668namespace clang {
669
670/// A builder class used to construct new code-completion strings.
671class CodeCompletionBuilder {
672public:
673  using Chunk = CodeCompletionString::Chunk;
674
675private:
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
688public:
689  CodeCompletionBuilder(CodeCompletionAllocator &Allocator,
690                        CodeCompletionTUInfo &CCTUInfo)
691      : Allocator(Allocator), CCTUInfo(CCTUInfo) {}
692
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.
701  CodeCompletionAllocator &getAllocator() const { return Allocator; }
702
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
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
739  const char *getBriefComment() const { return BriefComment; }
740  void addBriefComment(StringRef Comment);
741
742  StringRef getParentName() const { return ParentName; }
743};
744
745/// Captures a result of code completion.
746class CodeCompletionResult {
747public:
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>())
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)
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)
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)
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.
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.
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.
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
974private:
975  void computeCursorKindAndAvailability(bool Accessible = true);
976};
977
978bool operator<(const CodeCompletionResult &X, const CodeCompletionResult &Y);
979
980inline bool operator>(const CodeCompletionResult &X,
981                      const CodeCompletionResult &Y) {
982  return Y < X;
983}
984
985inline bool operator<=(const CodeCompletionResult &X,
986                      const CodeCompletionResult &Y) {
987  return !(Y < X);
988}
989
990inline bool operator>=(const CodeCompletionResult &X,
991                       const CodeCompletionResult &Y) {
992  return !(X < Y);
993}
994
995raw_ostream &operator<<(raw_ostream &OS,
996                              const CodeCompletionString &CCS);
997
998/// Abstract interface for a consumer of code-completion
999/// information.
1000class CodeCompleteConsumer {
1001protected:
1002  const CodeCompleteOptions CodeCompleteOpts;
1003
1004public:
1005  class OverloadCandidate {
1006  public:
1007    /// Describes the type of overload candidate.
1008    enum CandidateKind {
1009      /// The candidate is a function declaration.
1010      CK_Function,
1011
1012      /// The candidate is a function template.
1013      CK_FunctionTemplate,
1014
1015      /// The "candidate" is actually a variable, expression, or block
1016      /// for which we only have a function prototype.
1017      CK_FunctionType
1018    };
1019
1020  private:
1021    /// The kind of overload candidate.
1022    CandidateKind Kind;
1023
1024    union {
1025      /// The function overload candidate, available when
1026      /// Kind == CK_Function.
1027      FunctionDecl *Function;
1028
1029      /// The function template overload candidate, available when
1030      /// Kind == CK_FunctionTemplate.
1031      FunctionTemplateDecl *FunctionTemplate;
1032
1033      /// The function type that describes the entity being called,
1034      /// when Kind == CK_FunctionType.
1035      const FunctionType *Type;
1036    };
1037
1038  public:
1039    OverloadCandidate(FunctionDecl *Function)
1040        : Kind(CK_Function), Function(Function) {}
1041
1042    OverloadCandidate(FunctionTemplateDecl *FunctionTemplateDecl)
1043        : Kind(CK_FunctionTemplate), FunctionTemplate(FunctionTemplateDecl) {}
1044
1045    OverloadCandidate(const FunctionType *Type)
1046        : Kind(CK_FunctionType), Type(Type) {}
1047
1048    /// Determine the kind of overload candidate.
1049    CandidateKind getKind() const { return Kind; }
1050
1051    /// Retrieve the function overload candidate or the templated
1052    /// function declaration for a function template.
1053    FunctionDecl *getFunction() const;
1054
1055    /// Retrieve the function template overload candidate.
1056    FunctionTemplateDecl *getFunctionTemplate() const {
1057      assert(getKind() == CK_FunctionTemplate && "Not a function template");
1058      return FunctionTemplate;
1059    }
1060
1061    /// Retrieve the function type of the entity, regardless of how the
1062    /// function is stored.
1063    const FunctionType *getFunctionType() const;
1064
1065    /// Create a new code-completion string that describes the function
1066    /// signature of this overload candidate.
1067    CodeCompletionString *CreateSignatureString(unsigned CurrentArg,
1068                                                Sema &S,
1069                                      CodeCompletionAllocator &Allocator,
1070                                      CodeCompletionTUInfo &CCTUInfo,
1071                                      bool IncludeBriefComments) const;
1072  };
1073
1074  CodeCompleteConsumer(const CodeCompleteOptions &CodeCompleteOpts)
1075      : CodeCompleteOpts(CodeCompleteOpts) {}
1076
1077  /// Whether the code-completion consumer wants to see macros.
1078  bool includeMacros() const {
1079    return CodeCompleteOpts.IncludeMacros;
1080  }
1081
1082  /// Whether the code-completion consumer wants to see code patterns.
1083  bool includeCodePatterns() const {
1084    return CodeCompleteOpts.IncludeCodePatterns;
1085  }
1086
1087  /// Whether to include global (top-level) declaration results.
1088  bool includeGlobals() const { return CodeCompleteOpts.IncludeGlobals; }
1089
1090  /// Whether to include declarations in namespace contexts (including
1091  /// the global namespace). If this is false, `includeGlobals()` will be
1092  /// ignored.
1093  bool includeNamespaceLevelDecls() const {
1094    return CodeCompleteOpts.IncludeNamespaceLevelDecls;
1095  }
1096
1097  /// Whether to include brief documentation comments within the set of
1098  /// code completions returned.
1099  bool includeBriefComments() const {
1100    return CodeCompleteOpts.IncludeBriefComments;
1101  }
1102
1103  /// Whether to include completion items with small fix-its, e.g. change
1104  /// '.' to '->' on member access, etc.
1105  bool includeFixIts() const { return CodeCompleteOpts.IncludeFixIts; }
1106
1107  /// Hint whether to load data from the external AST in order to provide
1108  /// full results. If false, declarations from the preamble may be omitted.
1109  bool loadExternal() const {
1110    return CodeCompleteOpts.LoadExternal;
1111  }
1112
1113  /// Deregisters and destroys this code-completion consumer.
1114  virtual ~CodeCompleteConsumer();
1115
1116  /// \name Code-completion filtering
1117  /// Check if the result should be filtered out.
1118  virtual bool isResultFilteredOut(StringRef Filter,
1119                                   CodeCompletionResult Results) {
1120    return false;
1121  }
1122
1123  /// \name Code-completion callbacks
1124  //@{
1125  /// Process the finalized code-completion results.
1126  virtual void ProcessCodeCompleteResults(Sema &S,
1127                                          CodeCompletionContext Context,
1128                                          CodeCompletionResult *Results,
1129                                          unsigned NumResults) {}
1130
1131  /// \param S the semantic-analyzer object for which code-completion is being
1132  /// done.
1133  ///
1134  /// \param CurrentArg the index of the current argument.
1135  ///
1136  /// \param Candidates an array of overload candidates.
1137  ///
1138  /// \param NumCandidates the number of overload candidates
1139  ///
1140  /// \param OpenParLoc location of the opening parenthesis of the argument
1141  ///        list.
1142  virtual void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
1143                                         OverloadCandidate *Candidates,
1144                                         unsigned NumCandidates,
1145                                         SourceLocation OpenParLoc) {}
1146  //@}
1147
1148  /// Retrieve the allocator that will be used to allocate
1149  /// code completion strings.
1150  virtual CodeCompletionAllocator &getAllocator() = 0;
1151
1152  virtual CodeCompletionTUInfo &getCodeCompletionTUInfo() = 0;
1153};
1154
1155/// Get the documentation comment used to produce
1156/// CodeCompletionString::BriefComment for RK_Declaration.
1157const RawComment *getCompletionComment(const ASTContext &Ctx,
1158                                       const NamedDecl *Decl);
1159
1160/// Get the documentation comment used to produce
1161/// CodeCompletionString::BriefComment for RK_Pattern.
1162const RawComment *getPatternCompletionComment(const ASTContext &Ctx,
1163                                              const NamedDecl *Decl);
1164
1165/// Get the documentation comment used to produce
1166/// CodeCompletionString::BriefComment for OverloadCandidate.
1167const RawComment *
1168getParameterComment(const ASTContext &Ctx,
1169                    const CodeCompleteConsumer::OverloadCandidate &Result,
1170                    unsigned ArgIndex);
1171
1172/// A simple code-completion consumer that prints the results it
1173/// receives in a simple format.
1174class PrintingCodeCompleteConsumer : public CodeCompleteConsumer {
1175  /// The raw output stream.
1176  raw_ostream &OS;
1177
1178  CodeCompletionTUInfo CCTUInfo;
1179
1180public:
1181  /// Create a new printing code-completion consumer that prints its
1182  /// results to the given raw output stream.
1183  PrintingCodeCompleteConsumer(const CodeCompleteOptions &CodeCompleteOpts,
1184                               raw_ostream &OS)
1185      : CodeCompleteConsumer(CodeCompleteOpts), OS(OS),
1186        CCTUInfo(std::make_shared<GlobalCodeCompletionAllocator>()) {}
1187
1188  /// Prints the finalized code-completion results.
1189  void ProcessCodeCompleteResults(Sema &S, CodeCompletionContext Context,
1190                                  CodeCompletionResult *Results,
1191                                  unsigned NumResults) override;
1192
1193  void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
1194                                 OverloadCandidate *Candidates,
1195                                 unsigned NumCandidates,
1196                                 SourceLocation OpenParLoc) override;
1197
1198  bool isResultFilteredOut(StringRef Filter, CodeCompletionResult Results) override;
1199
1200  CodeCompletionAllocator &getAllocator() override {
1201    return CCTUInfo.getAllocator();
1202  }
1203
1204  CodeCompletionTUInfo &getCodeCompletionTUInfo() override { return CCTUInfo; }
1205};
1206
1207} // namespace clang
1208
1209#endif // LLVM_CLANG_SEMA_CODECOMPLETECONSUMER_H
1210