include/clang/Sema/CodeCompleteConsumer.h

   1 //===---- CodeCompleteConsumer.h - Code Completion Interface ----*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 //  This file defines the CodeCompleteConsumer class.
  11 //
  12 //===----------------------------------------------------------------------===//
  13 #ifndef LLVM_CLANG_SEMA_CODECOMPLETECONSUMER_H
  14 #define LLVM_CLANG_SEMA_CODECOMPLETECONSUMER_H
  15
  16 #include "llvm/ADT/SmallVector.h"
  17 #include "llvm/ADT/StringRef.h"
  18 #include <memory>
  19 #include <string>
  20
  21 namespace llvm {
  22 class raw_ostream;
  23 }
  24
  25 namespace clang {
  26
  27 class FunctionDecl;
  28 class FunctionType;
  29 class FunctionTemplateDecl;
  30 class IdentifierInfo;
  31 class NamedDecl;
  32 class NestedNameSpecifier;
  33 class Sema;
  34
  35 /// \brief A "string" used to describe how code completion can
  36 /// be performed for an entity.
  37 ///
  38 /// A code completion string typically shows how a particular entity can be
  39 /// used. For example, the code completion string for a function would show
  40 /// the syntax to call it, including the parentheses, placeholders for the
  41 /// arguments, etc.
  42 class CodeCompletionString {
  43 public:
  44   /// \brief The different kinds of "chunks" that can occur within a code
  45   /// completion string.
  46   enum ChunkKind {
  47     /// \brief The piece of text that the user is expected to type to
  48     /// match the code-completion string, typically a keyword or the name of a
  49     /// declarator or macro.
  50     CK_TypedText,
  51     /// \brief A piece of text that should be placed in the buffer, e.g.,
  52     /// parentheses or a comma in a function call.
  53     CK_Text,
  54     /// \brief A code completion string that is entirely optional. For example,
  55     /// an optional code completion string that describes the default arguments
  56     /// in a function call.
  57     CK_Optional,
  58     /// \brief A string that acts as a placeholder for, e.g., a function
  59     /// call argument.
  60     CK_Placeholder,
  61     /// \brief A piece of text that describes something about the result but
  62     /// should not be inserted into the buffer.
  63     CK_Informative,
  64     /// \brief A piece of text that describes the parameter that corresponds
  65     /// to the code-completion location within a function call, message send,
  66     /// macro invocation, etc.
  67     CK_CurrentParameter,
  68     /// \brief A left parenthesis ('(').
  69     CK_LeftParen,
  70     /// \brief A right parenthesis (')').
  71     CK_RightParen,
  72     /// \brief A left bracket ('[').
  73     CK_LeftBracket,
  74     /// \brief A right bracket (']').
  75     CK_RightBracket,
  76     /// \brief A left brace ('{').
  77     CK_LeftBrace,
  78     /// \brief A right brace ('}').
  79     CK_RightBrace,
  80     /// \brief A left angle bracket ('<').
  81     CK_LeftAngle,
  82     /// \brief A right angle bracket ('>').
  83     CK_RightAngle,
  84     /// \brief A comma separator (',').
  85     CK_Comma
  86   };
  87
  88   /// \brief One piece of the code completion string.
  89   struct Chunk {
  90     /// \brief The kind of data stored in this piece of the code completion
  91     /// string.
  92     ChunkKind Kind;
  93
  94     union {
  95       /// \brief The text string associated with a CK_Text, CK_Placeholder,
  96       /// CK_Informative, or CK_Comma chunk.
  97       /// The string is owned by the chunk and will be deallocated
  98       /// (with delete[]) when the chunk is destroyed.
  99       const char *Text;
 100
 101       /// \brief The code completion string associated with a CK_Optional chunk.
 102       /// The optional code completion string is owned by the chunk, and will
 103       /// be deallocated (with delete) when the chunk is destroyed.
 104       CodeCompletionString *Optional;
 105     };
 106
 107     Chunk() : Kind(CK_Text), Text(0) { }
 108
 109     Chunk(ChunkKind Kind, llvm::StringRef Text = "");
 110
 111     /// \brief Create a new text chunk.
 112     static Chunk CreateText(llvm::StringRef Text);
 113
 114     /// \brief Create a new optional chunk.
 115     static Chunk CreateOptional(std::auto_ptr<CodeCompletionString> Optional);
 116
 117     /// \brief Create a new placeholder chunk.
 118     static Chunk CreatePlaceholder(llvm::StringRef Placeholder);
 119
 120     /// \brief Create a new informative chunk.
 121     static Chunk CreateInformative(llvm::StringRef Informative);
 122
 123     /// \brief Create a new current-parameter chunk.
 124     static Chunk CreateCurrentParameter(llvm::StringRef CurrentParameter);
 125
 126     /// \brief Clone the given chunk.
 127     Chunk Clone() const;
 128
 129     /// \brief Destroy this chunk, deallocating any memory it owns.
 130     void Destroy();
 131   };
 132
 133 private:
 134   /// \brief The chunks stored in this string.
 135   llvm::SmallVector<Chunk, 4> Chunks;
 136
 137   CodeCompletionString(const CodeCompletionString &); // DO NOT IMPLEMENT
 138   CodeCompletionString &operator=(const CodeCompletionString &); // DITTO
 139
 140 public:
 141   CodeCompletionString() { }
 142   ~CodeCompletionString();
 143
 144   typedef llvm::SmallVector<Chunk, 4>::const_iterator iterator;
 145   iterator begin() const { return Chunks.begin(); }
 146   iterator end() const { return Chunks.end(); }
 147   bool empty() const { return Chunks.empty(); }
 148   unsigned size() const { return Chunks.size(); }
 149
 150   Chunk &operator[](unsigned I) {
 151     assert(I < size() && "Chunk index out-of-range");
 152     return Chunks[I];
 153   }
 154
 155   const Chunk &operator[](unsigned I) const {
 156     assert(I < size() && "Chunk index out-of-range");
 157     return Chunks[I];
 158   }
 159
 160   /// \brief Add a new typed-text chunk.
 161   /// The text string will be copied.
 162   void AddTypedTextChunk(llvm::StringRef Text) {
 163     Chunks.push_back(Chunk(CK_TypedText, Text));
 164   }
 165
 166   /// \brief Add a new text chunk.
 167   /// The text string will be copied.
 168   void AddTextChunk(llvm::StringRef Text) {
 169     Chunks.push_back(Chunk::CreateText(Text));
 170   }
 171
 172   /// \brief Add a new optional chunk.
 173   void AddOptionalChunk(std::auto_ptr<CodeCompletionString> Optional) {
 174     Chunks.push_back(Chunk::CreateOptional(Optional));
 175   }
 176
 177   /// \brief Add a new placeholder chunk.
 178   /// The placeholder text will be copied.
 179   void AddPlaceholderChunk(llvm::StringRef Placeholder) {
 180     Chunks.push_back(Chunk::CreatePlaceholder(Placeholder));
 181   }
 182
 183   /// \brief Add a new informative chunk.
 184   /// The text will be copied.
 185   void AddInformativeChunk(llvm::StringRef Text) {
 186     Chunks.push_back(Chunk::CreateInformative(Text));
 187   }
 188
 189   /// \brief Add a new current-parameter chunk.
 190   /// The text will be copied.
 191   void AddCurrentParameterChunk(llvm::StringRef CurrentParameter) {
 192     Chunks.push_back(Chunk::CreateCurrentParameter(CurrentParameter));
 193   }
 194
 195   /// \brief Add a new chunk.
 196   void AddChunk(Chunk C) { Chunks.push_back(C); }
 197
 198   /// \brief Returns the text in the TypedText chunk.
 199   const char *getTypedText() const;
 200
 201   /// \brief Retrieve a string representation of the code completion string,
 202   /// which is mainly useful for debugging.
 203   std::string getAsString() const;
 204
 205   /// \brief Clone this code-completion string.
 206   CodeCompletionString *Clone() const;
 207
 208   /// \brief Serialize this code-completion string to the given stream.
 209   void Serialize(llvm::raw_ostream &OS) const;
 210
 211   /// \brief Deserialize a code-completion string from the given string.
 212   static CodeCompletionString *Deserialize(llvm::StringRef &Str);
 213 };
 214
 215 llvm::raw_ostream &operator<<(llvm::raw_ostream &OS,
 216                               const CodeCompletionString &CCS);
 217
 218 /// \brief Abstract interface for a consumer of code-completion
 219 /// information.
 220 class CodeCompleteConsumer {
 221 protected:
 222   /// \brief Whether to include macros in the code-completion results.
 223   bool IncludeMacros;
 224
 225 public:
 226   /// \brief Captures a result of code completion.
 227   struct Result {
 228     /// \brief Describes the kind of result generated.
 229     enum ResultKind {
 230       RK_Declaration = 0, //< Refers to a declaration
 231       RK_Keyword,         //< Refers to a keyword or symbol.
 232       RK_Macro,           //< Refers to a macro
 233       RK_Pattern          //< Refers to a precomputed pattern.
 234     };
 235
 236     /// \brief The kind of result stored here.
 237     ResultKind Kind;
 238
 239     union {
 240       /// \brief When Kind == RK_Declaration, the declaration we are referring
 241       /// to.
 242       NamedDecl *Declaration;
 243
 244       /// \brief When Kind == RK_Keyword, the string representing the keyword
 245       /// or symbol's spelling.
 246       const char *Keyword;
 247
 248       /// \brief When Kind == RK_Pattern, the code-completion string that
 249       /// describes the completion text to insert.
 250       CodeCompletionString *Pattern;
 251
 252       /// \brief When Kind == RK_Macro, the identifier that refers to a macro.
 253       IdentifierInfo *Macro;
 254     };
 255
 256     /// \brief Describes how good this result is, with zero being the best
 257     /// result and progressively higher numbers representing poorer results.
 258     unsigned Rank;
 259
 260     /// \brief Specifiers which parameter (of a function, Objective-C method,
 261     /// macro, etc.) we should start with when formatting the result.
 262     unsigned StartParameter;
 263
 264     /// \brief Whether this result is hidden by another name.
 265     bool Hidden : 1;
 266
 267     /// \brief Whether this result was found via lookup into a base class.
 268     bool QualifierIsInformative : 1;
 269
 270     /// \brief Whether this declaration is the beginning of a
 271     /// nested-name-specifier and, therefore, should be followed by '::'.
 272     bool StartsNestedNameSpecifier : 1;
 273
 274     /// \brief Whether all parameters (of a function, Objective-C
 275     /// method, etc.) should be considered "informative".
 276     bool AllParametersAreInformative : 1;
 277
 278     /// \brief If the result should have a nested-name-specifier, this is it.
 279     /// When \c QualifierIsInformative, the nested-name-specifier is
 280     /// informative rather than required.
 281     NestedNameSpecifier *Qualifier;
 282
 283     /// \brief Build a result that refers to a declaration.
 284     Result(NamedDecl *Declaration, unsigned Rank,
 285            NestedNameSpecifier *Qualifier = 0,
 286            bool QualifierIsInformative = false)
 287       : Kind(RK_Declaration), Declaration(Declaration), Rank(Rank),
 288         StartParameter(0), Hidden(false),
 289         QualifierIsInformative(QualifierIsInformative),
 290         StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
 291         Qualifier(Qualifier) { }
 292
 293     /// \brief Build a result that refers to a keyword or symbol.
 294     Result(const char *Keyword, unsigned Rank)
 295       : Kind(RK_Keyword), Keyword(Keyword), Rank(Rank), StartParameter(0),
 296         Hidden(false), QualifierIsInformative(0),
 297         StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
 298         Qualifier(0) { }
 299
 300     /// \brief Build a result that refers to a macro.
 301     Result(IdentifierInfo *Macro, unsigned Rank)
 302      : Kind(RK_Macro), Macro(Macro), Rank(Rank), StartParameter(0),
 303        Hidden(false), QualifierIsInformative(0),
 304        StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
 305        Qualifier(0) { }
 306
 307     /// \brief Build a result that refers to a pattern.
 308     Result(CodeCompletionString *Pattern, unsigned Rank)
 309       : Kind(RK_Pattern), Pattern(Pattern), Rank(Rank), StartParameter(0),
 310         Hidden(false), QualifierIsInformative(0),
 311         StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
 312         Qualifier(0) { }
 313
 314     /// \brief Retrieve the declaration stored in this result.
 315     NamedDecl *getDeclaration() const {
 316       assert(Kind == RK_Declaration && "Not a declaration result");
 317       return Declaration;
 318     }
 319
 320     /// \brief Retrieve the keyword stored in this result.
 321     const char *getKeyword() const {
 322       assert(Kind == RK_Keyword && "Not a keyword result");
 323       return Keyword;
 324     }
 325
 326     /// \brief Create a new code-completion string that describes how to insert
 327     /// this result into a program.
 328     CodeCompletionString *CreateCodeCompletionString(Sema &S);
 329
 330     void Destroy();
 331   };
 332
 333   class OverloadCandidate {
 334   public:
 335     /// \brief Describes the type of overload candidate.
 336     enum CandidateKind {
 337       /// \brief The candidate is a function declaration.
 338       CK_Function,
 339       /// \brief The candidate is a function template.
 340       CK_FunctionTemplate,
 341       /// \brief The "candidate" is actually a variable, expression, or block
 342       /// for which we only have a function prototype.
 343       CK_FunctionType
 344     };
 345
 346   private:
 347     /// \brief The kind of overload candidate.
 348     CandidateKind Kind;
 349
 350     union {
 351       /// \brief The function overload candidate, available when
 352       /// Kind == CK_Function.
 353       FunctionDecl *Function;
 354
 355       /// \brief The function template overload candidate, available when
 356       /// Kind == CK_FunctionTemplate.
 357       FunctionTemplateDecl *FunctionTemplate;
 358
 359       /// \brief The function type that describes the entity being called,
 360       /// when Kind == CK_FunctionType.
 361       const FunctionType *Type;
 362     };
 363
 364   public:
 365     OverloadCandidate(FunctionDecl *Function)
 366       : Kind(CK_Function), Function(Function) { }
 367
 368     OverloadCandidate(FunctionTemplateDecl *FunctionTemplateDecl)
 369       : Kind(CK_FunctionTemplate), FunctionTemplate(FunctionTemplate) { }
 370
 371     OverloadCandidate(const FunctionType *Type)
 372       : Kind(CK_FunctionType), Type(Type) { }
 373
 374     /// \brief Determine the kind of overload candidate.
 375     CandidateKind getKind() const { return Kind; }
 376
 377     /// \brief Retrieve the function overload candidate or the templated
 378     /// function declaration for a function template.
 379     FunctionDecl *getFunction() const;
 380
 381     /// \brief Retrieve the function template overload candidate.
 382     FunctionTemplateDecl *getFunctionTemplate() const {
 383       assert(getKind() == CK_FunctionTemplate && "Not a function template");
 384       return FunctionTemplate;
 385     }
 386
 387     /// \brief Retrieve the function type of the entity, regardless of how the
 388     /// function is stored.
 389     const FunctionType *getFunctionType() const;
 390
 391     /// \brief Create a new code-completion string that describes the function
 392     /// signature of this overload candidate.
 393     CodeCompletionString *CreateSignatureString(unsigned CurrentArg,
 394                                                 Sema &S) const;
 395   };
 396
 397   CodeCompleteConsumer() : IncludeMacros(false) { }
 398
 399   explicit CodeCompleteConsumer(bool IncludeMacros)
 400     : IncludeMacros(IncludeMacros) { }
 401
 402   /// \brief Whether the code-completion consumer wants to see macros.
 403   bool includeMacros() const { return IncludeMacros; }
 404
 405   /// \brief Deregisters and destroys this code-completion consumer.
 406   virtual ~CodeCompleteConsumer();
 407
 408   /// \name Code-completion callbacks
 409   //@{
 410   /// \brief Process the finalized code-completion results.
 411   virtual void ProcessCodeCompleteResults(Sema &S, Result *Results,
 412                                           unsigned NumResults) { }
 413
 414   /// \param S the semantic-analyzer object for which code-completion is being
 415   /// done.
 416   ///
 417   /// \param CurrentArg the index of the current argument.
 418   ///
 419   /// \param Candidates an array of overload candidates.
 420   ///
 421   /// \param NumCandidates the number of overload candidates
 422   virtual void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
 423                                          OverloadCandidate *Candidates,
 424                                          unsigned NumCandidates) { }
 425   //@}
 426 };
 427
 428 /// \brief A simple code-completion consumer that prints the results it
 429 /// receives in a simple format.
 430 class PrintingCodeCompleteConsumer : public CodeCompleteConsumer {
 431   /// \brief The raw output stream.
 432   llvm::raw_ostream &OS;
 433
 434 public:
 435   /// \brief Create a new printing code-completion consumer that prints its
 436   /// results to the given raw output stream.
 437   PrintingCodeCompleteConsumer(bool IncludeMacros,
 438                                llvm::raw_ostream &OS)
 439     : CodeCompleteConsumer(IncludeMacros), OS(OS) { }
 440
 441   /// \brief Prints the finalized code-completion results.
 442   virtual void ProcessCodeCompleteResults(Sema &S, Result *Results,
 443                                           unsigned NumResults);
 444
 445   virtual void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
 446                                          OverloadCandidate *Candidates,
 447                                          unsigned NumCandidates);
 448 };
 449
 450 /// \brief A code-completion consumer that prints the results it receives
 451 /// in a format that is parsable by the CIndex library.
 452 class CIndexCodeCompleteConsumer : public CodeCompleteConsumer {
 453   /// \brief The raw output stream.
 454   llvm::raw_ostream &OS;
 455
 456 public:
 457   /// \brief Create a new CIndex code-completion consumer that prints its
 458   /// results to the given raw output stream in a format readable to the CIndex
 459   /// library.
 460   CIndexCodeCompleteConsumer(bool IncludeMacros, llvm::raw_ostream &OS)
 461     : CodeCompleteConsumer(IncludeMacros), OS(OS) { }
 462
 463   /// \brief Prints the finalized code-completion results.
 464   virtual void ProcessCodeCompleteResults(Sema &S, Result *Results,
 465                                           unsigned NumResults);
 466
 467   virtual void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
 468                                          OverloadCandidate *Candidates,
 469                                          unsigned NumCandidates);
 470 };
 471
 472 } // end namespace clang
 473
 474 #endif // LLVM_CLANG_SEMA_CODECOMPLETECONSUMER_H