mirror of
https://github.com/apple/swift.git
synced 2025-12-14 20:36:38 +01:00
253 lines
9.0 KiB
Plaintext
253 lines
9.0 KiB
Plaintext
This documents the Request/Response API as it is currently.
|
|
For specific details related to Swift see SwiftSupport.txt
|
|
|
|
The format is
|
|
{
|
|
<KEY>: (type) // comments
|
|
...
|
|
}
|
|
|
|
"{ }" indicates dictionary
|
|
"[ ]" indicates array.
|
|
"[opt]" indicates optional key
|
|
|
|
Specific UIDs are written as <UID string>
|
|
|
|
|
|
================================================
|
|
Requests
|
|
================================================
|
|
|
|
=== Code-Completion ===
|
|
|
|
// If "SourceText" is provided, "SourceFile" is ignored. Not specifying either one is erroneous.
|
|
Request:
|
|
{
|
|
<key.request>: (UID) <source.request.codecomplete>
|
|
[opt] <key.sourcetext>: (string) // source contents
|
|
[opt] <key.sourcefile>: (string) // absolute path to the file
|
|
<key.offset>: (int64) // byte offset of code-completion point inside the source contents
|
|
[opt] <key.compilerargs> [string*] // array of zero or more strings for the compiler arguments
|
|
// e.g ["-sdk", "/path/to/sdk"]
|
|
[opt] <key.not_recommended> [bool] // true if this result is to be avoided, e.g. because
|
|
// the declaration is unavailable.
|
|
}
|
|
|
|
Response:
|
|
{
|
|
<key.results>: (array) [completion-result*] // array of zero or more completion-result dictionaries
|
|
}
|
|
|
|
completion-result ::=
|
|
{
|
|
<key.description>: (string) // text to be displayed in code-completion window
|
|
<key.kind>: (UID) // UID for the declaration kind (function, class, etc.)
|
|
<key.sourcetext>: (string) // text to be inserted in source
|
|
<key.typename>: (string) // text describing the type of the result
|
|
<key.doc.brief>: (string) // brief documentation comment attached to the entity
|
|
<key.context>: (UID) // semantic context of the code completion result
|
|
<key.num_bytes_to_erase>: (int64) // number of bytes to the left of the cursor that should be erased before inserting this completion result
|
|
}
|
|
|
|
Testing:
|
|
$ sourcekitd-test -req=complete -cc-offset=<offset> <file> [-- <compiler args>]
|
|
|
|
|
|
=== Indexing ===
|
|
|
|
// If "SourceText" is provided, "SourceFile" is ignored. Not specifying either one is erroneous.
|
|
// If <key.hash> is provided and matches the hash of the indexed file then the
|
|
// <key.entities> entry will be missing from the response.
|
|
Request:
|
|
{
|
|
<key.request>: (UID) <source.request.indexsource>
|
|
[opt] <key.sourcetext>: (string) // source contents
|
|
[opt] <key.sourcefile>: (string) // absolute path to the file
|
|
[opt] <key.compilerargs> [string*] // array of zero or more strings for the compiler arguments
|
|
// e.g ["-sdk", "/path/to/sdk"]
|
|
[opt] <key.hash>: (string) // known hash for the indexed file
|
|
}
|
|
|
|
// If <key.hash> was provided in the indexing request and matches the hash in the response
|
|
// then the <key.entities> entry will be missing from the response.
|
|
Response:
|
|
{
|
|
<key.dependencies>: (array) [dependency*] // array of zero or more dependencies
|
|
<key.hash>: (string) // Hash associated with the indexed file
|
|
[opt] <key.entities>: (array) [entity*] // array of zero or more top-level indexed entities
|
|
}
|
|
|
|
entity ::=
|
|
{
|
|
<key.kind>: (UID) // UID for the declaration or reference kind (function, class, etc.)
|
|
<key.name>: (string) // displayed name for the entity
|
|
<key.usr>: (string) // USR string for the entity
|
|
<key.line>: (int64) // Line of the position of the entity in source contents.
|
|
<key.column>: (int64) // Column of the position of the entity in source contents.
|
|
[opt] <key.entities>: (array) [entity+] // one or more entities contained in the particular entity (sub-classes, references, etc.)
|
|
[opt] <key.related>: (array) [entity+] // one or more entities related with the particular entity (inherited classes, protocols, etc.)
|
|
}
|
|
|
|
dependency ::=
|
|
{
|
|
<key.kind>: (UID) // UID for the kind (import of a swift module, etc.)
|
|
<key.name>: (string) // displayed name for dependency
|
|
<key.filepath>: (string) // path to the file
|
|
[opt] <key.hash>: (string) // Hash associated with this dependency
|
|
}
|
|
|
|
Testing:
|
|
$ sourcekitd-test -req=index <file> [-- <compiler args>]
|
|
|
|
|
|
=== DocInfo ===
|
|
|
|
{
|
|
"key.request": source.request.docinfo,
|
|
"key.modulename": "Foundation",
|
|
"key.compilerargs": ["-sdk", "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.9.sdk"]
|
|
}
|
|
|
|
This will return:
|
|
|
|
key.sourcetext:
|
|
The pretty-printed module interface in swift source code
|
|
|
|
key.annotations:
|
|
An array of annotations for the tokens of source text, they refer to the text via offset+length entries. This includes syntactic annotations (e.g. keywords) and semantic ones. The semantic ones include the name and USR of the referenced symbol.
|
|
|
|
key.entities:
|
|
A structure of the symbols, similar to what the indexing request returns (a class has its methods as sub-entities, etc.). This includes the function parameters and their types as entities.
|
|
Each entity refers to the range of the original text via offset+length entries.
|
|
|
|
|
|
For source text (you can also pass a source filename with "key.sourcefile")
|
|
|
|
{
|
|
"key.request": source.request.docinfo,
|
|
"key.sourcefile": "/whatever/virtual/path",
|
|
"key.sourcetext": "import Foundation\n var s: NSString\n",
|
|
"key.compilerargs": ["/whatever/virtual/path", "-sdk", "/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX10.10.sdk"]
|
|
}
|
|
|
|
This will return
|
|
|
|
key.annotations
|
|
key.entities
|
|
which will refer to the original text.
|
|
|
|
and
|
|
|
|
key.diagnostics
|
|
for any compiler diagnostics during parsing
|
|
|
|
=== Module interface generation ===
|
|
|
|
Request:
|
|
{
|
|
<key.request>: (UID) <source.request.editor.open.interface>
|
|
<key.name>: (string) // virtual name/path to associate with the interface document
|
|
<key.modulename>: (string) // Full module name, e.g. "Foundation.NSArray"
|
|
[opt] <key.compilerargs> [string*] // array of zero or more strings for the compiler arguments
|
|
// e.g ["-sdk", "/path/to/sdk"]
|
|
}
|
|
|
|
This will return the Swift interface of the specified module.
|
|
|
|
key.sourcetext:
|
|
The pretty-printed module interface in swift source code
|
|
|
|
key.syntaxmap:
|
|
An array of syntactic annotations, same as the one returned for the source.request.editor.open request.
|
|
|
|
key.annotations:
|
|
An array of semantic annotations, same as the one returned for the source.request.editor.open request.
|
|
|
|
|
|
All SourceKit requests that don't modify the source buffer should work on the
|
|
opened document, by passing the associated 'name' for the document.
|
|
|
|
If pointing at a symbol which came from a clang module or the stdlib, then the
|
|
response for the cursor-info request will have an entry for the module name:
|
|
|
|
key.modulename: "<module-name>"
|
|
|
|
Also if there is already a generated-interface document for this module
|
|
previously opened, there will be an entry with the "virtual name" associated
|
|
with this document (from the previous 'editor.open.interface' request):
|
|
|
|
key.module_interface_name: "<virtual name for interface document>"
|
|
|
|
|
|
After 'opening' the module interface, to 'jump' to the location of a declaration
|
|
with a particular USR, use the 'find_usr' request:
|
|
|
|
Request:
|
|
{
|
|
<key.request>: (UID) <source.request.editor.find_usr>
|
|
<key.usr>: (string) // USR to look for.
|
|
<key.sourcefile>: (string) // virtual name/path associated with the interface document
|
|
}
|
|
|
|
This returns the byte offset if the USR is found, or an empty response otherwise:
|
|
|
|
key.offset: <byte offset in the interface source>
|
|
|
|
|
|
================================================
|
|
Diagnostics
|
|
================================================
|
|
|
|
Diagnostic entries occur as part of the responses for editor requests.
|
|
If there is a diagnostic, <key.diagnostics> is present and contains an array
|
|
of diagnostic entries. A diagnostic entry has this format:
|
|
|
|
{
|
|
<key.severity>: (UID) // severity of error
|
|
<key.offset>: (int64) // error location
|
|
<key.description>: (string) // error description
|
|
[opts] <key.fixits>: (array) [fixit+] // one or more entries for fixits
|
|
[opts] <key.ranges>: (array) [range+] // one or more entries for ranges
|
|
[opts] <key.diagnostics>: (array) [diagnostic+] // one or more sub-diagnostic entries
|
|
}
|
|
|
|
severity can be one of:
|
|
source.diagnostic.severity.note
|
|
source.diagnostic.severity.warning
|
|
source.diagnostic.severity.error
|
|
|
|
fixit ::=
|
|
{
|
|
<key.offset>: (int64) // location of the fixit range
|
|
<key.length>: (int64) // length of the fixit range
|
|
<key.sourcetext>: (string) // text to replace the range with
|
|
}
|
|
|
|
range ::=
|
|
{
|
|
<key.offset>: (int64) // location of the range
|
|
<key.length>: (int64) // length of the range
|
|
}
|
|
|
|
sub-diagnostics are only diagnostic notes currently.
|
|
|
|
================================================
|
|
UIDs
|
|
================================================
|
|
|
|
=== Keys ===
|
|
|
|
key.column
|
|
key.compilerargs
|
|
key.description
|
|
key.kind
|
|
key.line
|
|
key.name
|
|
key.offset
|
|
key.results
|
|
key.request
|
|
key.sourcefile
|
|
key.sourcetext
|
|
key.typename
|
|
key.usr
|