| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Clang.Completion
Description
Functions for performing code completion.
To get started with code completion, it's enough to parse a file with
parseSourceFile and pass the TranslationUnit to codeCompleteAt.
This will return a CodeCompleteResults value, from which you can
retrieve a list of completion strings using getResults. Each completion
string in turn consists of a series of chunks, which you can retrieve using
getChunks.
This module is intended to be imported qualified.
- codeCompleteAt :: ClangBase m => TranslationUnit s' -> FilePath -> Int -> Int -> Vector UnsavedFile -> Maybe [CodeCompleteFlags] -> ClangT s m (CodeCompleteResults s)
- data CodeCompleteFlags
- data CodeCompleteResults s
- getResults :: ClangBase m => CodeCompleteResults s' -> ClangT s m [(CompletionString s, CursorKind)]
- data CompletionString s
- sortResults :: ClangBase m => CodeCompleteResults s' -> ClangT s m ()
- getDiagnostics :: ClangBase m => CodeCompleteResults s' -> ClangT s m [Diagnostic s]
- getContexts :: ClangBase m => CodeCompleteResults s' -> ClangT s m [CompletionContext]
- data CompletionContext
- = UnexposedCompletionContext
- | AnyTypeCompletionContext
- | AnyValueCompletionContext
- | ObjCObjectValueCompletionContext
- | ObjCSelectorValueCompletionContext
- | CXXClassTypeValueCompletionContext
- | DotMemberAccessCompletionContext
- | ArrowMemberAccessCompletionContext
- | ObjCPropertyAccessCompletionContext
- | EnumTagCompletionContext
- | UnionTagCompletionContext
- | StructTagCompletionContext
- | ClassTagCompletionContext
- | NamespaceCompletionContext
- | NestedNameSpecifierCompletionContext
- | ObjCInterfaceCompletionContext
- | ObjCProtocolCompletionContext
- | ObjCCategoryCompletionContext
- | ObjCInstanceMessageCompletionContext
- | ObjCClassMessageCompletionContext
- | ObjCSelectorNameCompletionContext
- | MacroNameCompletionContext
- | NaturalLanguageCompletionContext
- getContainerKind :: ClangBase m => CodeCompleteResults s' -> ClangT s m (CursorKind, Bool)
- getContainerUSR :: ClangBase m => CodeCompleteResults s' -> ClangT s m (ClangString s)
- getObjCSelector :: ClangBase m => CodeCompleteResults s' -> ClangT s m (ClangString s)
- getChunks :: ClangBase m => CompletionString s' -> ClangT s m [Chunk s]
- data Chunk s
- = TextChunk ChunkKind (ClangString s)
- | OptionalChunk (CompletionString s)
- data ChunkKind
- = OptionalChunkKind
- | TypedTextChunkKind
- | TextChunkKind
- | PlaceholderChunkKind
- | InformativeChunkKind
- | CurrentParameterChunkKind
- | LeftParenChunkKind
- | RightParenChunkKind
- | LeftBracketChunkKind
- | RightBracketChunkKind
- | LeftBraceChunkKind
- | RightBraceChunkKind
- | LeftAngleChunkKind
- | RightAngleChunkKind
- | CommaChunkKind
- | ResultTypeChunkKind
- | ColonChunkKind
- | SemiColonChunkKind
- | EqualChunkKind
- | HorizontalSpaceChunkKind
- | VerticalSpaceChunkKind
- getPriority :: ClangBase m => CompletionString s' -> ClangT s m Int
- getAvailability :: ClangBase m => CompletionString s' -> ClangT s m AvailabilityKind
- getAnnotations :: ClangBase m => CompletionString s' -> ClangT s m [ClangString s]
- getParent :: ClangBase m => CompletionString s' -> ClangT s m (ClangString s)
- getBriefComment :: ClangBase m => CompletionString s' -> ClangT s m (ClangString s)
Code completion
Arguments
| :: ClangBase m | |
| => TranslationUnit s' | The translation unit in which code completion should occur.
The source files for this translation unit need not be
completely up-to-date (and the contents of those source files
may be overridden via the |
| -> FilePath | The name of the source file where code completion should be performed. This filename may be any file included in the translation unit. |
| -> Int | The line at which code completion should occur. |
| -> Int | The column at which code completion should occur. Note that the column should point just after the syntactic construct that initiated code completion, and not in the middle of a lexical token. |
| -> Vector UnsavedFile | Files that have not yet been saved to disk
but may be required for parsing or code completion, including
the contents of those files. The contents and name of these
files (as specified by |
| -> Maybe [CodeCompleteFlags] | Extra options that control the behavior of code
completion, or |
| -> ClangT s m (CodeCompleteResults s) |
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 CodeCompleteResults value.
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.
data CodeCompleteFlags Source
Flags that can be used to modify the behavior of codeCompleteAt.
IncludeMacros: Whether to include macros within the set of code completions returned.IncludeCodePatterns: Whether to include code patterns for language constructs within the set of code completions, e.g.,forloops.IncludeBriefComments: Whether to include brief documentation within the set of code completions returned.
Constructors
| IncludeMacros | |
| IncludeCodePatterns | |
| IncludeBriefComments |
Completion results
getResults :: ClangBase m => CodeCompleteResults s' -> ClangT s m [(CompletionString s, CursorKind)] Source
Retrieves a list of code completion results.
The first element of each tuple is the completion string, which describes how to insert
this result into the editing buffer. Use getChunks to analyze it further.
The second element of each tuple is the kind of entity that this completion refers to. It will be a macro, keyword, or declaration describing the entity that the completion is referring to.
data CompletionString s Source
A semantic string that describes a code completion result.
A CompletionString 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.
See ChunkKind for more details about the role each kind of chunk plays.
Instances
sortResults :: ClangBase m => CodeCompleteResults s' -> ClangT s m () Source
Sort the provided code completion results in case-insensitive alphabetical order.
getDiagnostics :: ClangBase m => CodeCompleteResults s' -> ClangT s m [Diagnostic s] Source
Retrieves the diagnostics associated with the given code completion.
getContexts :: ClangBase m => CodeCompleteResults s' -> ClangT s m [CompletionContext] Source
Determines which kinds of completions are appropriate for the context of the given code completion.
data CompletionContext Source
Contexts under which completion may occur. Multiple contexts may be present at the same time.
UnexposedCompletionContext: The context for completions is unexposed, as only Clang results should be included.AnyTypeCompletionContext: Completions for any possible type should be included in the results.AnyValueCompletionContext: Completions for any possible value (variables, function calls, etc.) should be included in the results.ObjCObjectValueCompletionContext: Completions for values that resolve to an Objective-C object should be included in the results.ObjCSelectorValueCompletionContext: Completions for values that resolve to an Objective-C selector should be included in the results.CXXClassTypeValueCompletionContext: Completions for values that resolve to a C++ class type should be included in the results.DotMemberAccessCompletionContext: Completions for fields of the member being accessed using the dot operator should be included in the results.ArrowMemberAccessCompletionContext: Completions for fields of the member being accessed using the arrow operator should be included in the results.ObjCPropertyAccessCompletionContext: Completions for properties of the Objective-C object being accessed using the dot operator should be included in the results.EnumTagCompletionContext: Completions for enum tags should be included in the results.UnionTagCompletionContext: Completions for union tags should be included in the results.StructTagCompletionContext: Completions for struct tags should be included in the results.ClassTagCompletionContext: Completions for C++ class names should be included in the results.NamespaceCompletionContext: Completions for C++ namespaces and namespace aliases should be included in the results.NestedNameSpecifierCompletionContext: Completions for C++ nested name specifiers should be included in the results.ObjCInterfaceCompletionContext: Completions for Objective-C interfaces (classes) should be included in the results.ObjCProtocolCompletionContext: Completions for Objective-C protocols should be included in the results.ObjCCategoryCompletionContext: Completions for Objective-C categories should be included in the results.ObjCInstanceMessageCompletionContext: Completions for Objective-C instance messages should be included in the results.ObjCClassMessageCompletionContext: Completions for Objective-C class messages should be included in the results.ObjCSelectorNameCompletionContext: Completions for Objective-C selector names should be included in the results.MacroNameCompletionContext: Completions for preprocessor macro names should be included in the results.NaturalLanguageCompletionContext: Natural language completions should be included in the results.
Constructors
getContainerKind :: ClangBase m => CodeCompleteResults s' -> ClangT s m (CursorKind, Bool) Source
Returns a cursor kind for the container associated with the given code
completion. Only contexts like member accesses and Objective-C message sends
have containers; for other kinds of contexts, a cursor kind of
InvalidCodeCursor is returned.
The second element of the result tuple is a boolean indicating whether libclang
has incomplete information about the container. A True value indicates that
information about the container is incomplete.
getContainerUSR :: ClangBase m => CodeCompleteResults s' -> ClangT s m (ClangString s) Source
Given a code completion context, returns a Clang.USR for the appropriate container. Only contexts like member accesses and Objective-C message sends have containers; for other kinds of contexts, the empty string is returned.
getObjCSelector :: ClangBase m => CodeCompleteResults s' -> ClangT s m (ClangString s) Source
Returns the currently-entered selector for an Objective-C message
send, formatted like "initWithFoo:bar:". This function is only guaranteed
to return a non-empty string if the completion context is an Objective-C
instance message or class message send, which you can check with getContexts.
Completion strings
getChunks :: ClangBase m => CompletionString s' -> ClangT s m [Chunk s] Source
Retrieves the chunks within a completion string.
Each "chunk" contains either a piece of text with a specific "kind" that describes how that text should be interpreted by the client, or another completion string.
The completion string is a template that describes not only the completion itself, but also information about how it should be presented to the user. It is divided into a list of chunks, with each kind of chunk playing a different role in the template.
Constructors
| TextChunk ChunkKind (ClangString s) | |
| OptionalChunk (CompletionString s) |
Describes a single piece of text within a code completion string.
OptionalChunkKind: A code completion string that describes "optional" text that could be a part of the template (but is not required). This is the only kind of chunk that has a code completion string for its representation. The code completion string describes an describes an additional part of the template that is completely optional. For example, optional chunks can be used to describe the placeholders for arguments that match up with defaulted function parameters.TypedTextChunkKind: 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.TextChunkKind: 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.PlaceholderChunkKind: 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.InformativeChunkKind: 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.CurrentParameterChunkKind: Text that describes the current parameter when code completion is referring to a 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 "add(", where the code completion point is after the "(", the code completion string will contain a "current parameter" chunk for "int x", indicating that the current argument will initialize that parameter. After typing further, to "add(17", (where the code completion point is after the ","), the code completion string will contain a "current parameter" chunk to "int y".LeftParenChunkKind: A left parenthesis ('('), used to initiate a function call or signal the beginning of a function parameter list.RightParenChunkKind: A right parenthesis (')'), used to finish a function call or signal the end of a function parameter list.LeftBracketChunkKind: A left bracket ('[').RightBracketChunkKind: A right bracket (']').LeftBraceChunkKind: A left brace ('{').RightBraceChunkKind: A right brace ('}').LeftAngleChunkKind: A left angle bracket ('<').RightAngleChunkKind: A right angle bracket ('>').CommaChunkKind: A comma separator (',').ResultTypeChunkKind: 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.ColonChunkKind: A colon (':').SemiColonChunkKind: A semicolon (';').EqualChunkKind: An '=' sign.HorizontalSpaceChunkKind: Horizontal space (' ').VerticalSpaceChunkKind: Vertical space ('\n'), after which it is generally a good idea to perform indentation.
Constructors
getPriority :: ClangBase m => CompletionString s' -> ClangT s m Int Source
Determines the priority of this code completion string.
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. Smaller values indicate more likely completions.
getAvailability :: ClangBase m => CompletionString s' -> ClangT s m AvailabilityKind Source
Determines the availability of the entity that this code completion string refers to.
getAnnotations :: ClangBase m => CompletionString s' -> ClangT s m [ClangString s] Source
Retrieves the annotations associated with the given completion string.
getParent :: ClangBase m => CompletionString s' -> ClangT s m (ClangString s) Source
Retrieves 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. A completion string representing a method on the NSObject class might have a parent context of "NSObject".
getBriefComment :: ClangBase m => CompletionString s' -> ClangT s m (ClangString s) Source
Retrieves the brief documentation comment attached to the declaration that corresponds to the given completion string.