 |
|
 |
|
| Files: |
1 |
|
Branches Taken: |
30.0% |
3 / 10 |
| Generated: |
2010-02-10 01:31 |
|
Branches Executed: |
60.0% |
6 / 10 |
| |
|
Line Coverage: |
96.2% |
51 / 53 |
| |
 |
|
 |
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 type of an entity or, for
65 : /// functions and methods, the return type.
66 : CK_ResultType,
67 : /// \brief A piece of text that describes the parameter that corresponds
68 : /// to the code-completion location within a function call, message send,
69 : /// macro invocation, etc.
70 : CK_CurrentParameter,
71 : /// \brief A left parenthesis ('(').
72 : CK_LeftParen,
73 : /// \brief A right parenthesis (')').
74 : CK_RightParen,
75 : /// \brief A left bracket ('[').
76 : CK_LeftBracket,
77 : /// \brief A right bracket (']').
78 : CK_RightBracket,
79 : /// \brief A left brace ('{').
80 : CK_LeftBrace,
81 : /// \brief A right brace ('}').
82 : CK_RightBrace,
83 : /// \brief A left angle bracket ('<').
84 : CK_LeftAngle,
85 : /// \brief A right angle bracket ('>').
86 : CK_RightAngle,
87 : /// \brief A comma separator (',').
88 : CK_Comma,
89 : /// \brief A colon (':').
90 : CK_Colon,
91 : /// \brief A semicolon (';').
92 : CK_SemiColon,
93 : /// \brief An '=' sign.
94 : CK_Equal,
95 : /// \brief Horizontal whitespace (' ').
96 : CK_HorizontalSpace,
97 : /// \brief Verticle whitespace ('\n' or '\r\n', depending on the
98 : /// platform).
99 : CK_VerticalSpace
100 : };
101 :
102 : /// \brief One piece of the code completion string.
103 5007: struct Chunk {
104 : /// \brief The kind of data stored in this piece of the code completion
105 : /// string.
106 : ChunkKind Kind;
107 :
108 : union {
109 : /// \brief The text string associated with a CK_Text, CK_Placeholder,
110 : /// CK_Informative, or CK_Comma chunk.
111 : /// The string is owned by the chunk and will be deallocated
112 : /// (with delete[]) when the chunk is destroyed.
113 : const char *Text;
114 :
115 : /// \brief The code completion string associated with a CK_Optional chunk.
116 : /// The optional code completion string is owned by the chunk, and will
117 : /// be deallocated (with delete) when the chunk is destroyed.
118 : CodeCompletionString *Optional;
119 : };
120 :
121 5: Chunk() : Kind(CK_Text), Text(0) { }
122 :
123 : Chunk(ChunkKind Kind, llvm::StringRef Text = "");
124 :
125 : /// \brief Create a new text chunk.
126 : static Chunk CreateText(llvm::StringRef Text);
127 :
128 : /// \brief Create a new optional chunk.
129 : static Chunk CreateOptional(std::auto_ptr<CodeCompletionString> Optional);
130 :
131 : /// \brief Create a new placeholder chunk.
132 : static Chunk CreatePlaceholder(llvm::StringRef Placeholder);
133 :
134 : /// \brief Create a new informative chunk.
135 : static Chunk CreateInformative(llvm::StringRef Informative);
136 :
137 : /// \brief Create a new result type chunk.
138 : static Chunk CreateResultType(llvm::StringRef ResultType);
139 :
140 : /// \brief Create a new current-parameter chunk.
141 : static Chunk CreateCurrentParameter(llvm::StringRef CurrentParameter);
142 :
143 : /// \brief Clone the given chunk.
144 : Chunk Clone() const;
145 :
146 : /// \brief Destroy this chunk, deallocating any memory it owns.
147 : void Destroy();
148 : };
149 :
150 : private:
151 : /// \brief The chunks stored in this string.
152 : llvm::SmallVector<Chunk, 4> Chunks;
153 :
154 : CodeCompletionString(const CodeCompletionString &); // DO NOT IMPLEMENT
155 : CodeCompletionString &operator=(const CodeCompletionString &); // DITTO
156 :
157 : public:
158 4224: CodeCompletionString() { }
159 : ~CodeCompletionString();
160 :
161 : typedef llvm::SmallVector<Chunk, 4>::const_iterator iterator;
162 3665: iterator begin() const { return Chunks.begin(); }
163 3665: iterator end() const { return Chunks.end(); }
164 1731: bool empty() const { return Chunks.empty(); }
165 14779: unsigned size() const { return Chunks.size(); }
166 :
167 6789: Chunk &operator[](unsigned I) {
6789: branch 1 taken
0: branch 2 not taken
168 6789: assert(I < size() && "Chunk index out-of-range");
169 6789: return Chunks[I];
170 : }
171 :
172 : const Chunk &operator[](unsigned I) const {
173 : assert(I < size() && "Chunk index out-of-range");
174 : return Chunks[I];
175 : }
176 :
177 : /// \brief Add a new typed-text chunk.
178 : /// The text string will be copied.
179 2409: void AddTypedTextChunk(llvm::StringRef Text) {
180 2409: Chunks.push_back(Chunk(CK_TypedText, Text));
181 2409: }
182 :
183 : /// \brief Add a new text chunk.
184 : /// The text string will be copied.
185 91: void AddTextChunk(llvm::StringRef Text) {
186 91: Chunks.push_back(Chunk::CreateText(Text));
187 91: }
188 :
189 : /// \brief Add a new optional chunk.
190 5: void AddOptionalChunk(std::auto_ptr<CodeCompletionString> Optional) {
191 5: Chunks.push_back(Chunk::CreateOptional(Optional));
192 5: }
193 :
194 : /// \brief Add a new placeholder chunk.
195 : /// The placeholder text will be copied.
196 271: void AddPlaceholderChunk(llvm::StringRef Placeholder) {
197 271: Chunks.push_back(Chunk::CreatePlaceholder(Placeholder));
198 271: }
199 :
200 : /// \brief Add a new informative chunk.
201 : /// The text will be copied.
202 33: void AddInformativeChunk(llvm::StringRef Text) {
203 33: Chunks.push_back(Chunk::CreateInformative(Text));
204 33: }
205 :
206 : /// \brief Add a new result-type chunk.
207 : /// The text will be copied.
208 180: void AddResultTypeChunk(llvm::StringRef ResultType) {
209 180: Chunks.push_back(Chunk::CreateResultType(ResultType));
210 180: }
211 :
212 : /// \brief Add a new current-parameter chunk.
213 : /// The text will be copied.
214 : void AddCurrentParameterChunk(llvm::StringRef CurrentParameter) {
215 : Chunks.push_back(Chunk::CreateCurrentParameter(CurrentParameter));
216 : }
217 :
218 : /// \brief Add a new chunk.
219 3205: void AddChunk(Chunk C) { Chunks.push_back(C); }
220 :
221 : /// \brief Returns the text in the TypedText chunk.
222 : const char *getTypedText() const;
223 :
224 : /// \brief Retrieve a string representation of the code completion string,
225 : /// which is mainly useful for debugging.
226 : std::string getAsString() const;
227 :
228 : /// \brief Clone this code-completion string.
229 : CodeCompletionString *Clone() const;
230 :
231 : /// \brief Serialize this code-completion string to the given stream.
232 : void Serialize(llvm::raw_ostream &OS) const;
233 :
234 : /// \brief Deserialize a code-completion string from the given string.
235 : static CodeCompletionString *Deserialize(const char *&Str,
236 : const char *StrEnd);
237 : };
238 :
239 : llvm::raw_ostream &operator<<(llvm::raw_ostream &OS,
240 : const CodeCompletionString &CCS);
241 :
242 : /// \brief Abstract interface for a consumer of code-completion
243 : /// information.
244 : class CodeCompleteConsumer {
245 : protected:
246 : /// \brief Whether to include macros in the code-completion results.
247 : bool IncludeMacros;
248 :
249 : /// \brief Whether the output format for the code-completion consumer is
250 : /// binary.
251 : bool OutputIsBinary;
252 :
253 : public:
254 : /// \brief Captures a result of code completion.
255 : struct Result {
256 : /// \brief Describes the kind of result generated.
257 : enum ResultKind {
258 : RK_Declaration = 0, //< Refers to a declaration
259 : RK_Keyword, //< Refers to a keyword or symbol.
260 : RK_Macro, //< Refers to a macro
261 : RK_Pattern //< Refers to a precomputed pattern.
262 : };
263 :
264 : /// \brief The kind of result stored here.
265 : ResultKind Kind;
266 :
267 : union {
268 : /// \brief When Kind == RK_Declaration, the declaration we are referring
269 : /// to.
270 : NamedDecl *Declaration;
271 :
272 : /// \brief When Kind == RK_Keyword, the string representing the keyword
273 : /// or symbol's spelling.
274 : const char *Keyword;
275 :
276 : /// \brief When Kind == RK_Pattern, the code-completion string that
277 : /// describes the completion text to insert.
278 : CodeCompletionString *Pattern;
279 :
280 : /// \brief When Kind == RK_Macro, the identifier that refers to a macro.
281 : IdentifierInfo *Macro;
282 : };
283 :
284 : /// \brief Specifiers which parameter (of a function, Objective-C method,
285 : /// macro, etc.) we should start with when formatting the result.
286 : unsigned StartParameter;
287 :
288 : /// \brief Whether this result is hidden by another name.
289 : bool Hidden : 1;
290 :
291 : /// \brief Whether this result was found via lookup into a base class.
292 : bool QualifierIsInformative : 1;
293 :
294 : /// \brief Whether this declaration is the beginning of a
295 : /// nested-name-specifier and, therefore, should be followed by '::'.
296 : bool StartsNestedNameSpecifier : 1;
297 :
298 : /// \brief Whether all parameters (of a function, Objective-C
299 : /// method, etc.) should be considered "informative".
300 : bool AllParametersAreInformative : 1;
301 :
302 : /// \brief If the result should have a nested-name-specifier, this is it.
303 : /// When \c QualifierIsInformative, the nested-name-specifier is
304 : /// informative rather than required.
305 : NestedNameSpecifier *Qualifier;
306 :
307 : /// \brief Build a result that refers to a declaration.
308 : Result(NamedDecl *Declaration,
309 : NestedNameSpecifier *Qualifier = 0,
310 451: bool QualifierIsInformative = false)
311 : : Kind(RK_Declaration), Declaration(Declaration),
312 : StartParameter(0), Hidden(false),
313 : QualifierIsInformative(QualifierIsInformative),
314 : StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
315 451: Qualifier(Qualifier) { }
316 :
317 : /// \brief Build a result that refers to a keyword or symbol.
318 340: Result(const char *Keyword)
319 : : Kind(RK_Keyword), Keyword(Keyword), StartParameter(0),
320 : Hidden(false), QualifierIsInformative(0),
321 : StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
322 340: Qualifier(0) { }
323 :
324 : /// \brief Build a result that refers to a macro.
325 1816: Result(IdentifierInfo *Macro)
326 : : Kind(RK_Macro), Macro(Macro), StartParameter(0),
327 : Hidden(false), QualifierIsInformative(0),
328 : StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
329 1816: Qualifier(0) { }
330 :
331 : /// \brief Build a result that refers to a pattern.
332 132: Result(CodeCompletionString *Pattern)
333 : : Kind(RK_Pattern), Pattern(Pattern), StartParameter(0),
334 : Hidden(false), QualifierIsInformative(0),
335 : StartsNestedNameSpecifier(false), AllParametersAreInformative(false),
336 132: Qualifier(0) { }
337 :
338 : /// \brief Retrieve the declaration stored in this result.
339 : NamedDecl *getDeclaration() const {
340 : assert(Kind == RK_Declaration && "Not a declaration result");
341 : return Declaration;
342 : }
343 :
344 : /// \brief Retrieve the keyword stored in this result.
345 : const char *getKeyword() const {
346 : assert(Kind == RK_Keyword && "Not a keyword result");
347 : return Keyword;
348 : }
349 :
350 : /// \brief Create a new code-completion string that describes how to insert
351 : /// this result into a program.
352 : CodeCompletionString *CreateCodeCompletionString(Sema &S);
353 :
354 : void Destroy();
355 : };
356 :
357 10: class OverloadCandidate {
358 : public:
359 : /// \brief Describes the type of overload candidate.
360 : enum CandidateKind {
361 : /// \brief The candidate is a function declaration.
362 : CK_Function,
363 : /// \brief The candidate is a function template.
364 : CK_FunctionTemplate,
365 : /// \brief The "candidate" is actually a variable, expression, or block
366 : /// for which we only have a function prototype.
367 : CK_FunctionType
368 : };
369 :
370 : private:
371 : /// \brief The kind of overload candidate.
372 : CandidateKind Kind;
373 :
374 : union {
375 : /// \brief The function overload candidate, available when
376 : /// Kind == CK_Function.
377 : FunctionDecl *Function;
378 :
379 : /// \brief The function template overload candidate, available when
380 : /// Kind == CK_FunctionTemplate.
381 : FunctionTemplateDecl *FunctionTemplate;
382 :
383 : /// \brief The function type that describes the entity being called,
384 : /// when Kind == CK_FunctionType.
385 : const FunctionType *Type;
386 : };
387 :
388 : public:
389 10: OverloadCandidate(FunctionDecl *Function)
390 10: : Kind(CK_Function), Function(Function) { }
391 :
392 : OverloadCandidate(FunctionTemplateDecl *FunctionTemplateDecl)
393 : : Kind(CK_FunctionTemplate), FunctionTemplate(FunctionTemplate) { }
394 :
395 : OverloadCandidate(const FunctionType *Type)
396 : : Kind(CK_FunctionType), Type(Type) { }
397 :
398 : /// \brief Determine the kind of overload candidate.
399 10: CandidateKind getKind() const { return Kind; }
400 :
401 : /// \brief Retrieve the function overload candidate or the templated
402 : /// function declaration for a function template.
403 : FunctionDecl *getFunction() const;
404 :
405 : /// \brief Retrieve the function template overload candidate.
406 : FunctionTemplateDecl *getFunctionTemplate() const {
407 : assert(getKind() == CK_FunctionTemplate && "Not a function template");
408 : return FunctionTemplate;
409 : }
410 :
411 : /// \brief Retrieve the function type of the entity, regardless of how the
412 : /// function is stored.
413 : const FunctionType *getFunctionType() const;
414 :
415 : /// \brief Create a new code-completion string that describes the function
416 : /// signature of this overload candidate.
417 : CodeCompletionString *CreateSignatureString(unsigned CurrentArg,
418 : Sema &S) const;
419 : };
420 :
421 : CodeCompleteConsumer() : IncludeMacros(false), OutputIsBinary(false) { }
422 :
423 87: CodeCompleteConsumer(bool IncludeMacros, bool OutputIsBinary)
424 87: : IncludeMacros(IncludeMacros), OutputIsBinary(OutputIsBinary) { }
425 :
426 : /// \brief Whether the code-completion consumer wants to see macros.
427 40: bool includeMacros() const { return IncludeMacros; }
428 :
429 : /// \brief Determine whether the output of this consumer is binary.
430 87: bool isOutputBinary() const { return OutputIsBinary; }
431 :
432 : /// \brief Deregisters and destroys this code-completion consumer.
433 : virtual ~CodeCompleteConsumer();
434 :
435 : /// \name Code-completion callbacks
436 : //@{
437 : /// \brief Process the finalized code-completion results.
438 : virtual void ProcessCodeCompleteResults(Sema &S, Result *Results,
439 0: unsigned NumResults) { }
440 :
441 : /// \param S the semantic-analyzer object for which code-completion is being
442 : /// done.
443 : ///
444 : /// \param CurrentArg the index of the current argument.
445 : ///
446 : /// \param Candidates an array of overload candidates.
447 : ///
448 : /// \param NumCandidates the number of overload candidates
449 : virtual void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
450 : OverloadCandidate *Candidates,
451 0: unsigned NumCandidates) { }
452 : //@}
453 : };
454 :
455 : /// \brief A simple code-completion consumer that prints the results it
456 : /// receives in a simple format.
36: branch 1 taken
0: branch 2 not taken
0: branch 5 not taken
0: branch 6 not taken
457 36: class PrintingCodeCompleteConsumer : public CodeCompleteConsumer {
458 : /// \brief The raw output stream.
459 : llvm::raw_ostream &OS;
460 :
461 : public:
462 : /// \brief Create a new printing code-completion consumer that prints its
463 : /// results to the given raw output stream.
464 : PrintingCodeCompleteConsumer(bool IncludeMacros,
465 36: llvm::raw_ostream &OS)
466 36: : CodeCompleteConsumer(IncludeMacros, false), OS(OS) { }
467 :
468 : /// \brief Prints the finalized code-completion results.
469 : virtual void ProcessCodeCompleteResults(Sema &S, Result *Results,
470 : unsigned NumResults);
471 :
472 : virtual void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
473 : OverloadCandidate *Candidates,
474 : unsigned NumCandidates);
475 : };
476 :
477 : /// \brief A code-completion consumer that prints the results it receives
478 : /// in a format that is parsable by the CIndex library.
51: branch 1 taken
0: branch 2 not taken
0: branch 5 not taken
0: branch 6 not taken
479 51: class CIndexCodeCompleteConsumer : public CodeCompleteConsumer {
480 : /// \brief The raw output stream.
481 : llvm::raw_ostream &OS;
482 :
483 : public:
484 : /// \brief Create a new CIndex code-completion consumer that prints its
485 : /// results to the given raw output stream in a format readable to the CIndex
486 : /// library.
487 51: CIndexCodeCompleteConsumer(bool IncludeMacros, llvm::raw_ostream &OS)
488 51: : CodeCompleteConsumer(IncludeMacros, true), OS(OS) { }
489 :
490 : /// \brief Prints the finalized code-completion results.
491 : virtual void ProcessCodeCompleteResults(Sema &S, Result *Results,
492 : unsigned NumResults);
493 :
494 : virtual void ProcessOverloadCandidates(Sema &S, unsigned CurrentArg,
495 : OverloadCandidate *Candidates,
496 : unsigned NumCandidates);
497 : };
498 :
499 : } // end namespace clang
500 :
501 : #endif // LLVM_CLANG_SEMA_CODECOMPLETECONSUMER_H
Generated: 2010-02-10 01:31 by zcov