Coverage Report

Created: 2020-09-22 08:39

/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
    /// An unknown context, in which we are recovering from a parsing
333
    /// error and don't know which completions we should give.
334
    CCC_Recovery
335
  };
336
337
  using VisitedContextSet = llvm::SmallPtrSet<DeclContext *, 8>;
338
339
private:
340
  Kind CCKind;
341
342
  /// Indicates whether we are completing a name of a using declaration, e.g.
343
  ///     using ^;
344
  ///     using a::^;
345
  bool IsUsingDeclaration;
346
347
  /// The type that would prefer to see at this point (e.g., the type
348
  /// of an initializer or function parameter).
349
  QualType PreferredType;
350
351
  /// The type of the base object in a member access expression.
352
  QualType BaseType;
353
354
  /// The identifiers for Objective-C selector parts.
355
  ArrayRef<IdentifierInfo *> SelIdents;
356
357
  /// The scope specifier that comes before the completion token e.g.
358
  /// "a::b::"
359
  llvm::Optional<CXXScopeSpec> ScopeSpecifier;
360
361
  /// A set of declaration contexts visited by Sema when doing lookup for
362
  /// code completion.
363
  VisitedContextSet VisitedContexts;
364
365
public:
366
  /// Construct a new code-completion context of the given kind.
367
  CodeCompletionContext(Kind CCKind)
368
827
      : 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
705
      : CCKind(CCKind), IsUsingDeclaration(false), SelIdents(SelIdents) {
374
705
    if (CCKind == CCC_DotMemberAccess || 
CCKind == CCC_ArrowMemberAccess607
||
375
566
        CCKind == CCC_ObjCPropertyAccess || 
CCKind == CCC_ObjCClassMessage543
||
376
514
        CCKind == CCC_ObjCInstanceMessage)
377
247
      BaseType = T;
378
458
    else
379
458
      PreferredType = T;
380
705
  }
381
382
0
  bool isUsingDeclaration() const { return IsUsingDeclaration; }
383
60
  void setIsUsingDeclaration(bool V) { IsUsingDeclaration = V; }
384
385
  /// Retrieve the kind of code-completion context.
386
76.4k
  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
65.7k
  QualType getPreferredType() const { return PreferredType; }
392
154
  void setPreferredType(QualType T) { PreferredType = T; }
393
394
  /// Retrieve the type of the base object in a member-access
395
  /// expression.
396
6.42k
  QualType getBaseType() const { return BaseType; }
397
398
  /// Retrieve the Objective-C selector identifiers.
399
715
  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
59
  void setCXXScopeSpecifier(CXXScopeSpec SS) {
409
59
    this->ScopeSpecifier = std::move(SS);
410
59
  }
411
412
  /// Adds a visited context.
413
1.00k
  void addVisitedContext(DeclContext *Ctx) {
414
1.00k
    VisitedContexts.insert(Ctx);
415
1.00k
  }
416
417
  /// Retrieves all visited contexts.
418
  const VisitedContextSet &getVisitedContexts() const {
419
    return VisitedContexts;
420
  }
421
422
0
  llvm::Optional<const CXXScopeSpec *> getCXXScopeSpecifier() {
423
0
    if (ScopeSpecifier)
424
0
      return ScopeSpecifier.getPointer();
425
0
    return llvm::None;
426
0
  }
427
};
428
429
/// Get string representation of \p Kind, useful for for debugging.
430
llvm::StringRef getCompletionKindString(CodeCompletionContext::Kind Kind);
431
432
/// A "string" used to describe how code completion can
433
/// be performed for an entity.
434
///
435
/// A code completion string typically shows how a particular entity can be
436
/// used. For example, the code completion string for a function would show
437
/// the syntax to call it, including the parentheses, placeholders for the
438
/// arguments, etc.
439
class CodeCompletionString {
440
public:
441
  /// The different kinds of "chunks" that can occur within a code
442
  /// completion string.
443
  enum ChunkKind {
444
    /// The piece of text that the user is expected to type to
445
    /// match the code-completion string, typically a keyword or the name of a
446
    /// declarator or macro.
447
    CK_TypedText,
448
449
    /// A piece of text that should be placed in the buffer, e.g.,
450
    /// parentheses or a comma in a function call.
451
    CK_Text,
452
453
    /// A code completion string that is entirely optional. For example,
454
    /// an optional code completion string that describes the default arguments
455
    /// in a function call.
456
    CK_Optional,
457
458
    /// A string that acts as a placeholder for, e.g., a function
459
    /// call argument.
460
    CK_Placeholder,
461
462
    /// A piece of text that describes something about the result but
463
    /// should not be inserted into the buffer.
464
    CK_Informative,
465
    /// A piece of text that describes the type of an entity or, for
466
    /// functions and methods, the return type.
467
    CK_ResultType,
468
469
    /// A piece of text that describes the parameter that corresponds
470
    /// to the code-completion location within a function call, message send,
471
    /// macro invocation, etc.
472
    CK_CurrentParameter,
473
474
    /// A left parenthesis ('(').
475
    CK_LeftParen,
476
477
    /// A right parenthesis (')').
478
    CK_RightParen,
479
480
    /// A left bracket ('[').
481
    CK_LeftBracket,
482
483
    /// A right bracket (']').
484
    CK_RightBracket,
485
486
    /// A left brace ('{').
487
    CK_LeftBrace,
488
489
    /// A right brace ('}').
490
    CK_RightBrace,
491
492
    /// A left angle bracket ('<').
493
    CK_LeftAngle,
494
495
    /// A right angle bracket ('>').
496
    CK_RightAngle,
497
498
    /// A comma separator (',').
499
    CK_Comma,
500
501
    /// A colon (':').
502
    CK_Colon,
503
504
    /// A semicolon (';').
505
    CK_SemiColon,
506
507
    /// An '=' sign.
508
    CK_Equal,
509
510
    /// Horizontal whitespace (' ').
511
    CK_HorizontalSpace,
512
513
    /// Vertical whitespace ('\\n' or '\\r\\n', depending on the
514
    /// platform).
515
    CK_VerticalSpace
516
  };
517
518
  /// One piece of the code completion string.
519
  struct Chunk {
520
    /// The kind of data stored in this piece of the code completion
521
    /// string.
522
    ChunkKind Kind = CK_Text;
523
524
    union {
525
      /// The text string associated with a CK_Text, CK_Placeholder,
526
      /// CK_Informative, or CK_Comma chunk.
527
      /// The string is owned by the chunk and will be deallocated
528
      /// (with delete[]) when the chunk is destroyed.
529
      const char *Text;
530
531
      /// The code completion string associated with a CK_Optional chunk.
532
      /// The optional code completion string is owned by the chunk, and will
533
      /// be deallocated (with delete) when the chunk is destroyed.
534
      CodeCompletionString *Optional;
535
    };
536
537
100
    Chunk() : Text(nullptr) {}
538
539
    explicit Chunk(ChunkKind Kind, const char *Text = "");
540
541
    /// Create a new text chunk.
542
    static Chunk CreateText(const char *Text);
543
544
    /// Create a new optional chunk.
545
    static Chunk CreateOptional(CodeCompletionString *Optional);
546
547
    /// Create a new placeholder chunk.
548
    static Chunk CreatePlaceholder(const char *Placeholder);
549
550
    /// Create a new informative chunk.
551
    static Chunk CreateInformative(const char *Informative);
552
553
    /// Create a new result type chunk.
554
    static Chunk CreateResultType(const char *ResultType);
555
556
    /// Create a new current-parameter chunk.
557
    static Chunk CreateCurrentParameter(const char *CurrentParameter);
558
  };
559
560
private:
561
  friend class CodeCompletionBuilder;
562
  friend class CodeCompletionResult;
563
564
  /// The number of chunks stored in this string.
565
  unsigned NumChunks : 16;
566
567
  /// The number of annotations for this code-completion result.
568
  unsigned NumAnnotations : 16;
569
570
  /// The priority of this code-completion string.
571
  unsigned Priority : 16;
572
573
  /// The availability of this code-completion result.
574
  unsigned Availability : 2;
575
576
  /// The name of the parent context.
577
  StringRef ParentName;
578
579
  /// A brief documentation comment attached to the declaration of
580
  /// entity being completed by this result.
581
  const char *BriefComment;
582
583
  CodeCompletionString(const Chunk *Chunks, unsigned NumChunks,
584
                       unsigned Priority, CXAvailabilityKind Availability,
585
                       const char **Annotations, unsigned NumAnnotations,
586
                       StringRef ParentName,
587
                       const char *BriefComment);
588
  ~CodeCompletionString() = default;
589
590
public:
591
  CodeCompletionString(const CodeCompletionString &) = delete;
592
  CodeCompletionString &operator=(const CodeCompletionString &) = delete;
593
594
  using iterator = const Chunk *;
595
596
15.3M
  iterator begin() const { return reinterpret_cast<const Chunk *>(this + 1); }
597
7.44M
  iterator end() const { return begin() + NumChunks; }
598
0
  bool empty() const { return NumChunks == 0; }
599
829k
  unsigned size() const { return NumChunks; }
600
601
429k
  const Chunk &operator[](unsigned I) const {
602
429k
    assert(I < size() && "Chunk index out-of-range");
603
429k
    return begin()[I];
604
429k
  }
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
112k
  unsigned getPriority() const { return Priority; }
611
612
  /// Retrieve the availability of this code completion result.
613
112k
  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
112k
  StringRef getParentContextName() const {
623
112k
    return ParentName;
624
112k
  }
625
626
113k
  const char *getBriefComment() const {
627
113k
    return BriefComment;
628
113k
  }
629
630
  /// Retrieve a string representation of the code completion string,
631
  /// which is mainly useful for debugging.
632
  std::string getAsString() const;
633
};
634
635
/// An allocator used specifically for the purpose of code completion.
636
class CodeCompletionAllocator : public llvm::BumpPtrAllocator {
637
public:
638
  /// Copy the given string into this allocator.
639
  const char *CopyString(const Twine &String);
640
};
641
642
/// Allocator for a cached set of global code completions.
643
class GlobalCodeCompletionAllocator : public CodeCompletionAllocator {};
644
645
class CodeCompletionTUInfo {
646
  llvm::DenseMap<const DeclContext *, StringRef> ParentNames;
647
  std::shared_ptr<GlobalCodeCompletionAllocator> AllocatorRef;
648
649
public:
650
  explicit CodeCompletionTUInfo(
651
      std::shared_ptr<GlobalCodeCompletionAllocator> Allocator)
652
1.35k
      : AllocatorRef(std::move(Allocator)) {}
653
654
0
  std::shared_ptr<GlobalCodeCompletionAllocator> getAllocatorRef() const {
655
0
    return AllocatorRef;
656
0
  }
657
658
7.48k
  CodeCompletionAllocator &getAllocator() const {
659
7.48k
    assert(AllocatorRef);
660
7.48k
    return *AllocatorRef;
661
7.48k
  }
662
663
  StringRef getParentName(const DeclContext *DC);
664
};
665
666
} // namespace clang
667
668
namespace clang {
669
670
/// A builder class used to construct new code-completion strings.
671
class CodeCompletionBuilder {
672
public:
673
  using Chunk = CodeCompletionString::Chunk;
674
675
private:
676
  CodeCompletionAllocator &Allocator;
677
  CodeCompletionTUInfo &CCTUInfo;
678
  unsigned Priority = 0;
679
  CXAvailabilityKind Availability = CXAvailability_Available;
680
  StringRef ParentName;
681
  const char *BriefComment = nullptr;
682
683
  /// The chunks stored in this string.
684
  SmallVector<Chunk, 4> Chunks;
685
686
  SmallVector<const char *, 2> Annotations;
687
688
public:
689
  CodeCompletionBuilder(CodeCompletionAllocator &Allocator,
690
                        CodeCompletionTUInfo &CCTUInfo)
691
6.35k
      : 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
197k
        Availability(Availability) {}
698
699
  /// Retrieve the allocator into which the code completion
700
  /// strings should be allocated.
701
298k
  CodeCompletionAllocator &getAllocator() const { return Allocator; }
702
703
2.20k
  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
6
  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
4
  const char *getBriefComment() const { return BriefComment; }
740
  void addBriefComment(StringRef Comment);
741
742
202
  StringRef getParentName() const { return ParentName; }
743
};
744
745
/// Captures a result of code completion.
746
class CodeCompletionResult {
747
public:
748
  /// Describes the kind of result generated.
749
  enum ResultKind {
750
    /// Refers to a declaration.
751
    RK_Declaration = 0,
752
753
    /// Refers to a keyword or symbol.
754
    RK_Keyword,
755
756
    /// Refers to a macro.
757
    RK_Macro,
758
759
    /// Refers to a precomputed pattern.
760
    RK_Pattern
761
  };
762
763
  /// When Kind == RK_Declaration or RK_Pattern, the declaration we are
764
  /// referring to. In the latter case, the declaration might be NULL.
765
  const NamedDecl *Declaration = nullptr;
766
767
  union {
768
    /// When Kind == RK_Keyword, the string representing the keyword
769
    /// or symbol's spelling.
770
    const char *Keyword;
771
772
    /// When Kind == RK_Pattern, the code-completion string that
773
    /// describes the completion text to insert.
774
    CodeCompletionString *Pattern;
775
776
    /// When Kind == RK_Macro, the identifier that refers to a macro.
777
    const IdentifierInfo *Macro;
778
  };
779
780
  /// The priority of this particular code-completion result.
781
  unsigned Priority;
782
783
  /// Specifies which parameter (of a function, Objective-C method,
784
  /// macro, etc.) we should start with when formatting the result.
785
  unsigned StartParameter = 0;
786
787
  /// The kind of result stored here.
788
  ResultKind Kind;
789
790
  /// The cursor kind that describes this result.
791
  CXCursorKind CursorKind;
792
793
  /// The availability of this result.
794
  CXAvailabilityKind Availability = CXAvailability_Available;
795
796
  /// Fix-its that *must* be applied before inserting the text for the
797
  /// corresponding completion.
798
  ///
799
  /// By default, CodeCompletionBuilder only returns completions with empty
800
  /// fix-its. Extra completions with non-empty fix-its should be explicitly
801
  /// requested by setting CompletionOptions::IncludeFixIts.
802
  ///
803
  /// For the clients to be able to compute position of the cursor after
804
  /// applying fix-its, the following conditions are guaranteed to hold for
805
  /// RemoveRange of the stored fix-its:
806
  ///  - Ranges in the fix-its are guaranteed to never contain the completion
807
  ///  point (or identifier under completion point, if any) inside them, except
808
  ///  at the start or at the end of the range.
809
  ///  - If a fix-it range starts or ends with completion point (or starts or
810
  ///  ends after the identifier under completion point), it will contain at
811
  ///  least one character. It allows to unambiguously recompute completion
812
  ///  point after applying the fix-it.
813
  ///
814
  /// The intuition is that provided fix-its change code around the identifier
815
  /// we complete, but are not allowed to touch the identifier itself or the
816
  /// completion point. One example of completions with corrections are the ones
817
  /// replacing '.' with '->' and vice versa:
818
  ///
819
  /// std::unique_ptr<std::vector<int>> vec_ptr;
820
  /// In 'vec_ptr.^', one of the completions is 'push_back', it requires
821
  /// replacing '.' with '->'.
822
  /// In 'vec_ptr->^', one of the completions is 'release', it requires
823
  /// replacing '->' with '.'.
824
  std::vector<FixItHint> FixIts;
825
826
  /// Whether this result is hidden by another name.
827
  bool Hidden : 1;
828
829
  /// Whether this is a class member from base class.
830
  bool InBaseClass : 1;
831
832
  /// Whether this result was found via lookup into a base class.
833
  bool QualifierIsInformative : 1;
834
835
  /// Whether this declaration is the beginning of a
836
  /// nested-name-specifier and, therefore, should be followed by '::'.
837
  bool StartsNestedNameSpecifier : 1;
838
839
  /// Whether all parameters (of a function, Objective-C
840
  /// method, etc.) should be considered "informative".
841
  bool AllParametersAreInformative : 1;
842
843
  /// Whether we're completing a declaration of the given entity,
844
  /// rather than a use of that entity.
845
  bool DeclaringEntity : 1;
846
847
  /// If the result should have a nested-name-specifier, this is it.
848
  /// When \c QualifierIsInformative, the nested-name-specifier is
849
  /// informative rather than required.
850
  NestedNameSpecifier *Qualifier = nullptr;
851
852
  /// If this Decl was unshadowed by using declaration, this can store a
853
  /// pointer to the UsingShadowDecl which was used in the unshadowing process.
854
  /// This information can be used to uprank CodeCompletionResults / which have
855
  /// corresponding `using decl::qualified::name;` nearby.
856
  const UsingShadowDecl *ShadowDecl = nullptr;
857
858
  /// If the result is RK_Macro, this can store the information about the macro
859
  /// definition. This should be set in most cases but can be missing when
860
  /// the macro has been undefined.
861
  const MacroInfo *MacroDefInfo = nullptr;
862
863
  /// Build a result that refers to a declaration.
864
  CodeCompletionResult(const NamedDecl *Declaration, unsigned Priority,
865
                       NestedNameSpecifier *Qualifier = nullptr,
866
                       bool QualifierIsInformative = false,
867
                       bool Accessible = true,
868
                       std::vector<FixItHint> FixIts = std::vector<FixItHint>())
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
17.6k
        DeclaringEntity(false), Qualifier(Qualifier) {
874
    // FIXME: Add assert to check FixIts range requirements.
875
17.6k
    computeCursorKindAndAvailability(Accessible);
876
17.6k
  }
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
15.3k
        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
124k
        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
69.3k
        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
243
        DeclaringEntity(false) {
915
243
    computeCursorKindAndAvailability();
916
243
  }
917
918
  /// Retrieve the declaration stored in this result. This might be nullptr if
919
  /// Kind is RK_Pattern.
920
0
  const NamedDecl *getDeclaration() const {
921
0
    assert(((Kind == RK_Declaration) || (Kind == RK_Pattern)) &&
922
0
           "Not a declaration or pattern result");
923
0
    return Declaration;
924
0
  }
925
926
  /// Retrieve the keyword stored in this result.
927
0
  const char *getKeyword() const {
928
0
    assert(Kind == RK_Keyword && "Not a keyword result");
929
0
    return Keyword;
930
0
  }
931
932
  /// Create a new code-completion string that describes how to insert
933
  /// this result into a program.
934
  ///
935
  /// \param S The semantic analysis that created the result.
936
  ///
937
  /// \param Allocator The allocator that will be used to allocate the
938
  /// string itself.
939
  CodeCompletionString *CreateCodeCompletionString(Sema &S,
940
                                         const CodeCompletionContext &CCContext,
941
                                           CodeCompletionAllocator &Allocator,
942
                                           CodeCompletionTUInfo &CCTUInfo,
943
                                           bool IncludeBriefComments);
944
  CodeCompletionString *CreateCodeCompletionString(ASTContext &Ctx,
945
                                                   Preprocessor &PP,
946
                                         const CodeCompletionContext &CCContext,
947
                                           CodeCompletionAllocator &Allocator,
948
                                           CodeCompletionTUInfo &CCTUInfo,
949
                                           bool IncludeBriefComments);
950
  /// Creates a new code-completion string for the macro result. Similar to the
951
  /// above overloads, except this only requires preprocessor information.
952
  /// The result kind must be `RK_Macro`.
953
  CodeCompletionString *
954
  CreateCodeCompletionStringForMacro(Preprocessor &PP,
955
                                     CodeCompletionAllocator &Allocator,
956
                                     CodeCompletionTUInfo &CCTUInfo);
957
958
  CodeCompletionString *createCodeCompletionStringForDecl(
959
      Preprocessor &PP, ASTContext &Ctx, CodeCompletionBuilder &Result,
960
      bool IncludeBriefComments, const CodeCompletionContext &CCContext,
961
      PrintingPolicy &Policy);
962
963
  CodeCompletionString *createCodeCompletionStringForOverride(
964
      Preprocessor &PP, ASTContext &Ctx, CodeCompletionBuilder &Result,
965
      bool IncludeBriefComments, const CodeCompletionContext &CCContext,
966
      PrintingPolicy &Policy);
967
968
  /// Retrieve the name that should be used to order a result.
969
  ///
970
  /// If the name needs to be constructed as a string, that string will be
971
  /// saved into Saved and the returned StringRef will refer to it.
972
  StringRef getOrderedName(std::string &Saved) const;
973
974
private:
975
  void computeCursorKindAndAvailability(bool Accessible = true);
976
};
977
978
bool operator<(const CodeCompletionResult &X, const CodeCompletionResult &Y);
979
980
inline bool operator>(const CodeCompletionResult &X,
981
0
                      const CodeCompletionResult &Y) {
982
0
  return Y < X;
983
0
}
984
985
inline bool operator<=(const CodeCompletionResult &X,
986
0
                      const CodeCompletionResult &Y) {
987
0
  return !(Y < X);
988
0
}
989
990
inline bool operator>=(const CodeCompletionResult &X,
991
0
                       const CodeCompletionResult &Y) {
992
0
  return !(X < Y);
993
0
}
994
995
raw_ostream &operator<<(raw_ostream &OS,
996
                              const CodeCompletionString &CCS);
997
998
/// Abstract interface for a consumer of code-completion
999
/// information.
1000
class CodeCompleteConsumer {
1001
protected:
1002
  const CodeCompleteOptions CodeCompleteOpts;
1003
1004
public:
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
306
        : Kind(CK_Function), Function(Function) {}
1041
1042
    OverloadCandidate(FunctionTemplateDecl *FunctionTemplateDecl)
1043
0
        : Kind(CK_FunctionTemplate), FunctionTemplate(FunctionTemplateDecl) {}
1044
1045
    OverloadCandidate(const FunctionType *Type)
1046
5
        : Kind(CK_FunctionType), Type(Type) {}
1047
1048
    /// Determine the kind of overload candidate.
1049
244
    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
0
    FunctionTemplateDecl *getFunctionTemplate() const {
1057
0
      assert(getKind() == CK_FunctionTemplate && "Not a function template");
1058
0
      return FunctionTemplate;
1059
0
    }
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
1.94k
      : CodeCompleteOpts(CodeCompleteOpts) {}
1076
1077
  /// Whether the code-completion consumer wants to see macros.
1078
652
  bool includeMacros() const {
1079
652
    return CodeCompleteOpts.IncludeMacros;
1080
652
  }
1081
1082
  /// Whether the code-completion consumer wants to see code patterns.
1083
682
  bool includeCodePatterns() const {
1084
682
    return CodeCompleteOpts.IncludeCodePatterns;
1085
682
  }
1086
1087
  /// Whether to include global (top-level) declaration results.
1088
830
  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
57
  bool includeNamespaceLevelDecls() const {
1094
57
    return CodeCompleteOpts.IncludeNamespaceLevelDecls;
1095
57
  }
1096
1097
  /// Whether to include brief documentation comments within the set of
1098
  /// code completions returned.
1099
159k
  bool includeBriefComments() const {
1100
159k
    return CodeCompleteOpts.IncludeBriefComments;
1101
159k
  }
1102
1103
  /// Whether to include completion items with small fix-its, e.g. change
1104
  /// '.' to '->' on member access, etc.
1105
158k
  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
1.79k
  bool loadExternal() const {
1110
1.79k
    return CodeCompleteOpts.LoadExternal;
1111
1.79k
  }
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
0
                                   CodeCompletionResult Results) {
1120
0
    return false;
1121
0
  }
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
0
                                          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
42
                                         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.
1157
const RawComment *getCompletionComment(const ASTContext &Ctx,
1158
                                       const NamedDecl *Decl);
1159
1160
/// Get the documentation comment used to produce
1161
/// CodeCompletionString::BriefComment for RK_Pattern.
1162
const RawComment *getPatternCompletionComment(const ASTContext &Ctx,
1163
                                              const NamedDecl *Decl);
1164
1165
/// Get the documentation comment used to produce
1166
/// CodeCompletionString::BriefComment for OverloadCandidate.
1167
const RawComment *
1168
getParameterComment(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.
1174
class PrintingCodeCompleteConsumer : public CodeCompleteConsumer {
1175
  /// The raw output stream.
1176
  raw_ostream &OS;
1177
1178
  CodeCompletionTUInfo CCTUInfo;
1179
1180
public:
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
268
        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
7.13k
  CodeCompletionAllocator &getAllocator() override {
1201
7.13k
    return CCTUInfo.getAllocator();
1202
7.13k
  }
1203
1204
4.48k
  CodeCompletionTUInfo &getCodeCompletionTUInfo() override { return CCTUInfo; }
1205
};
1206
1207
} // namespace clang
1208
1209
#endif // LLVM_CLANG_SEMA_CODECOMPLETECONSUMER_H