Coverage Report

Created: 2022-05-21 09:15

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