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