CodeCompleteConsumer.h revision 76e0fece5b0c829ee4c184e78863806d3ca04be8
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 <memory> 18#include <string> 19 20namespace llvm { 21class raw_ostream; 22} 23 24namespace clang { 25 26class NamedDecl; 27class NestedNameSpecifier; 28class Sema; 29 30/// \brief A "string" used to describe how code completion can 31/// be performed for an entity. 32/// 33/// A code completion string typically shows how a particular entity can be 34/// used. For example, the code completion string for a function would show 35/// the syntax to call it, including the parentheses, placeholders for the 36/// arguments, etc. 37class CodeCompletionString { 38public: 39 /// \brief The different kinds of "chunks" that can occur within a code 40 /// completion string. 41 enum ChunkKind { 42 /// \brief A piece of text that should be placed in the buffer, e.g., 43 /// parentheses or a comma in a function call. 44 CK_Text, 45 /// \brief A code completion string that is entirely optional. For example, 46 /// an optional code completion string that describes the default arguments 47 /// in a function call. 48 CK_Optional, 49 /// \brief A string that acts as a placeholder for, e.g., a function 50 /// call argument. 51 CK_Placeholder 52 }; 53 54 /// \brief One piece of the code completion string. 55 struct Chunk { 56 /// \brief The kind of data stored in this piece of the code completion 57 /// string. 58 ChunkKind Kind; 59 60 union { 61 /// \brief The text string associated with a CK_Text chunk. 62 /// The string is owned by the chunk and will be deallocated 63 /// (with delete[]) when the chunk is destroyed. 64 const char *Text; 65 66 /// \brief The code completion string associated with a CK_Optional chunk. 67 /// The optional code completion string is owned by the chunk, and will 68 /// be deallocated (with delete) when the chunk is destroyed. 69 CodeCompletionString *Optional; 70 71 /// \brief Placeholder text associated with a CK_Placeholder chunk. 72 /// The string is owned by the chunk and will be deallocated (with 73 /// delete[]) when the chunk is destroyed. 74 const char *Placeholder; 75 }; 76 77 /// \brief Create a new text chunk. 78 static Chunk CreateText(const char *Text); 79 80 /// \brief Create a new optional chunk. 81 static Chunk CreateOptional(std::auto_ptr<CodeCompletionString> Optional); 82 83 /// \brief Create a new placeholder chunk. 84 static Chunk CreatePlaceholder(const char *Placeholder); 85 86 /// \brief Destroy this chunk, deallocating any memory it owns. 87 void Destroy(); 88 }; 89 90private: 91 /// \brief The chunks stored in this string. 92 llvm::SmallVector<Chunk, 4> Chunks; 93 94 CodeCompletionString(const CodeCompletionString &); // DO NOT IMPLEMENT 95 CodeCompletionString &operator=(const CodeCompletionString &); // DITTO 96 97public: 98 CodeCompletionString() { } 99 ~CodeCompletionString(); 100 101 typedef llvm::SmallVector<Chunk, 4>::const_iterator iterator; 102 iterator begin() const { return Chunks.begin(); } 103 iterator end() const { return Chunks.end(); } 104 105 /// \brief Add a new text chunk. 106 /// The text string will be copied. 107 void AddTextChunk(const char *Text) { 108 Chunks.push_back(Chunk::CreateText(Text)); 109 } 110 111 /// \brief Add a new optional chunk. 112 void AddOptionalChunk(std::auto_ptr<CodeCompletionString> Optional) { 113 Chunks.push_back(Chunk::CreateOptional(Optional)); 114 } 115 116 /// \brief Add a new placeholder chunk. 117 /// The placeholder text will be copied. 118 void AddPlaceholderChunk(const char *Placeholder) { 119 Chunks.push_back(Chunk::CreatePlaceholder(Placeholder)); 120 } 121 122 /// \brief Retrieve a string representation of the code completion string, 123 /// which is mainly useful for debugging. 124 std::string getAsString() const; 125}; 126 127/// \brief Abstract interface for a consumer of code-completion 128/// information. 129class CodeCompleteConsumer { 130public: 131 /// \brief Captures a result of code completion. 132 struct Result { 133 /// \brief Describes the kind of result generated. 134 enum ResultKind { 135 RK_Declaration = 0, //< Refers to a declaration 136 RK_Keyword //< Refers to a keyword or symbol. 137 }; 138 139 /// \brief The kind of result stored here. 140 ResultKind Kind; 141 142 union { 143 /// \brief When Kind == RK_Declaration, the declaration we are referring 144 /// to. 145 NamedDecl *Declaration; 146 147 /// \brief When Kind == RK_Keyword, the string representing the keyword 148 /// or symbol's spelling. 149 const char *Keyword; 150 }; 151 152 /// \brief Describes how good this result is, with zero being the best 153 /// result and progressively higher numbers representing poorer results. 154 unsigned Rank; 155 156 /// \brief Whether this result is hidden by another name. 157 bool Hidden : 1; 158 159 /// \brief If the result requires a nested-name-specifier for name lookup 160 /// to function properly, this is the nested-name-specifier. 161 NestedNameSpecifier *Qualifier; 162 163 /// \brief Build a result that refers to a declaration. 164 Result(NamedDecl *Declaration, unsigned Rank, 165 NestedNameSpecifier *Qualifier = 0) 166 : Kind(RK_Declaration), Declaration(Declaration), Rank(Rank), 167 Hidden(false), Qualifier(Qualifier) { } 168 169 /// \brief Build a result that refers to a keyword or symbol. 170 Result(const char *Keyword, unsigned Rank) 171 : Kind(RK_Keyword), Keyword(Keyword), Rank(Rank), Hidden(false) { } 172 173 /// \brief Retrieve the declaration stored in this result. 174 NamedDecl *getDeclaration() const { 175 assert(Kind == RK_Declaration && "Not a declaration result"); 176 return Declaration; 177 } 178 179 /// \brief Retrieve the keyword stored in this result. 180 const char *getKeyword() const { 181 assert(Kind == RK_Keyword && "Not a keyword result"); 182 return Keyword; 183 } 184 185 /// \brief Create a new code-completion string that describes how to insert 186 /// this result into a program. 187 CodeCompletionString *CreateCodeCompletionString(Sema &S); 188 }; 189 190 /// \brief Deregisters and destroys this code-completion consumer. 191 virtual ~CodeCompleteConsumer(); 192 193 /// \name Code-completion callbacks 194 //@{ 195 /// \brief Process the finalized code-completion results. 196 virtual void ProcessCodeCompleteResults(Result *Results, 197 unsigned NumResults) { } 198 //@} 199}; 200 201/// \brief A simple code-completion consumer that prints the results it 202/// receives in a simple format. 203class PrintingCodeCompleteConsumer : public CodeCompleteConsumer { 204 /// \brief The semantic-analysis object to which this code-completion 205 /// consumer is attached. 206 Sema &SemaRef; 207 208 /// \brief The raw output stream. 209 llvm::raw_ostream &OS; 210 211public: 212 /// \brief Create a new printing code-completion consumer that prints its 213 /// results to the given raw output stream. 214 PrintingCodeCompleteConsumer(Sema &S, llvm::raw_ostream &OS) 215 : SemaRef(S), OS(OS) { } 216 217 /// \brief Prints the finalized code-completion results. 218 virtual void ProcessCodeCompleteResults(Result *Results, 219 unsigned NumResults); 220}; 221 222} // end namespace clang 223 224#endif // LLVM_CLANG_SEMA_CODECOMPLETECONSUMER_H 225