Code completion involves taking an (incomplete) source file, along with knowledge of where the user is actively editing that file, and suggesting syntactically- and semantically-valid constructs that the user might want to use at that particular point in the source code. More...
clang_codeCompleteAt() . Code completion involves taking an (incomplete) source file, along with knowledge of where the user is actively editing that file, and suggesting syntactically- and semantically-valid constructs that the user might want to use at that particular point in the source code.
These data structures and routines provide support for code completion.
A semantic string that describes a code-completion result.
A semantic string that describes the formatting of a code-completion result as a single "template" of text that should be inserted into the source buffer when a particular code-completion result is selected. Each semantic string is made up of some number of "chunks", each of which contains some text along with a description of what that text means, e.g., the name of the entity being referenced, whether the text chunk is part of the template, or whether it is a "placeholder" that the user should replace with actual code,of a specific kind. See CXCompletionChunkKind for a description of the different kinds of chunks.
Flags that can be passed to clang_codeCompleteAt() to modify its behavior.
The enumerators in this enumeration can be bitwise-OR'd together to provide multiple options to clang_codeCompleteAt() .
| Enumerator | |
|---|---|
| CXCodeComplete_IncludeMacros | Whether to include macros within the set of code completions returned. |
| CXCodeComplete_IncludeCodePatterns | Whether to include code patterns for language constructs within the set of code completions, e.g., for loops. |
| CXCodeComplete_IncludeBriefComments | Whether to include brief documentation within the set of code completions returned. |
| CXCodeComplete_SkipPreamble | Whether to speed up completion by omitting top- or namespace-level entities defined in the preamble. There's no guarantee any particular entity is omitted. This may be useful if the headers are indexed externally. |
| CXCodeComplete_IncludeCompletionsWithFixIts | Whether to include completions with small fix-its, e.g. change '.' to '->' on member access, etc. |
Describes a single piece of text within a code-completion string.
Each "chunk" within a code-completion string (CXCompletionString ) is either a piece of text with a specific "kind" that describes how that text should be interpreted by the client or is another completion string.
| Enumerator | |
|---|---|
| CXCompletionChunk_Optional | A code-completion string that describes "optional" text that could be a part of the template (but is not required). The Optional chunk is the only kind of chunk that has a code-completion string for its representation, which is accessible via void f(int x, float y = 3.14, double z = 2.71828);
The code-completion string for this function would contain:
There are many ways to handle Optional chunks. Two simple approaches are:
|
| CXCompletionChunk_TypedText | Text that a user would be expected to type to get this code-completion result. There will be exactly one "typed text" chunk in a semantic string, which will typically provide the spelling of a keyword or the name of a declaration that could be used at the current code point. Clients are expected to filter the code-completion results based on the text in this chunk. |
| CXCompletionChunk_Text | Text that should be inserted as part of a code-completion result. A "text" chunk represents text that is part of the template to be inserted into user code should this particular code-completion result be selected. |
| CXCompletionChunk_Placeholder | Placeholder text that should be replaced by the user. A "placeholder" chunk marks a place where the user should insert text into the code-completion template. For example, placeholders might mark the function parameters for a function declaration, to indicate that the user should provide arguments for each of those parameters. The actual text in a placeholder is a suggestion for the text to display before the user replaces the placeholder with real code. |
| CXCompletionChunk_Informative | Informative text that should be displayed but never inserted as part of the template. An "informative" chunk contains annotations that can be displayed to help the user decide whether a particular code-completion result is the right option, but which is not part of the actual template to be inserted by code completion. |
| CXCompletionChunk_CurrentParameter | Text that describes the current parameter when code-completion is referring to function call, message send, or template specialization. A "current parameter" chunk occurs when code-completion is providing information about a parameter corresponding to the argument at the code-completion point. For example, given a function int add(int x, int y);
and the source code |
| CXCompletionChunk_LeftParen | A left parenthesis ('('), used to initiate a function call or signal the beginning of a function parameter list. |
| CXCompletionChunk_RightParen | A right parenthesis (')'), used to finish a function call or signal the end of a function parameter list. |
| CXCompletionChunk_LeftBracket | A left bracket ('['). |
| CXCompletionChunk_RightBracket | A right bracket (']'). |
| CXCompletionChunk_LeftBrace | A left brace ('{'). |
| CXCompletionChunk_RightBrace | A right brace ('}'). |
| CXCompletionChunk_LeftAngle | A left angle bracket ('<'). |
| CXCompletionChunk_RightAngle | A right angle bracket ('>'). |
| CXCompletionChunk_Comma | A comma separator (','). |
| CXCompletionChunk_ResultType | Text that specifies the result type of a given result. This special kind of informative chunk is not meant to be inserted into the text buffer. Rather, it is meant to illustrate the type that an expression using the given completion string would have. |
| CXCompletionChunk_Colon | A colon (':'). |
| CXCompletionChunk_SemiColon | A semicolon (';'). |
| CXCompletionChunk_Equal | An '=' sign. |
| CXCompletionChunk_HorizontalSpace | Horizontal space (' '). |
| CXCompletionChunk_VerticalSpace | Vertical space ('\n'), after which it is generally a good idea to perform indentation. |
Bits that represent the context under which completion is occurring.
The enumerators in this enumeration may be bitwise-OR'd together if multiple contexts are occurring simultaneously.
| Enumerator | |
|---|---|
| CXCompletionContext_Unexposed | The context for completions is unexposed, as only Clang results should be included. (This is equivalent to having no context bits set.) |
| CXCompletionContext_AnyType | Completions for any possible type should be included in the results. |
| CXCompletionContext_AnyValue | Completions for any possible value (variables, function calls, etc.) should be included in the results. |
| CXCompletionContext_ObjCObjectValue | Completions for values that resolve to an Objective-C object should be included in the results. |
| CXCompletionContext_ObjCSelectorValue | Completions for values that resolve to an Objective-C selector should be included in the results. |
| CXCompletionContext_CXXClassTypeValue | Completions for values that resolve to a C++ class type should be included in the results. |
| CXCompletionContext_DotMemberAccess | Completions for fields of the member being accessed using the dot operator should be included in the results. |
| CXCompletionContext_ArrowMemberAccess | Completions for fields of the member being accessed using the arrow operator should be included in the results. |
| CXCompletionContext_ObjCPropertyAccess | Completions for properties of the Objective-C object being accessed using the dot operator should be included in the results. |
| CXCompletionContext_EnumTag | Completions for enum tags should be included in the results. |
| CXCompletionContext_UnionTag | Completions for union tags should be included in the results. |
| CXCompletionContext_StructTag | Completions for struct tags should be included in the results. |
| CXCompletionContext_ClassTag | Completions for C++ class names should be included in the results. |
| CXCompletionContext_Namespace | Completions for C++ namespaces and namespace aliases should be included in the results. |
| CXCompletionContext_NestedNameSpecifier | Completions for C++ nested name specifiers should be included in the results. |
| CXCompletionContext_ObjCInterface | Completions for Objective-C interfaces (classes) should be included in the results. |
| CXCompletionContext_ObjCProtocol | Completions for Objective-C protocols should be included in the results. |
| CXCompletionContext_ObjCCategory | Completions for Objective-C categories should be included in the results. |
| CXCompletionContext_ObjCInstanceMessage | Completions for Objective-C instance messages should be included in the results. |
| CXCompletionContext_ObjCClassMessage | Completions for Objective-C class messages should be included in the results. |
| CXCompletionContext_ObjCSelectorName | Completions for Objective-C selector names should be included in the results. |
| CXCompletionContext_MacroName | Completions for preprocessor macro names should be included in the results. |
| CXCompletionContext_NaturalLanguage | Natural language completions should be included in the results. |
| CXCompletionContext_IncludedFile | #include file completions should be included in the results. |
| CXCompletionContext_Unknown | The current context is unknown, so set all contexts. |
Perform code completion at a given location in a translation unit.
This function performs code completion at a particular file, line, and column within source code, providing results that suggest potential code snippets based on the context of the completion. The basic model for code completion is that Clang will parse a complete source file, performing syntax checking up to the location where code-completion has been requested. At that point, a special code-completion token is passed to the parser, which recognizes this token and determines, based on the current location in the C/Objective-C/C++ grammar and the state of semantic analysis, what completions to provide. These completions are returned via a new CXCodeCompleteResults structure.
Code completion itself is meant to be triggered by the client when the user types punctuation characters or whitespace, at which point the code-completion location will coincide with the cursor. For example, if p is a pointer, code-completion might be triggered after the "-" and then after the ">" in p->. When the code-completion location is after the ">", the completion results will provide, e.g., the members of the struct that "p" points to. The client is responsible for placing the cursor at the beginning of the token currently being typed, then filtering the results based on the contents of the token. For example, when code-completing for the expression p->get, the client should provide the location just after the ">" (e.g., pointing at the "g") to this code-completion hook. Then, the client can filter the results based on the current token text ("get"), only showing those results that start with "get". The intent of this interface is to separate the relatively high-latency acquisition of code-completion results from the filtering of results on a per-character basis, which must have a lower latency.
unsaved_files). Cursors referring into the translation unit may be invalidated by this invocation.unsaved_files.clang_defaultCodeCompleteOptions() function returns a default set of code-completion options.CXCodeCompleteResults structure containing code-completion results, which should eventually be freed with clang_disposeCodeCompleteResults() . If code completion fails, returns NULL. References CINDEX_LINKAGE.
Returns the cursor kind for the container for the current code completion context.
The container is only guaranteed to be set for contexts where a container exists (i.e. member accesses or Objective-C message sends); if there is not a container, this function will return CXCursor_InvalidCode.
References CINDEX_LINKAGE.
Returns the USR for the container for the current code completion context.
If there is not a container for the current context, this function will return the empty string.
References CINDEX_LINKAGE.
Determines what completions are appropriate for the context the given code completion.
References CINDEX_LINKAGE.
Retrieve a diagnostic associated with the given code completion.
clang_disposeDiagnostic() . References CINDEX_LINKAGE.
Determine the number of diagnostics produced prior to the location where code completion was performed.
References CINDEX_LINKAGE.
Returns the currently-entered selector for an Objective-C message send, formatted like "initWithFoo:bar:".
Only guaranteed to return a non-empty string for CXCompletionContext_ObjCInstanceMessage and CXCompletionContext_ObjCClassMessage.
Returns a default set of code-completion options that can be passed toclang_codeCompleteAt() .
References CINDEX_LINKAGE.
Free the given set of code-completion results.
References CINDEX_LINKAGE.
Retrieve the annotation associated with the given completion string.
annotation_number, or a NULL string if that annotation is not available. References CINDEX_LINKAGE.
Determine the availability of the entity that this code-completion string refers to.
References CINDEX_LINKAGE.
Retrieve the brief documentation comment attached to the declaration that corresponds to the given completion string.
References CINDEX_LINKAGE.
Retrieve the completion string associated with a particular chunk within a completion string.
chunk_number. References CINDEX_LINKAGE.
Determine the kind of a particular chunk within a completion string.
chunk_number. Retrieve the text associated with a particular chunk within a completion string.
chunk_number. References CINDEX_LINKAGE.
Fix-its that must be applied before inserting the text for the corresponding completion.
By default, clang_codeCompleteAt() only returns completions with empty fix-its. Extra completions with non-empty fix-its should be explicitly requested by setting CXCodeComplete_IncludeCompletionsWithFixIts.
For the clients to be able to compute position of the cursor after applying fix-its, the following conditions are guaranteed to hold for replacement_range of the stored fix-its:
The intuition is that provided fix-its change code around the identifier we complete, but are not allowed to touch the identifier itself or the completion point. One example of completions with corrections are the ones replacing '.' with '->' and vice versa:
std::unique_ptr<std::vector<int>> vec_ptr; In 'vec_ptr.^', one of the completions is 'push_back', it requires replacing '.' with '->'. In 'vec_ptr->^', one of the completions is 'release', it requires replacing '->' with '.'.
References CINDEX_LINKAGE.
Retrieve the number of annotations associated with the given completion string.
Retrieve the number of fix-its for the given completion index.
Calling this makes sense only if CXCodeComplete_IncludeCompletionsWithFixIts option was set.
Retrieve the parent context of the given completion string.
The parent context of a completion string is the semantic parent of the declaration (if any) that the code completion represents. For example, a code completion for an Objective-C method would have the method's class or protocol as its context.
References CINDEX_LINKAGE.
Determine the priority of this code completion.
The priority of a code completion indicates how likely it is that this particular completion is the completion that the user will select. The priority is selected by various internal heuristics.
References CINDEX_LINKAGE.
Retrieve a completion string for an arbitrary declaration or macro definition cursor.
Retrieve the number of chunks in the given code-completion string.
References CINDEX_LINKAGE.
Sort the code-completion results in case-insensitive alphabetical order.
Results. References CINDEX_LINKAGE.