Skip to content

[SourceKit] Convert Protocol docs to Markdown #2392

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
May 4, 2016
Merged

[SourceKit] Convert Protocol docs to Markdown #2392

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
338 changes: 338 additions & 0 deletions tools/SourceKit/docs/Protocol.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,338 @@
# The SourceKit Protocol

This documents the request/response API as it is currently implemented.
For specific details related to Swift, see `SwiftSupport.md`.

The protocol is documented in the following format:

```
{
<KEY>: (type) // comments
}
```

- `"{ }"` indicates a dictionary
- `"[ ]"` indicates an array.
- `"[opt]"` indicates an optional key.
- Specific UIDs are written as `<UID string>`.


# Requests

## Code-Completion

SourceKit is capable of providing code completion suggestions. To do so, it
must be given either the path to a file (`key.sourcefile`), or some text
(`key.sourcetext`). `key.sourcefile` is ignored when `key.sourcetext` is also
provided.

### 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"]. If key.sourcefile is provided,
// these must include the path to that file.
[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 -offset=<offset> <file> [-- <compiler args>]
```

For example, to get a code completion suggestion for the 58th character in an
ASCII file at `path/to/file.swift`:

```
$ sourcekitd-test -req=complete -offset=58 /path/to/file.swift -- /path/to/file.swift
```

You could also issue the following request in the `sourcekitd-repl`:

```
$ sourcekitd-repl
Welcome to SourceKit. Type ':help' for assistance.
(SourceKit) {
key.request: source.request.codecomplete,
key.sourcefile: "/path/to/file.swift",
key.offset: 57,
key.compilerargs: ["/path/to/file.swift"]
}
```

## Indexing

SourceKit is capable of "indexing" source code, responding with which ranges
of text contain what kinds of source code. In other words, SourceKit is
capable of telling you that "the source code on line 2, column 9, is a
reference to a struct".

To index source code, SourceKit must be given either the path to a file
(`key.sourcefile`), or some text (`key.sourcetext`). `key.sourcefile` is
ignored when `key.sourcetext` is also provided.

A hash (`key.hash`) may be provided in order to determine whether the source
code has changed since the last time it was indexed. If the provided hash
matches the one generated from the source code, the response will omit entries
that have already been returned.

### 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"]. If key.sourcefile is provided,
// these must include the path to that file.
[opt] <key.hash>: (string) // Known hash for the indexed file, used to determine whether
// the file has changed since the last time it was indexed.
}
```

### 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.
// If the key.hash provided in the request matches the
// one in the response, this key will not be included in
// the response.
}
```

```
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>]
```

For example, to index a file at `path/to/file.swift`:

```
$ sourcekitd-test -req=index /path/to/file.swift -- /path/to/file.swift
```

You could also issue the following request in the `sourcekitd-repl`:

```
$ sourcekitd-repl
Welcome to SourceKit. Type ':help' for assistance.
(SourceKit) {
key.request: source.request.index,
key.sourcefile: "/path/to/file.swift",
key.compilerargs: ["/path/to/file.swift"]
}
```

## 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"]
}
```

### Response

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:

```
{
<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
}
```

Where `key.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`

Loading