├── .vscode └── settings.json ├── License.txt ├── README.md ├── extension-cache.md ├── extension-files.md ├── extension-symbol-descriptor.md ├── images └── interaction-diagram.png ├── protocol.md └── versions ├── protocol-1-x.md └── protocol-2-x.md /.vscode/settings.json: -------------------------------------------------------------------------------- 1 | // Place your settings in this file to overwrite default and user settings. 2 | { 3 | "editor.wordWrap": "on" 4 | } -------------------------------------------------------------------------------- /License.txt: -------------------------------------------------------------------------------- 1 | Copyright (c) Microsoft Corporation. 2 | 3 | All rights reserved. 4 | 5 | Distributed under the following terms: 6 | 7 | 1. Documentation is licensed under the Creative Commons Attribution 3.0 United States License. Code is licensed under the MIT License. 8 | 2. This license does not grant you rights to use any trademarks or logos of Microsoft. For Microsoft’s general trademark guidelines, go to http://go.microsoft.com/fwlink/?LinkID=254653 9 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Language Server Protocol 2 | 3 | > **Note:** A blog covering the background and mechanics of the protocol has been added to the [Visual Studio Code](https://code.visualstudio.com/blogs/2016/06/27/common-language-protocol) site. 4 | 5 | The Language Server protocol is used between a tool (the client) and a language smartness provider (the server) to integrate features 6 | like auto complete, goto definition, find all references and alike into the tool. The following diagram illustrates the communication between a tool and the language server. 7 | 8 | ![Interaction diagram](images/interaction-diagram.png) 9 | 10 | The language server maintains semantic information about a program implemented in a particular language. 11 | * When the user opens a document in the tool, it notifies the language server that the document was opened and that the truth of the document is now maintained by the tool in a memory buffer. 12 | * When the user edits the document, the server is notified of the changes and updates the program's semantic information. 13 | * As the user makes changes the language server analyses the document and notifies the tool with any errors and warnings (diagnostics) that it finds. 14 | * When the user requests to go to the definition of a symbol, the client sends a `definition` request to the server. The server responds with the URI of the document and a range inside that document. Based on this information the tool opens the corresponding document at the position where the symbol is defined. 15 | * When the user closes the document, a `didClose` notification is sent, informing the language server that the truth of the file is now on the file system. 16 | 17 | The communication between the Editor/IDE host and the Language Server uses [JSON RPC v2.0](http://www.jsonrpc.org/specification). The protocol supports servers with different capabilities. The first request sent from the Editor/IDE to the language server informs the server about the supported language features. 18 | 19 | The first version of the protocol is based on experiences we gained while 20 | integrating [OmniSharp](http://www.omnisharp.net/) and the [TypeScript Server](https://github.com/Microsoft/TypeScript/tree/master/src/server) into 21 | [VS Code](https://code.visualstudio.com/). See the [history](https://github.com/Microsoft/language-server-protocol/wiki/Protocol-History) section for a brief history on how the protocol evolved. 22 | 23 | ## Contributing 24 | If you are interested in fixing issues like typos or contributing directly to the protocol specification you can either file an issue or provide a pull request 25 | containing the changes to the `protocol.md` file. 26 | 27 | When proposing an extension to the specification, then please refer to an implementation of the proposed changes in a language server. This will help us in understanding the particular use case. 28 | 29 | This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. 30 | 31 | ## The Language Server Protocol 32 | 33 | The file [protocol.md](protocol.md) specifies the language server protocol. 34 | 35 | ## License 36 | [Creative Commons Attribution / MIT](License.txt) 37 | -------------------------------------------------------------------------------- /extension-cache.md: -------------------------------------------------------------------------------- 1 | 2 | # Cache extension to LSP 3 | 4 | The cache extension to the Language Server Protocol (LSP) enables the language server to cache arbitrary data persistently and across multiple workspaces. 5 | Cache items are identified by a string key and have an associated value of arbitrary type. 6 | The client should cache items in a key/value store that optimized for fast look up. 7 | Different workspaces and instances of the same language servers MUST share the same cache namespace, but different language servers MUST NOT. 8 | The client may clear cache items at any time and the language server MUST NOT depend on the presence of a cache item at any time, even directly after a `cache/set` (for example, an item might not have been saved because disk space was low). 9 | 10 | ### Example use case 11 | This allows a language server for example to cache a self-contained definition/references index for each dependency at a specific version inside the workspace and reuse those indexes in multiple workspaces and instances of the language server. 12 | 13 | ### Initialization 14 | 15 | `ClientCapabilities` may contain a new field to indicate client-side support for this extension: 16 | 17 | ```typescript 18 | interface ClientCapabilities { 19 | // ... all fields from the base ClientCapabilities 20 | 21 | /** 22 | * The client provides support for cache/get and cache/set methods 23 | */ 24 | xcacheProvider?: boolean; 25 | } 26 | ``` 27 | 28 | ### Cache Get Request 29 | 30 | The cache get request is sent from the server to the client to request the value of a cache item identified by the provided key. 31 | 32 | _Request_: 33 | * method: 'xcache/get' 34 | * params: `CacheGetParams` defined as follows: 35 | ```typescript 36 | interface CacheGetParams { 37 | /** 38 | * The key that identifies the cache item 39 | */ 40 | key: string; 41 | } 42 | ``` 43 | 44 | _Response_: 45 | * result: `any` the value of the cache item or `null` if it was not found in the cache. 46 | * error: code and message set in case an exception happens during the cache get request. 47 | 48 | ### Cache Set Notification 49 | 50 | The cache set notification is sent from the server to the client to set the value of a cache item identified by the provided key. 51 | This is a intentionally notification and not a request because the server is not supposed to act differently if the cache set failed. 52 | 53 | _Request_: 54 | * method: 'xcache/set' 55 | * params: `CacheSetParams` defined as follows: 56 | ```typescript 57 | interface CacheSetParams { 58 | /** 59 | * The key that identifies the cache item 60 | */ 61 | key: string; 62 | 63 | /** 64 | * The value that should be saved 65 | */ 66 | value: any; 67 | } 68 | ``` 69 | -------------------------------------------------------------------------------- /extension-files.md: -------------------------------------------------------------------------------- 1 | # Files extensions to LSP 2 | 3 | The files extension to the Language Server Protocol (LSP) allows a language server to operate without sharing a physical file system with the client. Instead of consulting its local disk, the language server can query the client for a list of all files and for the contents of specific files. 4 | 5 | Use cases: 6 | 7 | * In some deployment settings, the workspace exists on the client in archived form only, such as a bare Git repository or a .zip file. Using virtual file system access allows the language server to request the minimum set of files necessary to satisfy the request, instead of writing the entire workspace to disk. 8 | * In multitenant deployments, the local disk may not be secure enough to store private data on. (Perhaps an attacker could craft a workspace with malicious `import` statements in code and reveal portions of any file on the file system.) Using a virtual file system enforces that the language server can operate without writing private code files to disk. 9 | * In some deployment settings, language servers must avoid shelling out to untrusted (or sometimes any) programs, for security and performance reasons. Using a virtual file system helps enforce this by making it less likely that another programmer could change the language server to invoke an external program (since it would not be able to read any of the files anyway). 10 | * For testing and reproducibility, it is helpful to isolate the inputs to the language server. This is easier to do if you can guarantee that the language server will not access the file system. 11 | 12 | ## Protocol 13 | 14 | Note that unlike other requests in LSP, these requests are sent by the language server to the client, not vice versa. The client, not the language server, is assumed to have full access to the workspace's contents. 15 | 16 | The language server is allowed to request file paths outside of the workspace root. (This is common for, e.g., system dependencies.) The client may choose whether or not to satisfy these requests. 17 | 18 | ### Initialization 19 | 20 | `ClientCapabilities` may contain two new fields to indicate client-side support for this extension: 21 | 22 | ```typescript 23 | interface ClientCapabilities { 24 | /* ... all fields from the base ClientCapabilities ... */ 25 | 26 | /** 27 | * The client provides support for workspace/xfiles. 28 | */ 29 | xfilesProvider?: boolean; 30 | /** 31 | * The client provides support for textDocument/xcontent. 32 | */ 33 | xcontentProvider?: boolean; 34 | } 35 | ``` 36 | 37 | ### Content Request 38 | 39 | The content request is sent from the server to the client to request the current content of any text document. This allows language servers to operate without accessing the file system directly. 40 | 41 | _Request_: 42 | * method: 'textDocument/xcontent' 43 | * params: `ContentParams` defined as follows: 44 | 45 | ```typescript 46 | interface ContentParams { 47 | /** 48 | * The text document to receive the content for. 49 | */ 50 | textDocument: TextDocumentIdentifier; 51 | } 52 | ``` 53 | 54 | _Response_: 55 | * result: `TextDocumentItem` 56 | * error: code and message set in case an exception occurs 57 | 58 | ### Files Request 59 | 60 | The files request is sent from the server to the client to request a list of all files in the workspace or inside the directory of the `base` parameter, if given. 61 | 62 | A language server can use the result to index files by filtering and doing a content request for each text document of interest. 63 | 64 | _Request_: 65 | * method: 'workspace/xfiles' 66 | * params: `FilesParams` defined as follows: 67 | 68 | ```typescript 69 | interface FilesParams { 70 | /** 71 | * The URI of a directory to search. 72 | * Can be relative to the rootPath. 73 | * If not given, defaults to rootPath. 74 | */ 75 | base?: string; 76 | } 77 | ``` 78 | 79 | _Response_: 80 | * result: `TextDocumentIdentifier[]` 81 | * error: code and message set in case an exception occurs 82 | 83 | Examples: 84 | 85 | Relative (`rootPath` is `file:///some/project`): 86 | 87 | ```json 88 | { 89 | "jsonrpc": "2.0", 90 | "id": 1, 91 | "method": "workspace/xfiles" 92 | } 93 | ``` 94 | 95 | ```json 96 | { 97 | "jsonrpc": "2.0", 98 | "id": 1, 99 | "result": [ 100 | {"uri": "file:///some/project/.gitignore"}, 101 | {"uri": "file:///some/project/composer.json"} 102 | {"uri": "file:///some/project/folder/1.php"}, 103 | {"uri": "file:///some/project/folder/folder/2.php"} 104 | ] 105 | } 106 | ``` 107 | 108 | Absolute: 109 | 110 | ```json 111 | { 112 | "jsonrpc": "2.0", 113 | "id": 1, 114 | "method": "workspace/xfiles", 115 | "params": { 116 | "base": "file:///usr/local/go" 117 | } 118 | } 119 | ``` 120 | 121 | ```json 122 | { 123 | "jsonrpc": "2.0", 124 | "id": 1, 125 | "result": [ 126 | {"uri": "file:///usr/local/go/1.go"}, 127 | {"uri": "file:///usr/local/go/folder/"}, 128 | {"uri": "file:///usr/local/go/folder/2.go"}, 129 | {"uri": "file:///usr/local/go/folder/folder/"}, 130 | {"uri": "file:///usr/local/go/folder/folder/3.go"} 131 | ] 132 | } 133 | ``` 134 | 135 | ## Design notes 136 | 137 | * The protocol uses URIs, not file paths, to be consistent with the rest of LSP. 138 | * Matching the `base` parameter relative to the `rootPath` permits the server to request files outside the workspace even if the workspace is on a remote host and/or uses an arbitrary protocol. 139 | * Usage of `TextDocumentIdentifier` in `workspace/xfiles` allows to easily extend the result with more properties in the future without breaking backward compatibility. 140 | 141 | 142 | ## Known issues 143 | 144 | * There is no way to get directories 145 | * Results have to be filtered on the server side. In the future this request may allow filtering through glob patterns. 146 | -------------------------------------------------------------------------------- /extension-symbol-descriptor.md: -------------------------------------------------------------------------------- 1 | # SymbolDescriptor extensions to LSP 2 | 3 | A `SymbolDescription` contains metadata about a symbol to identify it as uniquely as possible. 4 | 5 | The `SymbolDescriptor` extensions to the Language Server Protocol (LSP) allow a language server to able to interact with `SymbolDescriptor`s via the following methods: 6 | - `textDocument/xdefinition` returns a `SymbolDescriptor` for a symbol at given location 7 | - `workspace/xreferences` locates project wide references to a symbol, given a `SymbolDescriptor` 8 | - `workspace/symbol` search for definitions of a symbol, given a `SymbolDescriptor` 9 | 10 | Use case: clients of a language server can invoke `workspace/xreferences` in order to find references to dependencies. This information can then be stored in a database, which allows the caller to create a "global mapping" of symbols in dependencies to the workspaces they are used in (e.g. to see "how do other people use this symbol?"). A user would perform `textDocument/xdefinition` in order to locate the metadata about the symbol they are interested in and find its references in the database. 11 | 12 | ### Initialization 13 | 14 | `ServerCapabilities` may contain a new field to indicate server-side support for this extension: 15 | 16 | ```typescript 17 | interface ServerCapabilities { 18 | /* ... all fields from the base ServerCapabilities ... */ 19 | 20 | /** 21 | * The server provides workspace references exporting support. 22 | */ 23 | xworkspaceReferencesProvider?: boolean; 24 | 25 | /** 26 | * The server provides extended text document definition support. 27 | */ 28 | xdefinitionProvider?: boolean; 29 | 30 | /** 31 | * The server provides support for querying symbols by properties 32 | * with WorkspaceSymbolParams.symbol 33 | */ 34 | xworkspaceSymbolByProperties?: boolean; 35 | } 36 | ``` 37 | 38 | #### Workspace References Request 39 | 40 | The workspace references request is sent from the client to the server to locate project-wide references to a symbol given its description / metadata. 41 | 42 | _Request_ 43 | * method: 'workspace/xreferences' 44 | * params: `WorkspaceReferencesParams` defined as follows: 45 | ```typescript 46 | /** 47 | * The parameters of a Workspace References Request. 48 | */ 49 | interface WorkspaceReferencesParams { 50 | /** 51 | * Metadata about the symbol that is being searched for. 52 | */ 53 | query: Partial; 54 | 55 | /** 56 | * Hints provides optional hints about where the language server should 57 | * look in order to find the symbol (this is an optimization). It is up to 58 | * the language server to define the schema of this object. 59 | */ 60 | hints: { 61 | [hint: string]: any; 62 | } 63 | } 64 | ``` 65 | 66 | _Response_: 67 | * result: `ReferenceInformation[]` defined as follows: 68 | ```typescript 69 | /** 70 | * Represents information about a reference to programming constructs like 71 | * variables, classes, interfaces, etc. 72 | */ 73 | interface ReferenceInformation { 74 | /** 75 | * The location in the workspace where the `symbol` is referenced. 76 | */ 77 | reference: Location; 78 | 79 | /** 80 | * Metadata about the symbol that can be used to identify or locate its 81 | * definition. 82 | */ 83 | symbol: SymbolDescriptor; 84 | } 85 | ``` 86 | * error: code and message set in case an exception happens during the workspace references request. 87 | 88 | Where `SymbolDescriptor` is defined as follows: 89 | 90 | ```typescript 91 | /** 92 | * Represents information about a programming construct that can be used to 93 | * identify and locate the construct's symbol. The identification does not have 94 | * to be unique, but it should be as unique as possible. It is up to the 95 | * language server to define the schema of this object. 96 | * 97 | * In contrast to `SymbolInformation`, `SymbolDescriptor` includes more concrete, 98 | * language-specific, metadata about the symbol. 99 | */ 100 | interface SymbolDescriptor { 101 | /** 102 | * A list of properties of a symbol that can be used to identify or locate 103 | * it. 104 | */ 105 | [attr: string]: any 106 | } 107 | ``` 108 | 109 | ### Goto Definition Extension Request 110 | 111 | This method is the same as `textDocument/definition`, except that: 112 | 113 | 1. The method returns metadata about the definition (the same metadata that `workspace/xreferences` searches for). 114 | 2. The concrete location to the definition (`location` field) is optional. This is useful because the language server might not be able to resolve a goto definition request to a concrete location (e.g. due to lack of dependencies) but still may know _some_ information about it. 115 | 116 | _Request_ 117 | * method: 'textDocument/xdefinition' 118 | * params: [`TextDocumentPositionParams`](#textdocumentpositionparams) 119 | 120 | _Response_: 121 | * result: `SymbolLocationInformation[]` defined as follows: 122 | ```typescript 123 | interface SymbolLocationInformation { 124 | /* The location where the symbol is defined, if any. */ 125 | location?: Location; 126 | 127 | /** 128 | * Metadata about the symbol that can be used to identify or locate its 129 | * definition. 130 | */ 131 | symbol: SymbolDescriptor; 132 | } 133 | ``` 134 | * error: code and message set in case an exception happens during the definition request. 135 | 136 | 137 | ### Extended Workspace Symbol Request 138 | 139 | The `workspace/symbol` request takes an optional parameter `symbol` that allows you to query by known properties about the symbol. 140 | The string `query` parameter becomes optional. 141 | If both `query` and `symbol` are provided, both should be matched with AND semantics. 142 | 143 | #### Differences between `symbol` and `query` 144 | 145 | `query` | `symbol` 146 | -------------------------------------|------------------------------------ 147 | comes from user input in UI | used programmatically 148 | matches as fuzzily as possible | matches as exact as possible 149 | returns as many results as possible | returns as few results as possible 150 | 151 | 152 | ```typescript 153 | /** 154 | * The parameters of a Workspace Symbol Request. 155 | */ 156 | interface WorkspaceSymbolParams { 157 | /** 158 | * A query string 159 | */ 160 | query?: string; 161 | 162 | /** 163 | * Known properties about the symbol. 164 | */ 165 | symbol?: Partial; 166 | } 167 | ``` 168 | -------------------------------------------------------------------------------- /images/interaction-diagram.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/sourcegraph/language-server-protocol/6f083d7cf03fb2a282b1f940d31c15b400ae7df6/images/interaction-diagram.png -------------------------------------------------------------------------------- /protocol.md: -------------------------------------------------------------------------------- 1 | # Language Server Protocol 2 | 3 | This document describes version 3.0 of the language server protocol. Major goals of the 3.0 version are: 4 | 5 | - add support for client feature flags to support that servers can adapt to different client capabilities. An example is the new `textDocument/willSaveWaitUntil` request which not all clients might be able to support. If the feature is disabled in the client capabilities sent on the initialize request, the server can't rely on receiving the request. 6 | - add support to experiment with new features. The new `ClientCapabilities.experimental` section together with feature flags allow servers to provide experimental feature without the need of ALL clients to adopt them immediatelly. 7 | - servers can more dynamically react to client features. Capabilites can now be registered and unregistered after the initialize request using the new `client/registerCapability` and `client/unregisterCapability`. This for example allows servers to react to settings or configuration changes without a restart. 8 | - add support for `textDocument/willSave` notification and `textDocument/willSaveWaitUntil` request. 9 | - add support for `textDocument/documentLink` request. 10 | - add a `rootUri` property to the initializeParams in favour of the `rootPath` property. 11 | 12 | An implementation for node of the 3.0 version of the protocol can be found [here](https://github.com/Microsoft/vscode-languageserver-node). 13 | 14 | The 2.x version of this document can be found [here](https://github.com/Microsoft/language-server-protocol/blob/master/versions/protocol-2-x.md). 15 | The 1.x version of this document can be found [here](https://github.com/Microsoft/language-server-protocol/blob/master/versions/protocol-1-x.md). 16 | 17 | ## Change Log 18 | 19 | ### 02/28/2017 20 | 21 | * Make the `WorkspaceEdit` changes backwards compatible. 22 | * Updated the specification to correctly describe the breaking changes from 2.x to 3.x around `WorkspaceEdit`and `TextDocumentEdit`. 23 | 24 | ## Messages overview 25 | 26 | General 27 | 28 | * :leftwards_arrow_with_hook: [initialize](#initialize) 29 | * **New** :arrow_right: [initialized](#initialized) 30 | * :leftwards_arrow_with_hook: [shutdown](#shutdown) 31 | * :arrow_right: [exit](#exit) 32 | * :arrow_right: [$/cancelRequest](#cancelRequest) 33 | 34 | Window 35 | 36 | * :arrow_left: [window/showMessage](#window_showMessage) 37 | * :arrow_right_hook: [window/showMessageRequest](#window_showMessageRequest) 38 | * :arrow_left: [window/logMessage](#window_logMessage) 39 | * **New** :arrow_left: [window/progress](#window_progress) 40 | * :arrow_left: [telemetry/event](#telemetry_event) 41 | 42 | >**New** Client 43 | * :arrow_right_hook: [client/registerCapability](#client_registerCapability) 44 | * :arrow_right_hook: [client/unregisterCapability](#client_unregisterCapability) 45 | 46 | Workspace 47 | 48 | * :arrow_right: [workspace/didChangeConfiguration](#workspace_didChangeConfiguration) 49 | * :arrow_right: [workspace/didChangeWatchedFiles](#workspace_didChangeWatchedFiles) 50 | * :leftwards_arrow_with_hook: [workspace/symbol](#workspace_symbol) 51 | * **New** :leftwards_arrow_with_hook: [workspace/executeCommand](#workspace_executeCommand) 52 | * **New** :arrow_right_hook: [workspace/applyEdit](#workspace_applyEdit) 53 | 54 | Document 55 | 56 | * :arrow_left: [textDocument/publishDiagnostics](#textDocument_publishDiagnostics) 57 | * :arrow_right: [textDocument/didOpen](#textDocument_didOpen) 58 | * :arrow_right: [textDocument/didChange](#textDocument_didChange) 59 | * :arrow_right: [textDocument/willSave](#textDocument_willSave) 60 | * **New** :leftwards_arrow_with_hook: [textDocument/willSaveWaitUntil](#textDocument_willSaveWaitUntil) 61 | * **New** :arrow_right: [textDocument/didSave](#textDocument_didSave) 62 | * :arrow_right: [textDocument/didClose](#textDocument_didClose) 63 | * :leftwards_arrow_with_hook: [textDocument/completion](#textDocument_completion) 64 | * :leftwards_arrow_with_hook: [completionItem/resolve](#completionItem_resolve) 65 | * :leftwards_arrow_with_hook: [textDocument/hover](#textDocument_hover) 66 | * :leftwards_arrow_with_hook: [textDocument/signatureHelp](#textDocument_signatureHelp) 67 | * :leftwards_arrow_with_hook: [textDocument/references](#textDocument_references) 68 | * :leftwards_arrow_with_hook: [textDocument/documentHighlight](#textDocument_documentHighlight) 69 | * :leftwards_arrow_with_hook: [textDocument/documentSymbol](#textDocument_documentSymbol) 70 | * :leftwards_arrow_with_hook: [textDocument/formatting](#textDocument_formatting) 71 | * :leftwards_arrow_with_hook: [textDocument/rangeFormatting](#textDocument_rangeFormatting) 72 | * :leftwards_arrow_with_hook: [textDocument/onTypeFormatting](#textDocument_onTypeFormatting) 73 | * :leftwards_arrow_with_hook: [textDocument/definition](#textDocument_definition) 74 | * :leftwards_arrow_with_hook: [textDocument/codeAction](#textDocument_codeAction) 75 | * :leftwards_arrow_with_hook: [textDocument/codeLens](#textDocument_codeLens) 76 | * :leftwards_arrow_with_hook: [codeLens/resolve](#codeLens_resolve) 77 | * :leftwards_arrow_with_hook: [textDocument/documentLink](#textDocument_documentLink) 78 | * :leftwards_arrow_with_hook: [documentLink/resolve](#documentLink_resolve) 79 | * :leftwards_arrow_with_hook: [textDocument/rename](#textDocument_rename) 80 | 81 | ## Base Protocol 82 | 83 | The base protocol consists of a header and a content part (comparable to HTTP). The header and content part are 84 | separated by a '\r\n'. 85 | 86 | ### Header Part 87 | 88 | The header part consists of header fields. Each header field is comprised of a name and a value, 89 | separated by ': ' (a colon and a space). 90 | Each header field is terminated by '\r\n'. 91 | Considering the last header field and the overall header itself are each terminated with '\r\n', 92 | and that at least one header is mandatory, this means that two '\r\n' sequences always 93 | immediately precede the content part of a message. 94 | 95 | Currently the following header fields are supported: 96 | 97 | | Header Field Name | Value Type | Description | 98 | |:------------------|:------------|:------------| 99 | | Content-Length | number | The length of the content part in bytes. This header is required. | 100 | | Content-Type | string | The mime type of the content part. Defaults to application/vscode-jsonrpc; charset=utf-8 | 101 | 102 | The header part is encoded using the 'ascii' encoding. This includes the '\r\n' separating the header and content part. 103 | 104 | ### Content Part 105 | 106 | Contains the actual content of the message. The content part of a message uses [JSON-RPC](http://www.jsonrpc.org/) to describe requests, responses and notifications. The content part is encoded using the charset provided in the Content-Type field. It defaults to `utf-8`, which is the only encoding supported right now. 107 | > **Changed** Prior version of the protocol used the string constant `utf8` which is not a correct encoding constant according to [specification](http://www.iana.org/assignments/character-sets/character-sets.xhtml)). For backwards compatibility it is highly recommended that a client and a server treats the string `utf8` as `utf-8`. 108 | 109 | ### Example: 110 | 111 | ``` 112 | Content-Length: ...\r\n 113 | \r\n 114 | { 115 | "jsonrpc": "2.0", 116 | "id": 1, 117 | "method": "textDocument/didOpen", 118 | "params": { 119 | ... 120 | } 121 | } 122 | ``` 123 | ### Base Protocol JSON structures 124 | 125 | The following TypeScript definitions describe the base [JSON-RPC protocol](http://www.jsonrpc.org/specification): 126 | 127 | #### Abstract Message 128 | 129 | A general message as defined by JSON-RPC. The language server protocol always uses "2.0" as the jsonrpc version. 130 | 131 | ```typescript 132 | interface Message { 133 | jsonrpc: string; 134 | } 135 | ``` 136 | #### RequestMessage 137 | 138 | A request message to describe a request between the client and the server. Every processed request must send a response back to the sender of the request. 139 | 140 | ```typescript 141 | interface RequestMessage extends Message { 142 | 143 | /** 144 | * The request id. 145 | */ 146 | id: number | string; 147 | 148 | /** 149 | * The method to be invoked. 150 | */ 151 | method: string; 152 | 153 | /** 154 | * The method's params. 155 | */ 156 | params?: any 157 | } 158 | ``` 159 | 160 | #### Response Message 161 | 162 | Response Message sent as a result of a request. If a request doesn't provide a result value the receiver of a request still needs to return a response message to conform to the JSON RPC specification. The result property of the ResponseMessage should be set to `null` in this case to signal a successful request. 163 | 164 | ```typescript 165 | interface ResponseMessage extends Message { 166 | /** 167 | * The request id. 168 | */ 169 | id: number | string | null; 170 | 171 | /** 172 | * The result of a request. This can be omitted in 173 | * the case of an error. 174 | */ 175 | result?: any; 176 | 177 | /** 178 | * The error object in case a request fails. 179 | */ 180 | error?: ResponseError; 181 | } 182 | 183 | interface ResponseError { 184 | /** 185 | * A number indicating the error type that occurred. 186 | */ 187 | code: number; 188 | 189 | /** 190 | * A string providing a short description of the error. 191 | */ 192 | message: string; 193 | 194 | /** 195 | * A Primitive or Structured value that contains additional 196 | * information about the error. Can be omitted. 197 | */ 198 | data?: D; 199 | } 200 | 201 | export namespace ErrorCodes { 202 | // Defined by JSON RPC 203 | export const ParseError: number = -32700; 204 | export const InvalidRequest: number = -32600; 205 | export const MethodNotFound: number = -32601; 206 | export const InvalidParams: number = -32602; 207 | export const InternalError: number = -32603; 208 | export const serverErrorStart: number = -32099; 209 | export const serverErrorEnd: number = -32000; 210 | export const ServerNotInitialized: number = -32002; 211 | export const UnknownErrorCode: number = -32001; 212 | 213 | // Defined by the protocol. 214 | export const RequestCancelled: number = -32800; 215 | } 216 | ``` 217 | #### Notification Message 218 | 219 | A notification message. A processed notification message must not send a response back. They work like events. 220 | 221 | ```typescript 222 | interface NotificationMessage extends Message { 223 | /** 224 | * The method to be invoked. 225 | */ 226 | method: string; 227 | 228 | /** 229 | * The notification's params. 230 | */ 231 | params?: any 232 | } 233 | ``` 234 | 235 | #### $ Notifications and Requests 236 | 237 | Notification and requests ids starting with '$/' are messages which are protocol implementation dependent and might not be implementable in all clients or servers. For example if the server implementation uses a single threaded synchronous programming language then there is little a server can do to react to a '$/cancelRequest'. If a server or client receives notifications or requests starting with '$/' it is free to ignore them if they are unknown. 238 | 239 | #### Cancellation Support 240 | 241 | The base protocol offers support for request cancellation. To cancel a request, a notification message with the following properties is sent: 242 | 243 | _Notification_: 244 | * method: '$/cancelRequest' 245 | * params: `CancelParams` defined as follows: 246 | ```typescript 247 | interface CancelParams { 248 | /** 249 | * The request id to cancel. 250 | */ 251 | id: number | string; 252 | } 253 | ``` 254 | 255 | A request that got canceled still needs to return from the server and send a response back. It can not be left open / hanging. This is in line with the JSON RPC protocol that requires that every request sends a response back. In addition it allows for returning partial results on cancel. If the requests returns an error response on cancellation it is advised to set the error code to `ErrorCodes.RequestCancelled`. 256 | 257 | ## Language Server Protocol 258 | 259 | The language server protocol defines a set of JSON-RPC request, response and notification messages which are exchanged using the above base protocol. This section starts describing the basic JSON structures used in the protocol. The document uses TypeScript interfaces to describe these. Based on the basic JSON structures, the actual requests with their responses and the notifications are described. 260 | 261 | The protocol currently assumes that one server serves one tool. There is currently no support in the protocol to share one server between different tools. Such a sharing would require additional protocol to either lock a document to support concurrent editing. 262 | 263 | ### Basic JSON Structures 264 | 265 | #### URI 266 | 267 | URI's are transferred as strings. The URI's format is defined in [http://tools.ietf.org/html/rfc3986](http://tools.ietf.org/html/rfc3986) 268 | 269 | ``` 270 | foo://example.com:8042/over/there?name=ferret#nose 271 | \_/ \______________/\_________/ \_________/ \__/ 272 | | | | | | 273 | scheme authority path query fragment 274 | | _____________________|__ 275 | / \ / \ 276 | urn:example:animal:ferret:nose 277 | ``` 278 | 279 | We also maintain a node module to parse a string into `scheme`, `authority`, `path`, `query`, and `fragment` URI components. The GitHub repository is [https://github.com/Microsoft/vscode-uri](https://github.com/Microsoft/vscode-uri) the npm module is [https://www.npmjs.com/package/vscode-uri](https://www.npmjs.com/package/vscode-uri). 280 | 281 | Many of the interfaces contain fields that correspond to the URI of a document. For clarity, the type of such a field is declared as a `DocumentUri`. Over the wire, it will still be transferred as a string, but this guarantees that the contents of that string can be parsed as a valid URI. 282 | 283 | ```typescript 284 | type DocumentUri = string; 285 | ``` 286 | 287 | #### Text Documents 288 | 289 | The current protocol is talored for textual documents which content can be represented as a string. There is currently no support for binary documents. Positions inside a document (see Position definition below) are expressed as a zero-based line and character offset. To ensure that both client and server split the string into the same line representation the protocol specs the following end of line sequences: '\n', '\r\n' and '\r'. 290 | 291 | ```typescript 292 | export const EOL: string[] = ['\n', '\r\n', '\r']; 293 | ``` 294 | 295 | #### Position 296 | 297 | Position in a text document expressed as zero-based line and character offset. A position is between two characters like an 'insert' cursor in a editor. 298 | 299 | ```typescript 300 | interface Position { 301 | /** 302 | * Line position in a document (zero-based). 303 | */ 304 | line: number; 305 | 306 | /** 307 | * Character offset on a line in a document (zero-based). 308 | */ 309 | character: number; 310 | } 311 | ``` 312 | #### Range 313 | 314 | A range in a text document expressed as (zero-based) start and end positions. A range is comparable to a selection in an editor. Therefore the end position is exclusive. 315 | 316 | ```typescript 317 | interface Range { 318 | /** 319 | * The range's start position. 320 | */ 321 | start: Position; 322 | 323 | /** 324 | * The range's end position. 325 | */ 326 | end: Position; 327 | } 328 | ``` 329 | 330 | #### Location 331 | 332 | Represents a location inside a resource, such as a line inside a text file. 333 | ```typescript 334 | interface Location { 335 | uri: DocumentUri; 336 | range: Range; 337 | } 338 | ``` 339 | 340 | #### Diagnostic 341 | 342 | Represents a diagnostic, such as a compiler error or warning. Diagnostic objects are only valid in the scope of a resource. 343 | 344 | ```typescript 345 | interface Diagnostic { 346 | /** 347 | * The range at which the message applies. 348 | */ 349 | range: Range; 350 | 351 | /** 352 | * The diagnostic's severity. Can be omitted. If omitted it is up to the 353 | * client to interpret diagnostics as error, warning, info or hint. 354 | */ 355 | severity?: number; 356 | 357 | /** 358 | * The diagnostic's code. Can be omitted. 359 | */ 360 | code?: number | string; 361 | 362 | /** 363 | * A human-readable string describing the source of this 364 | * diagnostic, e.g. 'typescript' or 'super lint'. 365 | */ 366 | source?: string; 367 | 368 | /** 369 | * The diagnostic's message. 370 | */ 371 | message: string; 372 | } 373 | ``` 374 | 375 | The protocol currently supports the following diagnostic severities: 376 | 377 | ```typescript 378 | namespace DiagnosticSeverity { 379 | /** 380 | * Reports an error. 381 | */ 382 | export const Error = 1; 383 | /** 384 | * Reports a warning. 385 | */ 386 | export const Warning = 2; 387 | /** 388 | * Reports an information. 389 | */ 390 | export const Information = 3; 391 | /** 392 | * Reports a hint. 393 | */ 394 | export const Hint = 4; 395 | } 396 | ``` 397 | 398 | #### Command 399 | 400 | Represents a reference to a command. Provides a title which will be used to represent a command in the UI. Commands are identitifed using a string identifier and the protocol currently doesn't specify a set of well known commands. So executing a command requires some tool extension code. 401 | 402 | ```typescript 403 | interface Command { 404 | /** 405 | * Title of the command, like `save`. 406 | */ 407 | title: string; 408 | /** 409 | * The identifier of the actual command handler. 410 | */ 411 | command: string; 412 | /** 413 | * Arguments that the command handler should be 414 | * invoked with. 415 | */ 416 | arguments?: any[]; 417 | } 418 | ``` 419 | 420 | #### TextEdit 421 | 422 | A textual edit applicable to a text document. 423 | 424 | ```typescript 425 | interface TextEdit { 426 | /** 427 | * The range of the text document to be manipulated. To insert 428 | * text into a document create a range where start === end. 429 | */ 430 | range: Range; 431 | 432 | /** 433 | * The string to be inserted. For delete operations use an 434 | * empty string. 435 | */ 436 | newText: string; 437 | } 438 | ``` 439 | 440 | If multiple `TextEdit`s are applied to a text document, all text edits describe changes made to the initial document version. Execution wise text edits should applied from the bottom to the top of the text document. Overlapping text edits are not supported. 441 | 442 | >#### New: TextDocumentEdit 443 | 444 | Describes textual changes on a single text document. The text document is referred to as a `VersionedTextDocumentIdentifier` to allow clients to check the text document version before an edit is applied. 445 | 446 | ```typescript 447 | export interface TextDocumentEdit { 448 | /** 449 | * The text document to change. 450 | */ 451 | textDocument: VersionedTextDocumentIdentifier; 452 | 453 | /** 454 | * The edits to be applied. 455 | */ 456 | edits: TextEdit[]; 457 | } 458 | ``` 459 | 460 | #### WorkspaceEdit 461 | 462 | > **Changed** A workspace edit represents changes to many resources managed in the workspace. The edit should either provide `changes` or `documentChanges`. If documentChanges are present they are preferred over `changes` if the client can handle versioned document edits. 463 | 464 | ```typescript 465 | export interface WorkspaceEdit { 466 | /** 467 | * Holds changes to existing resources. 468 | */ 469 | changes?: { [uri: string]: TextEdit[]; }; 470 | 471 | /** 472 | * An array of `TextDocumentEdit`s to express changes to specific a specific 473 | * version of a text document. Whether a client supports versioned document 474 | * edits is expressed via `WorkspaceClientCapabilites.versionedWorkspaceEdit`. 475 | */ 476 | documentChanges?: TextDocumentEdit[]; 477 | } 478 | ``` 479 | 480 | #### TextDocumentIdentifier 481 | 482 | Text documents are identified using a URI. On the protocol level, URIs are passed as strings. The corresponding JSON structure looks like this: 483 | ```typescript 484 | interface TextDocumentIdentifier { 485 | /** 486 | * The text document's URI. 487 | */ 488 | uri: DocumentUri; 489 | } 490 | ``` 491 | 492 | #### TextDocumentItem 493 | 494 | An item to transfer a text document from the client to the server. 495 | 496 | ```typescript 497 | interface TextDocumentItem { 498 | /** 499 | * The text document's URI. 500 | */ 501 | uri: DocumentUri; 502 | 503 | /** 504 | * The text document's language identifier. 505 | */ 506 | languageId: string; 507 | 508 | /** 509 | * The version number of this document (it will strictly increase after each 510 | * change, including undo/redo). 511 | */ 512 | version: number; 513 | 514 | /** 515 | * The content of the opened text document. 516 | */ 517 | text: string; 518 | } 519 | ``` 520 | 521 | #### VersionedTextDocumentIdentifier 522 | 523 | An identifier to denote a specific version of a text document. 524 | 525 | ```typescript 526 | interface VersionedTextDocumentIdentifier extends TextDocumentIdentifier { 527 | /** 528 | * The version number of this document. 529 | */ 530 | version: number; 531 | } 532 | ``` 533 | 534 | #### TextDocumentPositionParams 535 | 536 | Was `TextDocumentPosition` in 1.0 with inlined parameters 537 | 538 | A parameter literal used in requests to pass a text document and a position inside that document. 539 | 540 | ```typescript 541 | interface TextDocumentPositionParams { 542 | /** 543 | * The text document. 544 | */ 545 | textDocument: TextDocumentIdentifier; 546 | 547 | /** 548 | * The position inside the text document. 549 | */ 550 | position: Position; 551 | } 552 | ``` 553 | 554 | > #### New: DocumentFilter 555 | 556 | A document filter denotes a document through properties like `language`, `schema` or `pattern`. Examples are a filter that applies to TypeScript files on disk or a filter the applies to JSON files with name package.json: 557 | ```typescript 558 | { language: 'typescript', scheme: 'file' } 559 | { language: 'json', pattern: '**/package.json' } 560 | ``` 561 | 562 | ```typescript 563 | export interface DocumentFilter { 564 | /** 565 | * A language id, like `typescript`. 566 | */ 567 | language?: string; 568 | 569 | /** 570 | * A Uri [scheme](#Uri.scheme), like `file` or `untitled`. 571 | */ 572 | scheme?: string; 573 | 574 | /** 575 | * A glob pattern, like `*.{ts,js}`. 576 | */ 577 | pattern?: string; 578 | } 579 | ``` 580 | 581 | A document selector is the combination of one or many document filters. 582 | 583 | ```typescript 584 | export type DocumentSelector = DocumentFilter[]; 585 | ``` 586 | 587 | ### Actual Protocol 588 | 589 | This section documents the actual language server protocol. It uses the following format: 590 | 591 | * a header describing the request 592 | * a _Request_: section describing the format of the request sent. The method is a string identifying the request the params are documented using a TypeScript interface 593 | * a _Response_: section describing the format of the response. The result item describes the returned data in case of a success. The error.data describes the returned data in case of an error. Please remember that in case of a failure the response already contains an error.code and an error.message field. These fields are only speced if the protocol forces the use of certain error codes or messages. In cases where the server can decide on these values freely they aren't listed here. 594 | * a _Registration Options_ section decribing the registration option if the request or notification supports dynamic capability registration. 595 | 596 | #### Request, Notification and response ordering 597 | 598 | Responses for requests should be sent in the same order as the requests appear on the server or client side. So for example if a server receives a `textDocument/completion` request and then a `textDocument/signatureHelp` request it should first return the response for the `textDocument/completion` and then the reponse for `textDocument/signatureHelp`. 599 | 600 | How the server internally processes the requests is up to the server implementation. If the server decides to execute them in parallel and this produces correct result the server is free to do so. The server is also allowed to reorder requests and notification if the reordering doesn't affect correctness. 601 | 602 | #### Server lifetime 603 | 604 | The current protocol specification defines that the lifetime of a server is managed by the client (e.g. a tool like VS Code or Emacs). It is up to the client to decide when to start (process vise) and when to shutdown a server. 605 | 606 | #### Initialize Request 607 | 608 | The initialize request is sent as the first request from the client to the server. If the server receives request or notification before the `initialize` request it should act as follows: 609 | 610 | * for a request the respond should be errored with `code: -32002`. The message can be picked by the server. 611 | * notifications should be dropped, except for the exit notification. This will allow the exit a server without an initialize request. 612 | 613 | Until the server has responded to the `initialize` request with an `InitializeResult` the client must not sent any additional requests or notifications to the server. 614 | 615 | >**Updated**: During the `initialize` request the server is allowed to sent the notifications `window/showMessage`, `window/logMessage`, `window/progress` and `telemetry/event` as well as the `window/showMessageRequest` request to the client. 616 | 617 | _Request_: 618 | * method: 'initialize' 619 | * params: `InitializeParams` defined as follows: 620 | 621 | ```typescript 622 | interface InitializeParams { 623 | /** 624 | * The process Id of the parent process that started 625 | * the server. Is null if the process has not been started by another process. 626 | * If the parent process is not alive then the server should exit (see exit notification) its process. 627 | */ 628 | processId: number | null; 629 | 630 | /** 631 | * The rootPath of the workspace. Is null 632 | * if no folder is open. 633 | * 634 | * @deprecated in favour of rootUri. 635 | */ 636 | rootPath?: string | null; 637 | 638 | /** 639 | * The rootUri of the workspace. Is null if no 640 | * folder is open. If both `rootPath` and `rootUri` are set 641 | * `rootUri` wins. 642 | */ 643 | rootUri: DocumentUri | null; 644 | 645 | /** 646 | * User provided initialization options. 647 | */ 648 | initializationOptions?: any; 649 | 650 | /** 651 | * The capabilities provided by the client (editor or tool) 652 | */ 653 | capabilities: ClientCapabilities; 654 | 655 | /** 656 | * The initial trace setting. If omitted trace is disabled ('off'). 657 | */ 658 | trace?: 'off' | 'messages' | 'verbose'; 659 | } 660 | ``` 661 | Where `ClientCapabilities`, `TextDocumentClientCapabilities` and `WorkspaceClientCapabilites` are defined as follows: 662 | 663 | >**New**: `WorkspaceClientCapabilites` define capabilities the editor / tool provides on the workspace: 664 | 665 | ```typescript 666 | /** 667 | * Workspace specific client capabilities. 668 | */ 669 | export interface WorkspaceClientCapabilites { 670 | /** 671 | * The client supports applying batch edits to the workspace by supporting 672 | * the request 'workspace/applyEdit' 673 | */ 674 | applyEdit?: boolean; 675 | 676 | /** 677 | * Capabilities specific to `WorkspaceEdit`s 678 | */ 679 | workspaceEdit?: { 680 | /** 681 | * The client supports versioned document changes in `WorkspaceEdit`s 682 | */ 683 | documentChanges?: boolean; 684 | }; 685 | 686 | /** 687 | * Capabilities specific to the `workspace/didChangeConfiguration` notification. 688 | */ 689 | didChangeConfiguration?: { 690 | /** 691 | * Did change configuration notification supports dynamic registration. 692 | */ 693 | dynamicRegistration?: boolean; 694 | }; 695 | 696 | /** 697 | * Capabilities specific to the `workspace/didChangeWatchedFiles` notification. 698 | */ 699 | didChangeWatchedFiles?: { 700 | /** 701 | * Did change watched files notification supports dynamic registration. 702 | */ 703 | dynamicRegistration?: boolean; 704 | }; 705 | 706 | /** 707 | * Capabilities specific to the `workspace/symbol` request. 708 | */ 709 | symbol?: { 710 | /** 711 | * Symbol request supports dynamic registration. 712 | */ 713 | dynamicRegistration?: boolean; 714 | }; 715 | 716 | /** 717 | * Capabilities specific to the `workspace/executeCommand` request. 718 | */ 719 | executeCommand?: { 720 | /** 721 | * Execute command supports dynamic registration. 722 | */ 723 | dynamicRegistration?: boolean; 724 | }; 725 | } 726 | ``` 727 | 728 | >**New**: `TextDocumentClientCapabilities` define capabilities the editor / tool provides on text documents. 729 | 730 | ```typescript 731 | /** 732 | * Text document specific client capabilities. 733 | */ 734 | export interface TextDocumentClientCapabilities { 735 | 736 | synchronization?: { 737 | /** 738 | * Whether text document synchronization supports dynamic registration. 739 | */ 740 | dynamicRegistration?: boolean; 741 | 742 | /** 743 | * The client supports sending will save notifications. 744 | */ 745 | willSave?: boolean; 746 | 747 | /** 748 | * The client supports sending a will save request and 749 | * waits for a response providing text edits which will 750 | * be applied to the document before it is saved. 751 | */ 752 | willSaveWaitUntil?: boolean; 753 | 754 | /** 755 | * The client supports did save notifications. 756 | */ 757 | didSave?: boolean; 758 | } 759 | 760 | /** 761 | * Capabilities specific to the `textDocument/completion` 762 | */ 763 | completion?: { 764 | /** 765 | * Whether completion supports dynamic registration. 766 | */ 767 | dynamicRegistration?: boolean; 768 | 769 | /** 770 | * The client supports the following `CompletionItem` specific 771 | * capabilities. 772 | */ 773 | completionItem?: { 774 | /** 775 | * Client supports snippets as insert text. 776 | * 777 | * A snippet can define tab stops and placeholders with `$1`, `$2` 778 | * and `${3:foo}`. `$0` defines the final tab stop, it defaults to 779 | * the end of the snippet. Placeholders with equal identifiers are linked, 780 | * that is typing in one will update others too. 781 | */ 782 | snippetSupport?: boolean; 783 | } 784 | }; 785 | 786 | /** 787 | * Capabilities specific to the `textDocument/hover` 788 | */ 789 | hover?: { 790 | /** 791 | * Whether hover supports dynamic registration. 792 | */ 793 | dynamicRegistration?: boolean; 794 | }; 795 | 796 | /** 797 | * Capabilities specific to the `textDocument/signatureHelp` 798 | */ 799 | signatureHelp?: { 800 | /** 801 | * Whether signature help supports dynamic registration. 802 | */ 803 | dynamicRegistration?: boolean; 804 | }; 805 | 806 | /** 807 | * Capabilities specific to the `textDocument/references` 808 | */ 809 | references?: { 810 | /** 811 | * Whether references supports dynamic registration. 812 | */ 813 | dynamicRegistration?: boolean; 814 | }; 815 | 816 | /** 817 | * Capabilities specific to the `textDocument/documentHighlight` 818 | */ 819 | documentHighlight?: { 820 | /** 821 | * Whether document highlight supports dynamic registration. 822 | */ 823 | dynamicRegistration?: boolean; 824 | }; 825 | 826 | /** 827 | * Capabilities specific to the `textDocument/documentSymbol` 828 | */ 829 | documentSymbol?: { 830 | /** 831 | * Whether document symbol supports dynamic registration. 832 | */ 833 | dynamicRegistration?: boolean; 834 | }; 835 | 836 | /** 837 | * Capabilities specific to the `textDocument/formatting` 838 | */ 839 | formatting?: { 840 | /** 841 | * Whether formatting supports dynamic registration. 842 | */ 843 | dynamicRegistration?: boolean; 844 | }; 845 | 846 | /** 847 | * Capabilities specific to the `textDocument/rangeFormatting` 848 | */ 849 | rangeFormatting?: { 850 | /** 851 | * Whether range formatting supports dynamic registration. 852 | */ 853 | dynamicRegistration?: boolean; 854 | }; 855 | 856 | /** 857 | * Capabilities specific to the `textDocument/onTypeFormatting` 858 | */ 859 | onTypeFormatting?: { 860 | /** 861 | * Whether on type formatting supports dynamic registration. 862 | */ 863 | dynamicRegistration?: boolean; 864 | }; 865 | 866 | /** 867 | * Capabilities specific to the `textDocument/definition` 868 | */ 869 | definition?: { 870 | /** 871 | * Whether definition supports dynamic registration. 872 | */ 873 | dynamicRegistration?: boolean; 874 | }; 875 | 876 | /** 877 | * Capabilities specific to the `textDocument/codeAction` 878 | */ 879 | codeAction?: { 880 | /** 881 | * Whether code action supports dynamic registration. 882 | */ 883 | dynamicRegistration?: boolean; 884 | }; 885 | 886 | /** 887 | * Capabilities specific to the `textDocument/codeLens` 888 | */ 889 | codeLens?: { 890 | /** 891 | * Whether code lens supports dynamic registration. 892 | */ 893 | dynamicRegistration?: boolean; 894 | }; 895 | 896 | /** 897 | * Capabilities specific to the `textDocument/documentLink` 898 | */ 899 | documentLink?: { 900 | /** 901 | * Whether document link supports dynamic registration. 902 | */ 903 | dynamicRegistration?: boolean; 904 | }; 905 | 906 | /** 907 | * Capabilities specific to the `textDocument/rename` 908 | */ 909 | rename?: { 910 | /** 911 | * Whether rename supports dynamic registration. 912 | */ 913 | dynamicRegistration?: boolean; 914 | }; 915 | } 916 | ``` 917 | 918 | > **New**: `ClientCapabilities` now define capabilities for dynamic registration, workspace and text document features the client supports. The `experimental` can be used to pass experimential capabilities under development. For future compatibility a `ClientCapabilities` object literal can have more properties set than currently defined. Servers receiving a `ClientCapabilities` object literal with unknown properties should ignore these properties. A missing property should be interpreted as an absence of the capability. If a property is missing that defines sub properties all sub properties should be interpreted as an absence of the capability. 919 | 920 | Client capabilities got introduced with the version 3.0 of the protocol. They therefore only describe capabilities that got introduced in 3.x or later. Capabilities that existed in the 2.x version of the protocol are still mandatory for clients. Clients cannot opt out of providing them. So even if a client omits the `ClientCapabilities.textDocument.synchronization` it is still required that the client provides text document synchronization (e.g. open, changed and close notifications). 921 | 922 | ```typescript 923 | interface ClientCapabilities { 924 | /** 925 | * Workspace specific client capabilities. 926 | */ 927 | workspace?: WorkspaceClientCapabilites; 928 | 929 | /** 930 | * Text document specific client capabilities. 931 | */ 932 | textDocument?: TextDocumentClientCapabilities; 933 | 934 | /** 935 | * Experimental client capabilities. 936 | */ 937 | experimental?: any; 938 | } 939 | ``` 940 | 941 | _Response_: 942 | * result: `InitializeResult` defined as follows: 943 | ```typescript 944 | interface InitializeResult { 945 | /** 946 | * The capabilities the language server provides. 947 | */ 948 | capabilities: ServerCapabilities; 949 | } 950 | ``` 951 | * error.code: 952 | ```typescript 953 | /** 954 | * Known error codes for an `InitializeError`; 955 | */ 956 | export namespace InitializeError { 957 | /** 958 | * If the protocol version provided by the client can't be handled by the server. 959 | * @deprecated This initialize error got replaced by client capabilities. There is 960 | * no version handshake in version 3.0x 961 | */ 962 | export const unknownProtocolVersion: number = 1; 963 | } 964 | ``` 965 | 966 | * error.data: 967 | ```typescript 968 | interface InitializeError { 969 | /** 970 | * Indicates whether the client execute the following retry logic: 971 | * (1) show the message provided by the ResponseError to the user 972 | * (2) user selects retry or cancel 973 | * (3) if user selected retry the initialize method is sent again. 974 | */ 975 | retry: boolean; 976 | } 977 | ``` 978 | 979 | The server can signal the following capabilities: 980 | 981 | ```typescript 982 | /** 983 | * Defines how the host (editor) should sync document changes to the language server. 984 | */ 985 | export namespace TextDocumentSyncKind { 986 | /** 987 | * Documents should not be synced at all. 988 | */ 989 | export const None = 0; 990 | 991 | /** 992 | * Documents are synced by always sending the full content 993 | * of the document. 994 | */ 995 | export const Full = 1; 996 | 997 | /** 998 | * Documents are synced by sending the full content on open. 999 | * After that only incremental updates to the document are 1000 | * send. 1001 | */ 1002 | export const Incremental = 2; 1003 | } 1004 | 1005 | /** 1006 | * Completion options. 1007 | */ 1008 | export interface CompletionOptions { 1009 | /** 1010 | * The server provides support to resolve additional 1011 | * information for a completion item. 1012 | */ 1013 | resolveProvider?: boolean; 1014 | 1015 | /** 1016 | * The characters that trigger completion automatically. 1017 | */ 1018 | triggerCharacters?: string[]; 1019 | } 1020 | /** 1021 | * Signature help options. 1022 | */ 1023 | export interface SignatureHelpOptions { 1024 | /** 1025 | * The characters that trigger signature help 1026 | * automatically. 1027 | */ 1028 | triggerCharacters?: string[]; 1029 | } 1030 | 1031 | /** 1032 | * Code Lens options. 1033 | */ 1034 | export interface CodeLensOptions { 1035 | /** 1036 | * Code lens has a resolve provider as well. 1037 | */ 1038 | resolveProvider?: boolean; 1039 | } 1040 | 1041 | /** 1042 | * Format document on type options 1043 | */ 1044 | export interface DocumentOnTypeFormattingOptions { 1045 | /** 1046 | * A character on which formatting should be triggered, like `}`. 1047 | */ 1048 | firstTriggerCharacter: string; 1049 | 1050 | /** 1051 | * More trigger characters. 1052 | */ 1053 | moreTriggerCharacter?: string[]; 1054 | } 1055 | 1056 | /** 1057 | * Document link options 1058 | */ 1059 | export interface DocumentLinkOptions { 1060 | /** 1061 | * Document links have a resolve provider as well. 1062 | */ 1063 | resolveProvider?: boolean; 1064 | } 1065 | 1066 | /** 1067 | * Execute command options. 1068 | */ 1069 | export interface ExecuteCommandOptions { 1070 | /** 1071 | * The commands to be executed on the server 1072 | */ 1073 | commands: string[] 1074 | } 1075 | 1076 | /** 1077 | * Save options. 1078 | */ 1079 | export interface SaveOptions { 1080 | /** 1081 | * The client is supposed to include the content on save. 1082 | */ 1083 | includeText?: boolean; 1084 | } 1085 | 1086 | export interface TextDocumentSyncOptions { 1087 | /** 1088 | * Open and close notifications are sent to the server. 1089 | */ 1090 | openClose?: boolean; 1091 | /** 1092 | * Change notificatins are sent to the server. See TextDocumentSyncKind.None, TextDocumentSyncKind.Full 1093 | * and TextDocumentSyncKindIncremental. 1094 | */ 1095 | change?: number; 1096 | /** 1097 | * Will save notifications are sent to the server. 1098 | */ 1099 | willSave?: boolean; 1100 | /** 1101 | * Will save wait until requests are sent to the server. 1102 | */ 1103 | willSaveWaitUntil?: boolean; 1104 | /** 1105 | * Save notifications are sent to the server. 1106 | */ 1107 | save?: SaveOptions; 1108 | } 1109 | 1110 | interface ServerCapabilities { 1111 | /** 1112 | * Defines how text documents are synced. Is either a detailed structure defining each notification or 1113 | * for backwards compatibility the TextDocumentSyncKind number. 1114 | */ 1115 | textDocumentSync?: TextDocumentSyncOptions | number; 1116 | /** 1117 | * The server provides hover support. 1118 | */ 1119 | hoverProvider?: boolean; 1120 | /** 1121 | * The server provides completion support. 1122 | */ 1123 | completionProvider?: CompletionOptions; 1124 | /** 1125 | * The server provides signature help support. 1126 | */ 1127 | signatureHelpProvider?: SignatureHelpOptions; 1128 | /** 1129 | * The server provides goto definition support. 1130 | */ 1131 | definitionProvider?: boolean; 1132 | /** 1133 | * The server provides find references support. 1134 | */ 1135 | referencesProvider?: boolean; 1136 | /** 1137 | * The server provides document highlight support. 1138 | */ 1139 | documentHighlightProvider?: boolean; 1140 | /** 1141 | * The server provides document symbol support. 1142 | */ 1143 | documentSymbolProvider?: boolean; 1144 | /** 1145 | * The server provides workspace symbol support. 1146 | */ 1147 | workspaceSymbolProvider?: boolean; 1148 | /** 1149 | * The server provides code actions. 1150 | */ 1151 | codeActionProvider?: boolean; 1152 | /** 1153 | * The server provides code lens. 1154 | */ 1155 | codeLensProvider?: CodeLensOptions; 1156 | /** 1157 | * The server provides document formatting. 1158 | */ 1159 | documentFormattingProvider?: boolean; 1160 | /** 1161 | * The server provides document range formatting. 1162 | */ 1163 | documentRangeFormattingProvider?: boolean; 1164 | /** 1165 | * The server provides document formatting on typing. 1166 | */ 1167 | documentOnTypeFormattingProvider?: DocumentOnTypeFormattingOptions; 1168 | /** 1169 | * The server provides rename support. 1170 | */ 1171 | renameProvider?: boolean; 1172 | /** 1173 | * The server provides document link support. 1174 | */ 1175 | documentLinkProvider?: DocumentLinkOptions; 1176 | /** 1177 | * The server provides execute command support. 1178 | */ 1179 | executeCommandProvider?: ExecuteCommandOptions; 1180 | /** 1181 | * Experimental server capabilities. 1182 | */ 1183 | experimental?: any; 1184 | } 1185 | ``` 1186 | 1187 | >#### New: Initialized Notification 1188 | 1189 | The initialized notification is sent from the client to the server after the client received the result of the `initialize` request but before the client is sending any other request or notification to the server. The server can use the `initialized` notification for example to dynamically register capabilities. 1190 | 1191 | _Notification_: 1192 | * method: 'initialized' 1193 | * params: void 1194 | 1195 | #### Shutdown Request 1196 | 1197 | The shutdown request is sent from the client to the server. It asks the server to shut down, but to not exit (otherwise the response might not be delivered correctly to the client). There is a separate exit notification that asks the server to exit. 1198 | 1199 | _Request_: 1200 | * method: 'shutdown' 1201 | * params: void 1202 | 1203 | _Response_: 1204 | * result: null 1205 | * error: code and message set in case an exception happens during shutdown request. 1206 | 1207 | #### Exit Notification 1208 | 1209 | A notification to ask the server to exit its process. 1210 | The server should exit with `success` code 0 if the shutdown request has been received before; otherwise with `error` code 1. 1211 | 1212 | _Notification_: 1213 | * method: 'exit' 1214 | * params: void 1215 | 1216 | #### ShowMessage Notification 1217 | 1218 | The show message notification is sent from a server to a client to ask the client to display a particular message in the user interface. 1219 | 1220 | _Notification_: 1221 | * method: 'window/showMessage' 1222 | * params: `ShowMessageParams` defined as follows: 1223 | 1224 | ```typescript 1225 | interface ShowMessageParams { 1226 | /** 1227 | * The message type. See {@link MessageType}. 1228 | */ 1229 | type: number; 1230 | 1231 | /** 1232 | * The actual message. 1233 | */ 1234 | message: string; 1235 | } 1236 | ``` 1237 | 1238 | Where the type is defined as follows: 1239 | 1240 | ```typescript 1241 | export namespace MessageType { 1242 | /** 1243 | * An error message. 1244 | */ 1245 | export const Error = 1; 1246 | /** 1247 | * A warning message. 1248 | */ 1249 | export const Warning = 2; 1250 | /** 1251 | * An information message. 1252 | */ 1253 | export const Info = 3; 1254 | /** 1255 | * A log message. 1256 | */ 1257 | export const Log = 4; 1258 | } 1259 | ``` 1260 | 1261 | #### ShowMessage Request 1262 | 1263 | The show message request is sent from a server to a client to ask the client to display a particular message in the user interface. In addition to the show message notification the request allows to pass actions and to wait for an answer from the client. 1264 | 1265 | _Request_: 1266 | * method: 'window/showMessageRequest' 1267 | * params: `ShowMessageRequestParams` defined as follows: 1268 | 1269 | _Response_: 1270 | * result: the selected `MessageActionItem` 1271 | * error: code and message set in case an exception happens during showing a message. 1272 | 1273 | ```typescript 1274 | interface ShowMessageRequestParams { 1275 | /** 1276 | * The message type. See {@link MessageType} 1277 | */ 1278 | type: number; 1279 | 1280 | /** 1281 | * The actual message 1282 | */ 1283 | message: string; 1284 | 1285 | /** 1286 | * The message action items to present. 1287 | */ 1288 | actions?: MessageActionItem[]; 1289 | } 1290 | ``` 1291 | 1292 | Where the `MessageActionItem` is defined as follows: 1293 | 1294 | ```typescript 1295 | interface MessageActionItem { 1296 | /** 1297 | * A short title like 'Retry', 'Open Log' etc. 1298 | */ 1299 | title: string; 1300 | } 1301 | ``` 1302 | 1303 | #### LogMessage Notification 1304 | 1305 | The log message notification is sent from the server to the client to ask the client to log a particular message. 1306 | 1307 | _Notification_: 1308 | * method: 'window/logMessage' 1309 | * params: `LogMessageParams` defined as follows: 1310 | 1311 | ```typescript 1312 | interface LogMessageParams { 1313 | /** 1314 | * The message type. See {@link MessageType} 1315 | */ 1316 | type: number; 1317 | 1318 | /** 1319 | * The actual message 1320 | */ 1321 | message: string; 1322 | } 1323 | ``` 1324 | 1325 | Where type is defined as above. 1326 | 1327 | #### Progress Notification 1328 | 1329 | The progress notification is sent from the server to the client to ask the client to indicate progress. 1330 | 1331 | _Notification_: 1332 | * method: 'window/progress' 1333 | * params: `ProgressParams` defined as follows: 1334 | 1335 | ```typescript 1336 | interface ProgressParams { 1337 | /** 1338 | * A unique identifier to associate multiple progress notifications with the same progress. 1339 | */ 1340 | id: string; 1341 | 1342 | /** 1343 | * Optional title of the progress. 1344 | * If unset, the previous title (if any) is still valid. 1345 | */ 1346 | title?: string; 1347 | 1348 | /** 1349 | * Optional progress message to display. 1350 | * If unset, the previous progress message (if any) is still valid. 1351 | */ 1352 | message?: string; 1353 | 1354 | /** 1355 | * Optional progress percentage to display. 1356 | * If unset, the previous progress percentage (if any) is still valid. 1357 | */ 1358 | percentage?: number; 1359 | 1360 | /** 1361 | * Set to true on the final progress update. 1362 | * No more progress notifications with the same ID should be sent. 1363 | */ 1364 | done?: boolean; 1365 | } 1366 | ``` 1367 | 1368 | #### Telemetry Notification 1369 | 1370 | The telemetry notification is sent from the server to the client to ask the client to log a telemetry event. 1371 | 1372 | _Notification_: 1373 | * method: 'telemetry/event' 1374 | * params: 'any' 1375 | 1376 | > #### New: Register Capability 1377 | 1378 | The `client/registerCapability` request is sent from the server to the client to register for a new capability on the client side. Not all clients need to support dynamic capability registration. A client opts in via the `ClientCapabilities.dynamicRegistration` property. 1379 | 1380 | _Request_: 1381 | * method: 'client/registerCapability' 1382 | * params: `RegistrationParams` 1383 | 1384 | Where `RegistrationParams` are defined as follows: 1385 | 1386 | ```typescript 1387 | /** 1388 | * General paramters to to regsiter for a capability. 1389 | */ 1390 | export interface Registration { 1391 | /** 1392 | * The id used to register the request. The id can be used to deregister 1393 | * the request again. 1394 | */ 1395 | id: string; 1396 | 1397 | /** 1398 | * The method / capability to register for. 1399 | */ 1400 | method: string; 1401 | 1402 | /** 1403 | * Options necessary for the registration. 1404 | */ 1405 | registerOptions?: any; 1406 | } 1407 | 1408 | export interface RegistrationParams { 1409 | registrations: Registration[]; 1410 | } 1411 | ``` 1412 | 1413 | Since most of the registration options require to specify a document selector there is a base interface that can be used. 1414 | 1415 | ```typescript 1416 | export interface TextDocumentRegistrationOptions { 1417 | /** 1418 | * A document selector to identify the scope of the registration. If set to null 1419 | * the document selector provided on the client side will be used. 1420 | */ 1421 | documentSelector: DocumentSelector | null; 1422 | } 1423 | ``` 1424 | 1425 | An example JSON RPC message to register dynamically for the `textDocument/willSaveWaitUntil` feature on the client side is as follows (only details shown): 1426 | 1427 | ```json 1428 | { 1429 | "method": "client/registerCapability", 1430 | "params": { 1431 | "registrations": [ 1432 | { 1433 | "id": "79eee87c-c409-4664-8102-e03263673f6f", 1434 | "method": "textDocument/willSaveWaitUntil", 1435 | "registerOptions": { 1436 | "documentSelector": [ 1437 | { "language": "javascript" } 1438 | ] 1439 | } 1440 | } 1441 | ] 1442 | } 1443 | } 1444 | ``` 1445 | 1446 | This message is sent from the server to the client and after the client has successfully executed the request further `textDocument/willSaveWaitUntil` requests for JavaScript text documents are sent from the client to the server. 1447 | 1448 | _Response_: 1449 | * result: void. 1450 | * error: code and message set in case an exception happens during the request. 1451 | 1452 | > #### New: Unregister Capability 1453 | 1454 | The `client/unregisterCapability` request is sent from the server to the client to unregister a previously register capability. 1455 | 1456 | _Request_: 1457 | * method: 'client/unregisterCapability' 1458 | * params: `UnregistrationParams` 1459 | 1460 | Where `UnregistrationParams` are defined as follows: 1461 | 1462 | ```typescript 1463 | /** 1464 | * General parameters to unregister a capability. 1465 | */ 1466 | export interface Unregistration { 1467 | /** 1468 | * The id used to unregister the request or notification. Usually an id 1469 | * provided during the register request. 1470 | */ 1471 | id: string; 1472 | 1473 | /** 1474 | * The method / capability to unregister for. 1475 | */ 1476 | method: string; 1477 | } 1478 | 1479 | export interface UnregistrationParams { 1480 | unregisterations: Unregistration[]; 1481 | } 1482 | ``` 1483 | 1484 | An example JSON RPC message to unregister the above registered `textDocument/willSaveWaitUntil` feature looks like this: 1485 | 1486 | ```json 1487 | { 1488 | "method": "client/unregisterCapability", 1489 | "params": { 1490 | "unregisterations": [ 1491 | { 1492 | "id": "79eee87c-c409-4664-8102-e03263673f6f", 1493 | "method": "textDocument/willSaveWaitUntil" 1494 | } 1495 | ] 1496 | } 1497 | } 1498 | ``` 1499 | 1500 | #### DidChangeConfiguration Notification 1501 | 1502 | A notification sent from the client to the server to signal the change of configuration settings. 1503 | 1504 | _Notification_: 1505 | * method: 'workspace/didChangeConfiguration', 1506 | * params: `DidChangeConfigurationParams` defined as follows: 1507 | 1508 | ```typescript 1509 | interface DidChangeConfigurationParams { 1510 | /** 1511 | * The actual changed settings 1512 | */ 1513 | settings: any; 1514 | } 1515 | ``` 1516 | 1517 | #### DidOpenTextDocument Notification 1518 | 1519 | The document open notification is sent from the client to the server to signal newly opened text documents. The document's truth is now managed by the client and the server must not try to read the document's truth using the document's uri. 1520 | 1521 | _Notification_: 1522 | * method: 'textDocument/didOpen' 1523 | * params: `DidOpenTextDocumentParams` defined as follows: 1524 | 1525 | ```typescript 1526 | interface DidOpenTextDocumentParams { 1527 | /** 1528 | * The document that was opened. 1529 | */ 1530 | textDocument: TextDocumentItem; 1531 | } 1532 | ``` 1533 | 1534 | _Registration Options_: `TextDocumentRegistrationOptions` 1535 | 1536 | #### DidChangeTextDocument Notification 1537 | 1538 | The document change notification is sent from the client to the server to signal changes to a text document. In 2.0 the shape of the params has changed to include proper version numbers and language ids. 1539 | 1540 | _Notification_: 1541 | * method: 'textDocument/didChange' 1542 | * params: `DidChangeTextDocumentParams` defined as follows: 1543 | 1544 | ```typescript 1545 | interface DidChangeTextDocumentParams { 1546 | /** 1547 | * The document that did change. The version number points 1548 | * to the version after all provided content changes have 1549 | * been applied. 1550 | */ 1551 | textDocument: VersionedTextDocumentIdentifier; 1552 | 1553 | /** 1554 | * The actual content changes. 1555 | */ 1556 | contentChanges: TextDocumentContentChangeEvent[]; 1557 | } 1558 | 1559 | /** 1560 | * An event describing a change to a text document. If range and rangeLength are omitted 1561 | * the new text is considered to be the full content of the document. 1562 | */ 1563 | interface TextDocumentContentChangeEvent { 1564 | /** 1565 | * The range of the document that changed. 1566 | */ 1567 | range?: Range; 1568 | 1569 | /** 1570 | * The length of the range that got replaced. 1571 | */ 1572 | rangeLength?: number; 1573 | 1574 | /** 1575 | * The new text of the range/document. 1576 | */ 1577 | text: string; 1578 | } 1579 | ``` 1580 | 1581 | _Registration Options_: `TextDocumentChangeRegistrationOptions` defined as follows: 1582 | 1583 | ```typescript 1584 | /** 1585 | * Descibe options to be used when registered for text document change events. 1586 | */ 1587 | export interface TextDocumentChangeRegistrationOptions extends TextDocumentRegistrationOptions { 1588 | /** 1589 | * How documents are synced to the server. See TextDocumentSyncKind.Full 1590 | * and TextDocumentSyncKindIncremental. 1591 | */ 1592 | syncKind: number; 1593 | } 1594 | ``` 1595 | 1596 | 1597 | > #### New: WillSaveTextDocument Notification 1598 | 1599 | The document will save notification is sent from the client to the server before the document is actually saved. 1600 | 1601 | _Notification_: 1602 | * method: 'textDocument/willSave' 1603 | * params: `WillSaveTextDocumentParams` defined as follows: 1604 | 1605 | ```typescript 1606 | /** 1607 | * The parameters send in a will save text document notification. 1608 | */ 1609 | export interface WillSaveTextDocumentParams { 1610 | /** 1611 | * The document that will be saved. 1612 | */ 1613 | textDocument: TextDocumentIdentifier; 1614 | 1615 | /** 1616 | * The 'TextDocumentSaveReason'. 1617 | */ 1618 | reason: number; 1619 | } 1620 | 1621 | /** 1622 | * Represents reasons why a text document is saved. 1623 | */ 1624 | export namespace TextDocumentSaveReason { 1625 | 1626 | /** 1627 | * Manually triggered, e.g. by the user pressing save, by starting debugging, 1628 | * or by an API call. 1629 | */ 1630 | export const Manual = 1; 1631 | 1632 | /** 1633 | * Automatic after a delay. 1634 | */ 1635 | export const AfterDelay = 2; 1636 | 1637 | /** 1638 | * When the editor lost focus. 1639 | */ 1640 | export const FocusOut = 3; 1641 | } 1642 | ``` 1643 | 1644 | _Registration Options_: `TextDocumentRegistrationOptions` 1645 | 1646 | 1647 | > #### New: WillSaveWaitUntilTextDocument Request 1648 | 1649 | The document will save request is sent from the client to the server before the document is actually saved. The request can return an array of TextEdits which will be applied to the text document before it is saved. Please note that clients might drop results if computing the text edits took too long or if a server constantly fails on this request. This is done to keep the save fast and reliable. 1650 | 1651 | _Request_: 1652 | * method: 'textDocument/willSaveWaitUntil' 1653 | * params: `WillSaveTextDocumentParams` 1654 | 1655 | _Response_: 1656 | * result: `TextEdit[]` 1657 | * error: code and message set in case an exception happens during the `willSaveWaitUntil` request. 1658 | 1659 | _Registration Options_: `TextDocumentRegistrationOptions` 1660 | 1661 | #### DidSaveTextDocument Notification 1662 | 1663 | The document save notification is sent from the client to the server when the document was saved in the client. 1664 | 1665 | * method: 'textDocument/didSave' 1666 | * params: `DidSaveTextDocumentParams` defined as follows: 1667 | 1668 | ```typescript 1669 | interface DidSaveTextDocumentParams { 1670 | /** 1671 | * The document that was saved. 1672 | */ 1673 | textDocument: TextDocumentIdentifier; 1674 | 1675 | /** 1676 | * Optional the content when saved. Depends on the includeText value 1677 | * when the save notifcation was requested. 1678 | */ 1679 | text?: string; 1680 | } 1681 | ``` 1682 | 1683 | _Registration Options_: `TextDocumentSaveRegistrationOptions` defined as follows: 1684 | 1685 | ```typescript 1686 | export interface TextDocumentSaveRegistrationOptions extends TextDocumentRegistrationOptions { 1687 | /** 1688 | * The client is supposed to include the content on save. 1689 | */ 1690 | includeText?: boolean; 1691 | } 1692 | ``` 1693 | 1694 | #### DidCloseTextDocument Notification 1695 | 1696 | The document close notification is sent from the client to the server when the document got closed in the client. The document's truth now exists where the document's uri points to (e.g. if the document's uri is a file uri the truth now exists on disk). 1697 | 1698 | _Notification_: 1699 | * method: 'textDocument/didClose' 1700 | * params: `DidCloseTextDocumentParams` defined as follows: 1701 | 1702 | ```typescript 1703 | interface DidCloseTextDocumentParams { 1704 | /** 1705 | * The document that was closed. 1706 | */ 1707 | textDocument: TextDocumentIdentifier; 1708 | } 1709 | ``` 1710 | 1711 | _Registration Options_: `TextDocumentRegistrationOptions` 1712 | 1713 | #### DidChangeWatchedFiles Notification 1714 | 1715 | The watched files notification is sent from the client to the server when the client detects changes to files watched by the language client. 1716 | 1717 | _Notification_: 1718 | * method: 'workspace/didChangeWatchedFiles' 1719 | * params: `DidChangeWatchedFilesParams` defined as follows: 1720 | ```typescript 1721 | interface DidChangeWatchedFilesParams { 1722 | /** 1723 | * The actual file events. 1724 | */ 1725 | changes: FileEvent[]; 1726 | } 1727 | ``` 1728 | 1729 | Where FileEvents are described as follows: 1730 | 1731 | ```typescript 1732 | /** 1733 | * An event describing a file change. 1734 | */ 1735 | interface FileEvent { 1736 | /** 1737 | * The file's URI. 1738 | */ 1739 | uri: DocumentUri; 1740 | /** 1741 | * The change type. 1742 | */ 1743 | type: number; 1744 | } 1745 | 1746 | /** 1747 | * The file event type. 1748 | */ 1749 | export namespace FileChangeType { 1750 | /** 1751 | * The file got created. 1752 | */ 1753 | export const Created = 1; 1754 | /** 1755 | * The file got changed. 1756 | */ 1757 | export const Changed = 2; 1758 | /** 1759 | * The file got deleted. 1760 | */ 1761 | export const Deleted = 3; 1762 | } 1763 | ``` 1764 | 1765 | #### PublishDiagnostics Notification 1766 | 1767 | Diagnostics notification are sent from the server to the client to signal results of validation runs. 1768 | 1769 | _Notification_: 1770 | * method: 'textDocument/publishDiagnostics' 1771 | * params: `PublishDiagnosticsParams` defined as follows: 1772 | 1773 | ```typescript 1774 | interface PublishDiagnosticsParams { 1775 | /** 1776 | * The URI for which diagnostic information is reported. 1777 | */ 1778 | uri: DocumentUri; 1779 | 1780 | /** 1781 | * An array of diagnostic information items. 1782 | */ 1783 | diagnostics: Diagnostic[]; 1784 | } 1785 | ``` 1786 | 1787 | #### Completion Request 1788 | 1789 | The Completion request is sent from the client to the server to compute completion items at a given cursor position. Completion items are presented in the [IntelliSense](https://code.visualstudio.com/docs/editor/editingevolved#_intellisense) user interface. If computing full completion items is expensive, servers can additionally provide a handler for the completion item resolve request ('completionItem/resolve'). This request is sent when a completion item is selected in the user interface. A typically use case is for example: the 'textDocument/completion' request doesn't fill in the `documentation` property for returned completion items since it is expensive to compute. When the item is selected in the user interface then a 'completionItem/resolve' request is sent with the selected completion item as a param. The returned completion item should have the documentation property filled in. 1790 | 1791 | _Request_: 1792 | * method: 'textDocument/completion' 1793 | * params: [`TextDocumentPositionParams`](#textdocumentpositionparams) 1794 | 1795 | _Response_: 1796 | * result: `CompletionItem[] | CompletionList` 1797 | ```typescript 1798 | /** 1799 | * Represents a collection of [completion items](#CompletionItem) to be presented 1800 | * in the editor. 1801 | */ 1802 | interface CompletionList { 1803 | /** 1804 | * This list it not complete. Further typing should result in recomputing 1805 | * this list. 1806 | */ 1807 | isIncomplete: boolean; 1808 | /** 1809 | * The completion items. 1810 | */ 1811 | items: CompletionItem[]; 1812 | } 1813 | 1814 | /** 1815 | * Defines whether the insert text in a completion item should be interpreted as 1816 | * plain text or a snippet. 1817 | */ 1818 | namespace InsertTextFormat { 1819 | /** 1820 | * The primary text to be inserted is treated as a plain string. 1821 | */ 1822 | export const PlainText = 1; 1823 | 1824 | /** 1825 | * The primary text to be inserted is treated as a snippet. 1826 | * 1827 | * A snippet can define tab stops and placeholders with `$1`, `$2` 1828 | * and `${3:foo}`. `$0` defines the final tab stop, it defaults to 1829 | * the end of the snippet. Placeholders with equal identifiers are linked, 1830 | * that is typing in one will update others too. 1831 | * 1832 | * See also: https://github.com/Microsoft/vscode/blob/master/src/vs/editor/contrib/snippet/common/snippet.md 1833 | */ 1834 | export const Snippet = 2; 1835 | } 1836 | 1837 | type InsertTextFormat = 1 | 2; 1838 | 1839 | interface CompletionItem { 1840 | /** 1841 | * The label of this completion item. By default 1842 | * also the text that is inserted when selecting 1843 | * this completion. 1844 | */ 1845 | label: string; 1846 | /** 1847 | * The kind of this completion item. Based of the kind 1848 | * an icon is chosen by the editor. 1849 | */ 1850 | kind?: number; 1851 | /** 1852 | * A human-readable string with additional information 1853 | * about this item, like type or symbol information. 1854 | */ 1855 | detail?: string; 1856 | /** 1857 | * A human-readable string that represents a doc-comment. 1858 | */ 1859 | documentation?: string; 1860 | /** 1861 | * A string that shoud be used when comparing this item 1862 | * with other items. When `falsy` the label is used. 1863 | */ 1864 | sortText?: string; 1865 | /** 1866 | * A string that should be used when filtering a set of 1867 | * completion items. When `falsy` the label is used. 1868 | */ 1869 | filterText?: string; 1870 | /** 1871 | * A string that should be inserted a document when selecting 1872 | * this completion. When `falsy` the label is used. 1873 | */ 1874 | insertText?: string; 1875 | /** 1876 | * The format of the insert text. The format applies to both the `insertText` property 1877 | * and the `newText` property of a provided `textEdit`. 1878 | */ 1879 | insertTextFormat?: InsertTextFormat; 1880 | /** 1881 | * An edit which is applied to a document when selecting this completion. When an edit is provided the value of 1882 | * `insertText` is ignored. 1883 | * 1884 | * *Note:* The range of the edit must be a single line range and it must contain the position at which completion 1885 | * has been requested. 1886 | */ 1887 | textEdit?: TextEdit; 1888 | /** 1889 | * An optional array of additional text edits that are applied when 1890 | * selecting this completion. Edits must not overlap with the main edit 1891 | * nor with themselves. 1892 | */ 1893 | additionalTextEdits?: TextEdit[]; 1894 | /** 1895 | * An optional command that is executed *after* inserting this completion. *Note* that 1896 | * additional modifications to the current document should be described with the 1897 | * additionalTextEdits-property. 1898 | */ 1899 | command?: Command; 1900 | /** 1901 | * An data entry field that is preserved on a completion item between 1902 | * a completion and a completion resolve request. 1903 | */ 1904 | data?: any 1905 | } 1906 | 1907 | /** 1908 | * The kind of a completion entry. 1909 | */ 1910 | namespace CompletionItemKind { 1911 | export const Text = 1; 1912 | export const Method = 2; 1913 | export const Function = 3; 1914 | export const Constructor = 4; 1915 | export const Field = 5; 1916 | export const Variable = 6; 1917 | export const Class = 7; 1918 | export const Interface = 8; 1919 | export const Module = 9; 1920 | export const Property = 10; 1921 | export const Unit = 11; 1922 | export const Value = 12; 1923 | export const Enum = 13; 1924 | export const Keyword = 14; 1925 | export const Snippet = 15; 1926 | export const Color = 16; 1927 | export const File = 17; 1928 | export const Reference = 18; 1929 | } 1930 | ``` 1931 | * error: code and message set in case an exception happens during the completion request. 1932 | 1933 | _Registration Options_: `CompletionRegistrationOptions` options defined as follows: 1934 | 1935 | ```typescript 1936 | export interface CompletionRegistrationOptions extends TextDocumentRegistrationOptions { 1937 | /** 1938 | * The characters that trigger completion automatically. 1939 | */ 1940 | triggerCharacters?: string[]; 1941 | 1942 | /** 1943 | * The server provides support to resolve additional 1944 | * information for a completion item. 1945 | */ 1946 | resolveProvider?: boolean; 1947 | } 1948 | ``` 1949 | 1950 | #### Completion Item Resolve Request 1951 | 1952 | The request is sent from the client to the server to resolve additional information for a given completion item. 1953 | 1954 | _Request_: 1955 | * method: 'completionItem/resolve' 1956 | * params: `CompletionItem` 1957 | 1958 | _Response_: 1959 | * result: `CompletionItem` 1960 | * error: code and message set in case an exception happens during the completion resolve request. 1961 | 1962 | #### Hover Request 1963 | 1964 | The hover request is sent from the client to the server to request hover information at a given text document position. 1965 | 1966 | _Request_: 1967 | * method: 'textDocument/hover' 1968 | * params: [`TextDocumentPositionParams`](#textdocumentpositionparams) 1969 | 1970 | _Response_: 1971 | * result: `Hover` defined as follows: 1972 | 1973 | ```typescript 1974 | /** 1975 | * The result of a hover request. 1976 | */ 1977 | interface Hover { 1978 | /** 1979 | * The hover's content 1980 | */ 1981 | contents: MarkedString | MarkedString[]; 1982 | 1983 | /** 1984 | * An optional range is a range inside a text document 1985 | * that is used to visualize a hover, e.g. by changing the background color. 1986 | */ 1987 | range?: Range; 1988 | } 1989 | ``` 1990 | 1991 | Where `MarkedString` is defined as follows: 1992 | 1993 | ```typescript 1994 | /** 1995 | * MarkedString can be used to render human readable text. It is either a markdown string 1996 | * or a code-block that provides a language and a code snippet. The language identifier 1997 | * is sematically equal to the optional language identifier in fenced code blocks in GitHub 1998 | * issues. See https://help.github.com/articles/creating-and-highlighting-code-blocks/#syntax-highlighting 1999 | * 2000 | * The pair of a language and a value is an equivalent to markdown: 2001 | * ```${language} 2002 | * ${value} 2003 | * ``` 2004 | * 2005 | * Note that markdown strings will be sanitized - that means html will be escaped. 2006 | */ 2007 | type MarkedString = string | { language: string; value: string }; 2008 | ``` 2009 | 2010 | * error: code and message set in case an exception happens during the hover request. 2011 | 2012 | _Registration Options_: `TextDocumentRegistrationOptions` 2013 | 2014 | #### Signature Help Request 2015 | 2016 | The signature help request is sent from the client to the server to request signature information at a given cursor position. 2017 | 2018 | _Request_: 2019 | * method: 'textDocument/signatureHelp' 2020 | * params: [`TextDocumentPositionParams`](#textdocumentpositionparams) 2021 | 2022 | _Response_: 2023 | * result: `SignatureHelp` defined as follows: 2024 | 2025 | ```typescript 2026 | /** 2027 | * Signature help represents the signature of something 2028 | * callable. There can be multiple signature but only one 2029 | * active and only one active parameter. 2030 | */ 2031 | interface SignatureHelp { 2032 | /** 2033 | * One or more signatures. 2034 | */ 2035 | signatures: SignatureInformation[]; 2036 | 2037 | /** 2038 | * The active signature. If omitted or the value lies outside the 2039 | * range of `signatures` the value defaults to zero or is ignored if 2040 | * `signatures.length === 0`. Whenever possible implementors should 2041 | * make an active decision about the active signature and shouldn't 2042 | * rely on a default value. 2043 | * In future version of the protocol this property might become 2044 | * mandantory to better express this. 2045 | */ 2046 | activeSignature?: number; 2047 | 2048 | /** 2049 | * The active parameter of the active signature. If omitted or the value 2050 | * lies outside the range of `signatures[activeSignature].parameters` 2051 | * defaults to 0 if the active signature has parameters. If 2052 | * the active signature has no parameters it is ignored. 2053 | * In future version of the protocol this property might become 2054 | * mandantory to better express the active parameter if the 2055 | * active signature does have any. 2056 | */ 2057 | activeParameter?: number; 2058 | } 2059 | 2060 | /** 2061 | * Represents the signature of something callable. A signature 2062 | * can have a label, like a function-name, a doc-comment, and 2063 | * a set of parameters. 2064 | */ 2065 | interface SignatureInformation { 2066 | /** 2067 | * The label of this signature. Will be shown in 2068 | * the UI. 2069 | */ 2070 | label: string; 2071 | 2072 | /** 2073 | * The human-readable doc-comment of this signature. Will be shown 2074 | * in the UI but can be omitted. 2075 | */ 2076 | documentation?: string; 2077 | 2078 | /** 2079 | * The parameters of this signature. 2080 | */ 2081 | parameters?: ParameterInformation[]; 2082 | } 2083 | 2084 | /** 2085 | * Represents a parameter of a callable-signature. A parameter can 2086 | * have a label and a doc-comment. 2087 | */ 2088 | interface ParameterInformation { 2089 | /** 2090 | * The label of this parameter. Will be shown in 2091 | * the UI. 2092 | */ 2093 | label: string; 2094 | 2095 | /** 2096 | * The human-readable doc-comment of this parameter. Will be shown 2097 | * in the UI but can be omitted. 2098 | */ 2099 | documentation?: string; 2100 | } 2101 | ``` 2102 | 2103 | * error: code and message set in case an exception happens during the signature help request. 2104 | 2105 | _Registration Options_: `SignatureHelpRegistrationOptions` defined as follows: 2106 | 2107 | ```typescript 2108 | export interface SignatureHelpRegistrationOptions extends TextDocumentRegistrationOptions { 2109 | /** 2110 | * The characters that trigger signature help 2111 | * automatically. 2112 | */ 2113 | triggerCharacters?: string[]; 2114 | } 2115 | ``` 2116 | 2117 | #### Goto Definition Request 2118 | 2119 | The goto definition request is sent from the client to the server to resolve the definition location of a symbol at a given text document position. 2120 | 2121 | _Request_: 2122 | * method: 'textDocument/definition' 2123 | * params: [`TextDocumentPositionParams`](#textdocumentpositionparams) 2124 | 2125 | _Response_: 2126 | * result: [`Location`](#location) | [`Location`](#location)[] 2127 | * error: code and message set in case an exception happens during the definition request. 2128 | 2129 | _Registration Options_: `TextDocumentRegistrationOptions` 2130 | 2131 | #### Find References Request 2132 | 2133 | The references request is sent from the client to the server to resolve project-wide references for the symbol denoted by the given text document position. 2134 | 2135 | _Request_: 2136 | * method: 'textDocument/references' 2137 | * params: `ReferenceParams` defined as follows: 2138 | ```typescript 2139 | interface ReferenceParams extends TextDocumentPositionParams { 2140 | context: ReferenceContext 2141 | } 2142 | ``` 2143 | ```typescript 2144 | interface ReferenceContext { 2145 | /** 2146 | * Include the declaration of the current symbol. 2147 | */ 2148 | includeDeclaration: boolean; 2149 | } 2150 | ``` 2151 | _Response_: 2152 | * result: [`Location`](#location)[] 2153 | * error: code and message set in case an exception happens during the reference request. 2154 | 2155 | _Registration Options_: `TextDocumentRegistrationOptions` 2156 | 2157 | #### Document Highlights Request 2158 | 2159 | The document highlight request is sent from the client to the server to resolve a document highlights for a given text document position. 2160 | For programming languages this usually highlights all references to the symbol scoped to this file. However we kept 'textDocument/documentHighlight' 2161 | and 'textDocument/references' separate requests since the first one is allowed to be more fuzzy. Symbol matches usually have a `DocumentHighlightKind` 2162 | of `Read` or `Write` whereas fuzzy or textual matches use `Text`as the kind. 2163 | 2164 | _Request_: 2165 | * method: 'textDocument/documentHighlight' 2166 | * params: [`TextDocumentPositionParams`](#textdocumentpositionparams) 2167 | 2168 | _Response_: 2169 | * result: `DocumentHighlight`[] defined as follows: 2170 | 2171 | ```typescript 2172 | /** 2173 | * A document highlight is a range inside a text document which deserves 2174 | * special attention. Usually a document highlight is visualized by changing 2175 | * the background color of its range. 2176 | * 2177 | */ 2178 | interface DocumentHighlight { 2179 | /** 2180 | * The range this highlight applies to. 2181 | */ 2182 | range: Range; 2183 | 2184 | /** 2185 | * The highlight kind, default is DocumentHighlightKind.Text. 2186 | */ 2187 | kind?: number; 2188 | } 2189 | 2190 | /** 2191 | * A document highlight kind. 2192 | */ 2193 | export namespace DocumentHighlightKind { 2194 | /** 2195 | * A textual occurrence. 2196 | */ 2197 | export const Text = 1; 2198 | 2199 | /** 2200 | * Read-access of a symbol, like reading a variable. 2201 | */ 2202 | export const Read = 2; 2203 | 2204 | /** 2205 | * Write-access of a symbol, like writing to a variable. 2206 | */ 2207 | export const Write = 3; 2208 | } 2209 | ``` 2210 | 2211 | * error: code and message set in case an exception happens during the document highlight request. 2212 | 2213 | _Registration Options_: `TextDocumentRegistrationOptions` 2214 | 2215 | #### Document Symbols Request 2216 | 2217 | The document symbol request is sent from the client to the server to list all symbols found in a given text document. 2218 | 2219 | _Request_: 2220 | * method: 'textDocument/documentSymbol' 2221 | * params: `DocumentSymbolParams` defined as follows: 2222 | ```typescript 2223 | interface DocumentSymbolParams { 2224 | /** 2225 | * The text document. 2226 | */ 2227 | textDocument: TextDocumentIdentifier; 2228 | } 2229 | ``` 2230 | 2231 | _Response_: 2232 | * result: `SymbolInformation`[] defined as follows: 2233 | ```typescript 2234 | /** 2235 | * Represents information about programming constructs like variables, classes, 2236 | * interfaces etc. 2237 | */ 2238 | interface SymbolInformation { 2239 | /** 2240 | * The name of this symbol. 2241 | */ 2242 | name: string; 2243 | 2244 | /** 2245 | * The kind of this symbol. 2246 | */ 2247 | kind: number; 2248 | 2249 | /** 2250 | * The location of this symbol. 2251 | */ 2252 | location: Location; 2253 | 2254 | /** 2255 | * The name of the symbol containing this symbol. 2256 | */ 2257 | containerName?: string; 2258 | } 2259 | 2260 | /** 2261 | * A symbol kind. 2262 | */ 2263 | export namespace SymbolKind { 2264 | export const File = 1; 2265 | export const Module = 2; 2266 | export const Namespace = 3; 2267 | export const Package = 4; 2268 | export const Class = 5; 2269 | export const Method = 6; 2270 | export const Property = 7; 2271 | export const Field = 8; 2272 | export const Constructor = 9; 2273 | export const Enum = 10; 2274 | export const Interface = 11; 2275 | export const Function = 12; 2276 | export const Variable = 13; 2277 | export const Constant = 14; 2278 | export const String = 15; 2279 | export const Number = 16; 2280 | export const Boolean = 17; 2281 | export const Array = 18; 2282 | } 2283 | ``` 2284 | 2285 | * error: code and message set in case an exception happens during the document symbol request. 2286 | 2287 | _Registration Options_: `TextDocumentRegistrationOptions` 2288 | 2289 | #### Workspace Symbols Request 2290 | 2291 | The workspace symbol request is sent from the client to the server to list project-wide symbols matching the query string. The text document parameter specifies the active document at time of the query. This can be used to rank or limit results. 2292 | 2293 | _Request_: 2294 | * method: 'workspace/symbol' 2295 | * params: `WorkspaceSymbolParams` defined as follows: 2296 | ```typescript 2297 | /** 2298 | * The parameters of a Workspace Symbol Request. 2299 | */ 2300 | interface WorkspaceSymbolParams { 2301 | /** 2302 | * A non-empty query string 2303 | */ 2304 | query: string; 2305 | 2306 | /** 2307 | * Identifies the textDocument that is currently active. 2308 | */ 2309 | xactiveTextDocument?: TextDocumentIdentifier; 2310 | } 2311 | ``` 2312 | 2313 | _Response_: 2314 | * result: `SymbolInformation[]` as defined above. 2315 | * error: code and message set in case an exception happens during the workspace symbol request. 2316 | 2317 | _Registration Options_: void 2318 | 2319 | #### Code Action Request 2320 | 2321 | The code action request is sent from the client to the server to compute commands for a given text document and range. These commands are typically code fixes to either fix problems or to beautify/refactor code. 2322 | 2323 | _Request_: 2324 | * method: 'textDocument/codeAction' 2325 | * params: `CodeActionParams` defined as follows: 2326 | ```typescript 2327 | /** 2328 | * Params for the CodeActionRequest 2329 | */ 2330 | interface CodeActionParams { 2331 | /** 2332 | * The document in which the command was invoked. 2333 | */ 2334 | textDocument: TextDocumentIdentifier; 2335 | 2336 | /** 2337 | * The range for which the command was invoked. 2338 | */ 2339 | range: Range; 2340 | 2341 | /** 2342 | * Context carrying additional information. 2343 | */ 2344 | context: CodeActionContext; 2345 | } 2346 | 2347 | /** 2348 | * Contains additional diagnostic information about the context in which 2349 | * a code action is run. 2350 | */ 2351 | interface CodeActionContext { 2352 | /** 2353 | * An array of diagnostics. 2354 | */ 2355 | diagnostics: Diagnostic[]; 2356 | } 2357 | ``` 2358 | 2359 | _Response_: 2360 | * result: [`Command[]`](#command) defined as follows: 2361 | * error: code and message set in case an exception happens during the code action request. 2362 | 2363 | _Registration Options_: `TextDocumentRegistrationOptions` 2364 | 2365 | #### Code Lens Request 2366 | 2367 | The code lens request is sent from the client to the server to compute code lenses for a given text document. 2368 | 2369 | _Request_: 2370 | * method: 'textDocument/codeLens' 2371 | * params: `CodeLensParams` defined as follows: 2372 | 2373 | ```typescript 2374 | interface CodeLensParams { 2375 | /** 2376 | * The document to request code lens for. 2377 | */ 2378 | textDocument: TextDocumentIdentifier; 2379 | } 2380 | ``` 2381 | 2382 | _Response_: 2383 | * result: `CodeLens[]` defined as follows: 2384 | 2385 | ```typescript 2386 | /** 2387 | * A code lens represents a command that should be shown along with 2388 | * source text, like the number of references, a way to run tests, etc. 2389 | * 2390 | * A code lens is _unresolved_ when no command is associated to it. For performance 2391 | * reasons the creation of a code lens and resolving should be done in two stages. 2392 | */ 2393 | interface CodeLens { 2394 | /** 2395 | * The range in which this code lens is valid. Should only span a single line. 2396 | */ 2397 | range: Range; 2398 | 2399 | /** 2400 | * The command this code lens represents. 2401 | */ 2402 | command?: Command; 2403 | 2404 | /** 2405 | * A data entry field that is preserved on a code lens item between 2406 | * a code lens and a code lens resolve request. 2407 | */ 2408 | data?: any 2409 | } 2410 | ``` 2411 | * error: code and message set in case an exception happens during the code lens request. 2412 | 2413 | _Registration Options_: `CodeLensRegistrationOptions` defined as follows: 2414 | 2415 | ```typescript 2416 | export interface CodeLensRegistrationOptions extends TextDocumentRegistrationOptions { 2417 | /** 2418 | * Code lens has a resolve provider as well. 2419 | */ 2420 | resolveProvider?: boolean; 2421 | } 2422 | ``` 2423 | 2424 | #### Code Lens Resolve Request 2425 | 2426 | The code lens resolve request is sent from the client to the server to resolve the command for a given code lens item. 2427 | 2428 | _Request_: 2429 | * method: 'codeLens/resolve' 2430 | * params: `CodeLens` 2431 | 2432 | _Response_: 2433 | * result: `CodeLens` 2434 | * error: code and message set in case an exception happens during the code lens resolve request. 2435 | 2436 | #### Document Link Request 2437 | 2438 | The document links request is sent from the client to the server to request the location of links in a document. 2439 | 2440 | _Request_: 2441 | * method: 'textDocument/documentLink' 2442 | * params: `DocumentLinkParams`, defined as follows 2443 | ```typescript 2444 | interface DocumentLinkParams { 2445 | /** 2446 | * The document to provide document links for. 2447 | */ 2448 | textDocument: TextDocumentIdentifier; 2449 | } 2450 | ``` 2451 | 2452 | _Response_: 2453 | * result: An array of `DocumentLink`, or `null`. 2454 | 2455 | ```typescript 2456 | /** 2457 | * A document link is a range in a text document that links to an internal or external resource, like another 2458 | * text document or a web site. 2459 | */ 2460 | interface DocumentLink { 2461 | /** 2462 | * The range this link applies to. 2463 | */ 2464 | range: Range; 2465 | /** 2466 | * The uri this link points to. If missing a resolve request is sent later. 2467 | */ 2468 | target?: DocumentUri; 2469 | } 2470 | ``` 2471 | * error: code and message set in case an exception happens during the document link request. 2472 | 2473 | _Registration Options_: `DocumentLinkRegistrationOptions` defined as follows: 2474 | 2475 | ```typescript 2476 | export interface DocumentLinkRegistrationOptions extends TextDocumentRegistrationOptions { 2477 | /** 2478 | * Document links have a resolve provider as well. 2479 | */ 2480 | resolveProvider?: boolean; 2481 | } 2482 | ``` 2483 | 2484 | #### Document Link Resolve Request 2485 | 2486 | The document link resolve request is sent from the client to the server to resolve the target of a given document link. 2487 | 2488 | _Request_: 2489 | * method: 'documentLink/resolve' 2490 | * params: `DocumentLink` 2491 | 2492 | _Response_: 2493 | * result: `DocumentLink` 2494 | * error: code and message set in case an exception happens during the document link resolve request. 2495 | 2496 | #### Document Formatting Request 2497 | 2498 | The document formatting request is sent from the server to the client to format a whole document. 2499 | 2500 | _Request_: 2501 | * method: 'textDocument/formatting' 2502 | * params: `DocumentFormattingParams` defined as follows 2503 | ```typescript 2504 | interface DocumentFormattingParams { 2505 | /** 2506 | * The document to format. 2507 | */ 2508 | textDocument: TextDocumentIdentifier; 2509 | 2510 | /** 2511 | * The format options. 2512 | */ 2513 | options: FormattingOptions; 2514 | } 2515 | 2516 | /** 2517 | * Value-object describing what options formatting should use. 2518 | */ 2519 | interface FormattingOptions { 2520 | /** 2521 | * Size of a tab in spaces. 2522 | */ 2523 | tabSize: number; 2524 | 2525 | /** 2526 | * Prefer spaces over tabs. 2527 | */ 2528 | insertSpaces: boolean; 2529 | 2530 | /** 2531 | * Signature for further properties. 2532 | */ 2533 | [key: string]: boolean | number | string; 2534 | } 2535 | ``` 2536 | 2537 | _Response_: 2538 | * result: [`TextEdit[]`](#textedit) describing the modification to the document to be formatted. 2539 | * error: code and message set in case an exception happens during the formatting request. 2540 | 2541 | _Registration Options_: `TextDocumentRegistrationOptions` 2542 | 2543 | #### Document Range Formatting Request 2544 | 2545 | The document range formatting request is sent from the client to the server to format a given range in a document. 2546 | 2547 | _Request_: 2548 | * method: 'textDocument/rangeFormatting', 2549 | * params: `DocumentRangeFormattingParams` defined as follows: 2550 | 2551 | ```typescript 2552 | interface DocumentRangeFormattingParams { 2553 | /** 2554 | * The document to format. 2555 | */ 2556 | textDocument: TextDocumentIdentifier; 2557 | 2558 | /** 2559 | * The range to format 2560 | */ 2561 | range: Range; 2562 | 2563 | /** 2564 | * The format options 2565 | */ 2566 | options: FormattingOptions; 2567 | } 2568 | ``` 2569 | 2570 | _Response_: 2571 | * result: [`TextEdit[]`](#textedit) describing the modification to the document to be formatted. 2572 | * error: code and message set in case an exception happens during the range formatting request. 2573 | 2574 | _Registration Options_: `TextDocumentRegistrationOptions` 2575 | 2576 | #### Document on Type Formatting Request 2577 | 2578 | The document on type formatting request is sent from the client to the server to format parts of the document during typing. 2579 | 2580 | _Request_: 2581 | * method: 'textDocument/onTypeFormatting' 2582 | * params: `DocumentOnTypeFormattingParams` defined as follows: 2583 | 2584 | ```typescript 2585 | interface DocumentOnTypeFormattingParams { 2586 | /** 2587 | * The document to format. 2588 | */ 2589 | textDocument: TextDocumentIdentifier; 2590 | 2591 | /** 2592 | * The position at which this request was sent. 2593 | */ 2594 | position: Position; 2595 | 2596 | /** 2597 | * The character that has been typed. 2598 | */ 2599 | ch: string; 2600 | 2601 | /** 2602 | * The format options. 2603 | */ 2604 | options: FormattingOptions; 2605 | } 2606 | ``` 2607 | 2608 | _Response_: 2609 | * result: [`TextEdit[]`](#textedit) describing the modification to the document. 2610 | * error: code and message set in case an exception happens during the range formatting request. 2611 | 2612 | _Registration Options_: `DocumentOnTypeFormattingRegistrationOptions` defined as follows: 2613 | 2614 | ```typescript 2615 | export interface DocumentOnTypeFormattingRegistrationOptions extends TextDocumentRegistrationOptions { 2616 | /** 2617 | * A character on which formatting should be triggered, like `}`. 2618 | */ 2619 | firstTriggerCharacter: string; 2620 | /** 2621 | * More trigger characters. 2622 | */ 2623 | moreTriggerCharacter?: string[] 2624 | } 2625 | ``` 2626 | #### Rename Request 2627 | 2628 | The rename request is sent from the client to the server to perform a workspace-wide rename of a symbol. 2629 | 2630 | _Request_: 2631 | * method: 'textDocument/rename' 2632 | * params: `RenameParams` defined as follows 2633 | ```typescript 2634 | interface RenameParams { 2635 | /** 2636 | * The document to format. 2637 | */ 2638 | textDocument: TextDocumentIdentifier; 2639 | 2640 | /** 2641 | * The position at which this request was sent. 2642 | */ 2643 | position: Position; 2644 | 2645 | /** 2646 | * The new name of the symbol. If the given name is not valid the 2647 | * request must return a [ResponseError](#ResponseError) with an 2648 | * appropriate message set. 2649 | */ 2650 | newName: string; 2651 | } 2652 | ``` 2653 | 2654 | _Response_: 2655 | * result: [`WorkspaceEdit`](#workspaceedit) describing the modification to the workspace. 2656 | * error: code and message set in case an exception happens during the rename request. 2657 | 2658 | _Registration Options_: `TextDocumentRegistrationOptions` 2659 | 2660 | #### Execute a command 2661 | 2662 | The `workspace/executeCommand` request is sent from the client to the server to trigger command execution on the server. In most cases 2663 | the server creates a `WorkspaceEdit` structure and applies the changes to the workspace using the request `workspace/applyEdit` which is 2664 | sent from the server to the client. 2665 | 2666 | _Request:_ 2667 | * method: 'workspace/executeCommand' 2668 | * params: `ExecuteCommandParams` defined as follows: 2669 | 2670 | ```typescript 2671 | export interface ExecuteCommandParams { 2672 | 2673 | /** 2674 | * The identifier of the actual command handler. 2675 | */ 2676 | command: string; 2677 | /** 2678 | * Arguments that the command should be invoked with. 2679 | */ 2680 | arguments?: any[]; 2681 | } 2682 | ``` 2683 | 2684 | The arguments are typically specified when a command is returned from the server to the client. Example requests that return a command are `textDocument/codeAction` or `textDocument/codeLens`. 2685 | 2686 | _Response_: 2687 | * result: any 2688 | * error: code and message set in case an exception happens during the request. 2689 | 2690 | _Registration Options_: `ExecuteCommandRegistrationOptions` defined as follows: 2691 | 2692 | ```typescript 2693 | /** 2694 | * Execute command registration options. 2695 | */ 2696 | export interface ExecuteCommandRegistrationOptions { 2697 | /** 2698 | * The commands to be executed on the server 2699 | */ 2700 | commands: string[] 2701 | } 2702 | ``` 2703 | 2704 | #### Applies a WorkspaceEdit 2705 | 2706 | The `workspace/applyEdit` request is sent from the server to the client to modify resource on the client side. 2707 | 2708 | _Request_: 2709 | * method: 'workspace/applyEdit' 2710 | * params: `ApplyWorkspaceEditParams` defined as follows: 2711 | 2712 | ```typescript 2713 | export interface ApplyWorkspaceEditParams { 2714 | /** 2715 | * The edits to apply. 2716 | */ 2717 | edit: WorkspaceEdit; 2718 | } 2719 | ``` 2720 | 2721 | _Response_: 2722 | * result: `ApplyWorkspaceEditResponse` defined as follows: 2723 | ```typescript 2724 | export interface ApplyWorkspaceEditResponse { 2725 | /** 2726 | * Indicates whether the edit was applied or not. 2727 | */ 2728 | applied: boolean; 2729 | } 2730 | ``` 2731 | * error: code and message set in case an exception happens during the request. 2732 | -------------------------------------------------------------------------------- /versions/protocol-1-x.md: -------------------------------------------------------------------------------- 1 | # VSCode Client / Server Language Protocol 2 | 3 | This document descibes the 1.x version of the client server protocol. It defines the client server protocol used by VSCode to talk to out of process language servers. 4 | The repository contains a VSCode protocol definition so that other can implement the protocol in language like C#, C++, Java or Python. 5 | 6 | ## Base Protocol 7 | 8 | The base protocol consists of a header and a content part (comparable to http). The header and content part are 9 | separated by a '\r\n'. 10 | 11 | ### Header Part 12 | 13 | The header part consist of header fields. Header fields are separated from each other by '\r\n'. The last header 14 | field needs to be terminated with '\r\n' as well. Currently the following header fields are supported: 15 | 16 | | Header File Name | Value Type | Description | 17 | |:-----------------|:------------|:------------| 18 | | Content-Length | number | The length of the content part | 19 | | Content-Type | string | The mime typ of the content part. Defaults to application/vscode-jsonrpc; charset=utf8 | 20 | 21 | The header part is encoded using the 'ascii' encoding. This includes the '\r\n' separating the header and content part. 22 | 23 | ### Content Part 24 | 25 | Contains the actual content of the message. The content part of a message uses [JSON-RPC](http://www.jsonrpc.org/) to describe requests, responses and notifications. The content part is encoded using the charset provided in the Content-Type field. It defaults to 'utf8' which is the only encoding supported right now. 26 | 27 | 28 | ### Example: 29 | 30 | ``` 31 | Content-Length: ...\r\n 32 | \r\n 33 | { 34 | "jsonrpc": "2.0", 35 | "id": 1, 36 | "method": "textDocument/didOpen", 37 | "params": { 38 | ... 39 | } 40 | } 41 | ``` 42 | ### Base Protocol JSON structures 43 | 44 | The following TypeScript definitions describe the JSON-RPC protocol as implemented by VSCode: 45 | 46 | #### Abstract Message 47 | 48 | A general message as defined by JSON-RPC. The language server protocol always uses "2.0" as the jsonrpc version. 49 | 50 | ```typescript 51 | interface Message { 52 | jsonrpc: string; 53 | } 54 | ``` 55 | #### RequestMessage 56 | 57 | A request message to decribe a request between the client and the server. Every processed request must send a response back to the sender of the request. 58 | 59 | ```typescript 60 | interface RequestMessage extends Message { 61 | 62 | /** 63 | * The request id. 64 | */ 65 | id: number | string; 66 | 67 | /** 68 | * The method to be invoked. 69 | */ 70 | method: string; 71 | 72 | /** 73 | * The method's params. 74 | */ 75 | params?: any 76 | } 77 | ``` 78 | 79 | #### Response Message 80 | 81 | Response Message send as a result of a request. 82 | 83 | ```typescript 84 | interface ResponseMessage extends Message { 85 | /** 86 | * The request id. 87 | */ 88 | id: number | string; 89 | 90 | /** 91 | * The result of a request. This can be omitted in 92 | * the case of an error. 93 | */ 94 | result?: any; 95 | 96 | /** 97 | * The error object in case a request fails. 98 | */ 99 | error?: ResponseError; 100 | } 101 | 102 | interface ResponseError { 103 | /** 104 | * A number indicating the error type that occured. 105 | */ 106 | code: number; 107 | 108 | /** 109 | * A string providing a short decription of the error. 110 | */ 111 | message: string; 112 | 113 | /** 114 | * A Primitive or Structured value that contains additional 115 | * information about the error. Can be omitted. 116 | */ 117 | data?: D; 118 | } 119 | 120 | export namespace ErrorCodes { 121 | export const ParseError: number = -32700; 122 | export const InvalidRequest: number = -32600; 123 | export const MethodNotFound: number = -32601; 124 | export const InvalidParams: number = -32602; 125 | export const InternalError: number = -32603; 126 | export const serverErrorStart: number = -32099 127 | export const serverErrorEnd: number = -32000; 128 | } 129 | ``` 130 | #### Notification Message 131 | 132 | A notification message. A processed notification message must not send a response back. They work like events. 133 | 134 | ```typescript 135 | interface NotificationMessage extends Message { 136 | /** 137 | * The method to be invoked. 138 | */ 139 | method: string; 140 | 141 | /** 142 | * The notification's params. 143 | */ 144 | params?: any 145 | } 146 | ``` 147 | 148 | ## Language Server Protocol 149 | 150 | The language server protocol defines a set of JSON-RPC request, response and notification messages which are exchanged using the above base protocol. This sections starts descibing basic JSON structures used in the protocol. The document uses TypeScript interfaces to describe these. Bases on the basic JSON structures the actual requests with their responses and the notifications are described. 151 | 152 | ### Basic JSON Structures 153 | 154 | #### Position 155 | 156 | Position in a text document expressed as zero-based line and character offset. 157 | 158 | ```typescript 159 | interface Position { 160 | /** 161 | * Line position in a document (zero-based). 162 | */ 163 | line: number; 164 | 165 | /** 166 | * Character offset on a line in a document (zero-based). 167 | */ 168 | character: number; 169 | } 170 | ``` 171 | #### Range 172 | 173 | A range in a text document expressed as (zero-based) start and end positions. 174 | ```typescript 175 | interface Range { 176 | /** 177 | * The range's start position 178 | */ 179 | start: Position; 180 | 181 | /** 182 | * The range's end position 183 | */ 184 | end: Position; 185 | } 186 | ``` 187 | 188 | #### Location 189 | 190 | Represents a location inside a resource, such as a line inside a text file. 191 | ```typescript 192 | interface Location { 193 | uri: string; 194 | range: Range; 195 | } 196 | ``` 197 | 198 | #### Diagnostic 199 | 200 | Represents a diagnostic, such as a compiler error or warning. Diagnostic objects are only valid in the scope of a resource. 201 | 202 | ```typescript 203 | interface Diagnostic { 204 | /** 205 | * The range at which the message applies 206 | */ 207 | range: Range; 208 | 209 | /** 210 | * The diagnostic's severity. Can be omitted. If omitted it is up to the 211 | * client to interpret diagnostics as error, warning, info or hint. 212 | */ 213 | severity?: number; 214 | 215 | /** 216 | * The diagnostic's code. Can be omitted. 217 | */ 218 | code?: number | string; 219 | 220 | /** 221 | * A human-readable string describing the source of this 222 | * diagnostic, e.g. 'typescript' or 'super lint'. 223 | */ 224 | source?: string; 225 | 226 | /** 227 | * The diagnostic's message. 228 | */ 229 | message: string; 230 | } 231 | ``` 232 | 233 | The protocol currently supports the following diagnostic severities 234 | 235 | ```typescript 236 | enum DiagnosticSeverity { 237 | /** 238 | * Reports an error. 239 | */ 240 | Error = 1, 241 | /** 242 | * Reports a warning. 243 | */ 244 | Warning = 2, 245 | /** 246 | * Reports an information. 247 | */ 248 | Information = 3, 249 | /** 250 | * Reports a hint. 251 | */ 252 | Hint = 4 253 | } 254 | ``` 255 | 256 | #### Command 257 | 258 | Represents a reference to a command. Provides a title which will be used to represent a command in the UI and, optionally, an array of arguments which will be passed to the command handler function when invoked. 259 | 260 | ```typescript 261 | interface Command { 262 | /** 263 | * Title of the command, like `save`. 264 | */ 265 | title: string; 266 | /** 267 | * The identifier of the actual command handler. 268 | */ 269 | command: string; 270 | /** 271 | * Arguments that the command handler should be 272 | * invoked with. 273 | */ 274 | arguments?: any[]; 275 | } 276 | ``` 277 | 278 | #### TextEdit 279 | 280 | A textual edit applicable to a text document. 281 | 282 | ```typescript 283 | interface TextEdit { 284 | /** 285 | * The range of the text document to be manipulated. To insert 286 | * text into a document create a range where start === end. 287 | */ 288 | range: Range; 289 | 290 | /** 291 | * The string to be inserted. For delete operations use an 292 | * empty string. 293 | */ 294 | newText: string; 295 | } 296 | ``` 297 | 298 | #### WorkspaceEdit 299 | 300 | A workspace edit represents changes to many resources managed in the workspace. 301 | 302 | ```typescript 303 | export interface WorkspaceEdit { 304 | /** 305 | * Holds changes to existing resources. 306 | */ 307 | changes: { [uri: string]: TextEdit[]; }; 308 | } 309 | ``` 310 | 311 | #### TextDocumentIdentifier 312 | 313 | Text documents are identified using an URI. On the protocol level URI's are passed as strings. The corresponding JSON structure looks like this: 314 | ```typescript 315 | interface TextDocumentIdentifier { 316 | /** 317 | * The text document's uri. 318 | */ 319 | uri: string; 320 | } 321 | ``` 322 | 323 | #### TextDocumentPosition 324 | 325 | Identifies a position in a text document. 326 | 327 | ```typescript 328 | interface TextDocumentPosition extends TextDocumentIdentifier { 329 | /** 330 | * The position inside the text document. 331 | */ 332 | position: Position; 333 | } 334 | ``` 335 | 336 | ### Actual Protocol 337 | 338 | This section documents the actual language server protocol. It uses the following format: 339 | 340 | * a header describing the request 341 | * a _Request_ section describing the format of the request send. The method is a string identifying the request the params are documented using a TypeScript interface 342 | * a _Response_ section describing the format of the response. The result item descibes the returned data in case of a success. The error.data describes the returned data in case of an error. Please remember that in case of a failure the response already contains an error.code and an error.message field. These fields are only speced if the protocol forces the use of certain error codes or messages. In cases where the server can decide on these values freely they arn't listed here. 343 | 344 | #### Initialize Request 345 | 346 | The initialize request is sent as the first request from the client to the server. 347 | 348 | _Request_ 349 | * method: 'initialize' 350 | * params: `InitializeParams` defined as follows: 351 | ```typescript 352 | interface InitializeParams { 353 | /** 354 | * The process Id of the parent process that started 355 | * the server. 356 | */ 357 | processId: number; 358 | 359 | /** 360 | * The rootPath of the workspace. Is null 361 | * if no folder is open. 362 | */ 363 | rootPath: string; 364 | 365 | /** 366 | * The capabilities provided by the client (editor) 367 | */ 368 | capabilities: ClientCapabilities; 369 | } 370 | ``` 371 | 372 | _Response_ 373 | * result: `InitializeResult` defined as follows: 374 | ```typescript 375 | export InitializeResult { 376 | /** 377 | * The capabilities the language server provides. 378 | */ 379 | capabilities: ServerCapabilities; 380 | } 381 | ``` 382 | * error.data: 383 | ```typescript 384 | interface InitializeError { 385 | /** 386 | * Indicates whether the client should retry to send the 387 | * initilize request after showing the message provided 388 | * in the ResponseError. 389 | */ 390 | retry: boolean; 391 | } 392 | ``` 393 | The server can signal the following capabilities: 394 | ```typescript 395 | /** 396 | * Defines how the host (editor) should sync document changes to the language server. 397 | */ 398 | enum TextDocumentSyncKind { 399 | /** 400 | * Documents should not be synced at all. 401 | */ 402 | None = 0, 403 | /** 404 | * Documents are synced by always sending the full content of the document. 405 | */ 406 | Full = 1, 407 | /** 408 | * Documents are synced by sending the full content on open. After that only incremental 409 | * updates to the document are send. 410 | */ 411 | Incremental = 2 412 | } 413 | ``` 414 | ```typescript 415 | /** 416 | * Completion options. 417 | */ 418 | interface CompletionOptions { 419 | /** 420 | * The server provides support to resolve additional information for a completion item. 421 | */ 422 | resolveProvider?: boolean; 423 | 424 | /** 425 | * The characters that trigger completion automatically. 426 | */ 427 | triggerCharacters?: string[]; 428 | } 429 | ``` 430 | ```typescript 431 | /** 432 | * Signature help options. 433 | */ 434 | interface SignatureHelpOptions { 435 | /** 436 | * The characters that trigger signature help automatically. 437 | */ 438 | triggerCharacters?: string[]; 439 | } 440 | ``` 441 | ```typescript 442 | /** 443 | * Code Lens options. 444 | */ 445 | interface CodeLensOptions { 446 | /** 447 | * Code lens has a resolve provider as well. 448 | */ 449 | resolveProvider?: boolean; 450 | } 451 | ``` 452 | ```typescript 453 | /** 454 | * Format document on type options 455 | */ 456 | interface DocumentOnTypeFormattingOptions { 457 | /** 458 | * A character on which formatting should be triggered, like `}`. 459 | */ 460 | firstTriggerCharacter: string; 461 | /** 462 | * More trigger characters. 463 | */ 464 | moreTriggerCharacter?: string[] 465 | } 466 | ``` 467 | ```typescript 468 | interface ServerCapabilities { 469 | /** 470 | * Defines how text documents are synced. 471 | */ 472 | textDocumentSync?: number; 473 | /** 474 | * The server provides hover support. 475 | */ 476 | hoverProvider?: boolean; 477 | /** 478 | * The server provides completion support. 479 | */ 480 | completionProvider?: CompletionOptions; 481 | /** 482 | * The server provides signature help support. 483 | */ 484 | signatureHelpProvider?: SignatureHelpOptions; 485 | /** 486 | * The server provides goto definition support. 487 | */ 488 | definitionProvider?: boolean; 489 | /** 490 | * The server provides find references support. 491 | */ 492 | referencesProvider?: boolean; 493 | /** 494 | * The server provides document highlight support. 495 | */ 496 | documentHighlightProvider?: boolean; 497 | /** 498 | * The server provides document symbol support. 499 | */ 500 | documentSymbolProvider?: boolean; 501 | /** 502 | * The server provides workspace symbol support. 503 | */ 504 | workspaceSymbolProvider?: boolean; 505 | /** 506 | * The server provides code actions. 507 | */ 508 | codeActionProvider?: boolean; 509 | /** 510 | * The server provides code lens. 511 | */ 512 | codeLensProvider?: CodeLensOptions; 513 | /** 514 | * The server provides document formatting. 515 | */ 516 | documentFormattingProvider?: boolean; 517 | /** 518 | * The server provides document range formatting. 519 | */ 520 | documentRangeFormattingProvider?: boolean; 521 | /** 522 | * The server provides document formatting on typing. 523 | */ 524 | documentOnTypeFormattingProvider?: DocumentOnTypeFormattingOptions; 525 | /** 526 | * The server provides rename support. 527 | */ 528 | renameProvider?: boolean 529 | } 530 | ``` 531 | 532 | #### Shutdown Request 533 | 534 | The shutdown request is sent from the client to the server. It asks the server to shutdown, but to not exit (otherwise the response might not be delivered correctly to the client). There is a separate exit notification that asks the server to exit. 535 | 536 | _Request_ 537 | * method: 'shutdown' 538 | * params: undefined 539 | 540 | _Response_ 541 | * result: undefined 542 | * error: code and message set in case an exception happens during shutdown request. 543 | 544 | #### Exit Notification 545 | 546 | A notification to ask the server to exit its process. 547 | 548 | _Notification_ 549 | * method: 'exit' 550 | * params: undefined 551 | 552 | #### ShowMessage Notification 553 | 554 | The show message notification is sent from a server to a client to ask the client to display a particular message in the user interface. 555 | 556 | _Notification_: 557 | * method: 'window/showMessage' 558 | * params: `ShowMessageParams` defined as follows: 559 | ```typescript 560 | interface ShowMessageParams { 561 | /** 562 | * The message type. See {@link MessageType} 563 | */ 564 | type: number; 565 | 566 | /** 567 | * The actual message 568 | */ 569 | message: string; 570 | } 571 | ``` 572 | Where the type is defined as follows: 573 | ```typescript 574 | enum MessageType { 575 | /** 576 | * An error message. 577 | */ 578 | Error = 1, 579 | /** 580 | * A warning message. 581 | */ 582 | Warning = 2, 583 | /** 584 | * An information message. 585 | */ 586 | Info = 3, 587 | /** 588 | * A log message. 589 | */ 590 | Log = 4 591 | } 592 | ``` 593 | 594 | #### LogMessage Notification 595 | 596 | The log message notification is send from the server to the client to ask the client to log a particular message. 597 | 598 | _Notification_: 599 | * method: 'window/logMessage' 600 | * params: `LogMessageParams` defined as follows: 601 | ```typescript 602 | interface LogMessageParams { 603 | /** 604 | * The message type. See {@link MessageType} 605 | */ 606 | type: number; 607 | 608 | /** 609 | * The actual message 610 | */ 611 | message: string; 612 | } 613 | ``` 614 | Where type is defined as above. 615 | 616 | #### DidChangeConfiguration Notification 617 | 618 | A notification send from the client to the server to signal the change of configuration settings. 619 | 620 | _Notification_: 621 | * method: 'workspace/didChangeConfiguration', 622 | * params: `DidChangeConfigurationParams` defined as follows: 623 | ```typescript 624 | interface DidChangeConfigurationParams { 625 | /** 626 | * The actual changed settings 627 | */ 628 | settings: any; 629 | } 630 | ``` 631 | 632 | #### DidOpenTextDocument Notification 633 | 634 | The document open notification is sent from the client to the server to signal newly opened text documents. The document's truth is now managed by the client and the server must not try to read the document's truth using the document's uri. 635 | 636 | _Notification_: 637 | * method: 'textDocument/didOpen' 638 | * params: `DidOpenTextDocumentParams` defined as follows: 639 | ```typescript 640 | interface DidOpenTextDocumentParams extends TextDocumentIdentifier { 641 | /** 642 | * The content of the opened text document. 643 | */ 644 | text: string; 645 | } 646 | ``` 647 | 648 | #### DidChangeTextDocument Notification 649 | 650 | The document change notification is sent from the client to the server to signal changes to a text document. 651 | 652 | _Notification_: 653 | * method: 'textDocument/didChange' 654 | * params: `DidChangeTextDocumentParams` defined as follows: 655 | ```typescript 656 | interface DidChangeTextDocumentParams extends TextDocumentIdentifier { 657 | contentChanges: TextDocumentContentChangeEvent[]; 658 | } 659 | ``` 660 | ```typescript 661 | /** 662 | * An event describing a change to a text document. If range and rangeLength are omitted 663 | * the new text is considered to be the full content of the document. 664 | */ 665 | interface TextDocumentContentChangeEvent { 666 | /** 667 | * The range of the document that changed. 668 | */ 669 | range?: Range; 670 | 671 | /** 672 | * The length of the range that got replaced. 673 | */ 674 | rangeLength?: number; 675 | 676 | /** 677 | * The new text of the document. 678 | */ 679 | text: string; 680 | } 681 | ``` 682 | 683 | #### DidCloseTextDocument Notification 684 | 685 | The document close notification is sent from the client to the server when the document got closed in the client. The document's truth now exists where the document's uri points to (e.g. if the document's uri is a file uri the truth now exists on disk). 686 | 687 | _Notification_: 688 | * method: 'textDocument/didClose' 689 | * param: `TextDocumentIdentifier` 690 | 691 | #### DidChangeWatchedFiles Notification 692 | 693 | The watched files notification is sent from the client to the server when the client detects changes to file watched by the lanaguage client. 694 | 695 | _Notification_: 696 | * method: 'workspace/didChangeWatchedFiles' 697 | * params: `DidChangeWatchedFilesParams` defined as follows: 698 | ```typescript 699 | interface DidChangeWatchedFilesParams { 700 | /** 701 | * The actual file events. 702 | */ 703 | changes: FileEvent[]; 704 | } 705 | ``` 706 | Where FileEvents are described as follows: 707 | ```typescript 708 | /** 709 | * The file event type 710 | */ 711 | enum FileChangeType { 712 | /** 713 | * The file got created. 714 | */ 715 | Created = 1, 716 | /** 717 | * The file got changed. 718 | */ 719 | Changed = 2, 720 | /** 721 | * The file got deleted. 722 | */ 723 | Deleted = 3 724 | } 725 | ``` 726 | ```typescript 727 | /** 728 | * An event describing a file change. 729 | */ 730 | interface FileEvent { 731 | /** 732 | * The file's uri. 733 | */ 734 | uri: string; 735 | /** 736 | * The change type. 737 | */ 738 | type: number; 739 | } 740 | ``` 741 | 742 | #### PublishDiagnostics Notification 743 | 744 | Diagnostics notification are sent from the server to the client to signal results of validation runs. 745 | 746 | _Notification_ 747 | * method: 'textDocument/publishDiagnostics' 748 | * params: `PublishDiagnosticsParams` defined as follows: 749 | ```typescript 750 | interface PublishDiagnosticsParams { 751 | /** 752 | * The URI for which diagnostic information is reported. 753 | */ 754 | uri: string; 755 | 756 | /** 757 | * An array of diagnostic information items. 758 | */ 759 | diagnostics: Diagnostic[]; 760 | } 761 | ``` 762 | 763 | #### Completion Request 764 | 765 | The Completion request is sent from the client to the server to compute completion items at a given cursor position. Completion items are presented in the [IntelliSense](https://code.visualstudio.com/docs/editor/editingevolved#_intellisense) user interface. If computing complete completion items is expensive servers can additional provide a handler for the resolve completion item request. This request is send when a completion item is selected in the user interface. 766 | 767 | _Request_ 768 | * method: 'textDocument/completion' 769 | * params: [`TextDocumentPosition`](#textdocumentposition) 770 | 771 | _Response_ 772 | * result: `CompletionItem[]` 773 | ```typescript 774 | interface CompletionItem { 775 | /** 776 | * The label of this completion item. By default 777 | * also the text that is inserted when selecting 778 | * this completion. 779 | */ 780 | label: string; 781 | /** 782 | * The kind of this completion item. Based of the kind 783 | * an icon is chosen by the editor. 784 | */ 785 | kind?: number; 786 | /** 787 | * A human-readable string with additional information 788 | * about this item, like type or symbol information. 789 | */ 790 | detail?: string; 791 | /** 792 | * A human-readable string that represents a doc-comment. 793 | */ 794 | documentation?: string; 795 | /** 796 | * A string that shoud be used when comparing this item 797 | * with other items. When `falsy` the label is used. 798 | */ 799 | sortText?: string; 800 | /** 801 | * A string that should be used when filtering a set of 802 | * completion items. When `falsy` the label is used. 803 | */ 804 | filterText?: string; 805 | /** 806 | * A string that should be inserted a document when selecting 807 | * this completion. When `falsy` the label is used. 808 | */ 809 | insertText?: string; 810 | /** 811 | * An edit which is applied to a document when selecting 812 | * this completion. When an edit is provided the value of 813 | * insertText is ignored. 814 | */ 815 | textEdit?: TextEdit; 816 | /** 817 | * An data entry field that is preserved on a completion item between 818 | * a completion and a completion resolve request. 819 | */ 820 | data?: any 821 | } 822 | ``` 823 | Where `CompletionItemKind` is defined as follows: 824 | ```typescript 825 | /** 826 | * The kind of a completion entry. 827 | */ 828 | enum CompletionItemKind { 829 | Text = 1, 830 | Method = 2, 831 | Function = 3, 832 | Constructor = 4, 833 | Field = 5, 834 | Variable = 6, 835 | Class = 7, 836 | Interface = 8, 837 | Module = 9, 838 | Property = 10, 839 | Unit = 11, 840 | Value = 12, 841 | Enum = 13, 842 | Keyword = 14, 843 | Snippet = 15, 844 | Color = 16, 845 | File = 17, 846 | Reference = 18 847 | } 848 | ``` 849 | * error: code and message set in case an exception happens during the completion request. 850 | 851 | #### Completion Item Resolve Request 852 | 853 | The request is sent from the client to the server to resolve additional information for a given completion item. 854 | 855 | _Request_ 856 | * method: 'completionItem/resolve' 857 | * param: `CompletionItem` 858 | 859 | _Response_ 860 | * result: `CompletionItem` 861 | * error: code and message set in case an exception happens during the completion resolve request. 862 | 863 | #### Hover 864 | 865 | The hover request is sent from the client to the server to request hover information at a given text document position. 866 | 867 | _Request_ 868 | * method: 'textDocument/hover' 869 | * param: [`TextDocumentPosition`](#textdocumentposition) 870 | 871 | _Response_ 872 | * result: `Hover` defined as follows: 873 | ```typescript 874 | /** 875 | * The result of a hove request. 876 | */ 877 | interface Hover { 878 | /** 879 | * The hover's content 880 | */ 881 | contents: MarkedString | MarkedString[]; 882 | 883 | /** 884 | * An optional range 885 | */ 886 | range?: Range; 887 | } 888 | ``` 889 | Where `MarkedString` is defined as follows: 890 | ```typescript 891 | type MarkedString = string | { language: string; value: string }; 892 | ``` 893 | * error: code and message set in case an exception happens during the hover request. 894 | 895 | #### Signature Help 896 | 897 | The signature help request is sent from the client to the server to request signature information at a given cursor position. 898 | 899 | _Request_ 900 | * method: 'textDocument/signatureHelp' 901 | * param: [`TextDocumentPosition`](#textdocumentposition) 902 | 903 | _Response_ 904 | * result: `SignatureHelp` defined as follows: 905 | ```typescript 906 | /** 907 | * Signature help represents the signature of something 908 | * callable. There can be multiple signature but only one 909 | * active and only one active parameter. 910 | */ 911 | interface SignatureHelp { 912 | /** 913 | * One or more signatures. 914 | */ 915 | signatures: SignatureInformation[]; 916 | 917 | /** 918 | * The active signature. 919 | */ 920 | activeSignature?: number; 921 | 922 | /** 923 | * The active parameter of the active signature. 924 | */ 925 | activeParameter?: number; 926 | } 927 | ``` 928 | ```typescript 929 | /** 930 | * Represents the signature of something callable. A signature 931 | * can have a label, like a function-name, a doc-comment, and 932 | * a set of parameters. 933 | */ 934 | interface SignatureInformation { 935 | /** 936 | * The label of this signature. Will be shown in 937 | * the UI. 938 | */ 939 | label: string; 940 | 941 | /** 942 | * The human-readable doc-comment of this signature. Will be shown 943 | * in the UI but can be omitted. 944 | */ 945 | documentation?: string; 946 | 947 | /** 948 | * The parameters of this signature. 949 | */ 950 | parameters?: ParameterInformation[]; 951 | } 952 | ``` 953 | ```typescript 954 | /** 955 | * Represents a parameter of a callable-signature. A parameter can 956 | * have a label and a doc-comment. 957 | */ 958 | interface ParameterInformation { 959 | /** 960 | * The label of this signature. Will be shown in 961 | * the UI. 962 | */ 963 | label: string; 964 | 965 | /** 966 | * The human-readable doc-comment of this signature. Will be shown 967 | * in the UI but can be omitted. 968 | */ 969 | documentation?: string; 970 | } 971 | ``` 972 | * error: code and message set in case an exception happens during the signature help request. 973 | 974 | #### Goto Definition 975 | 976 | The goto definition request is sent from the client to the server to to resolve the defintion location of a symbol at a given text document position. 977 | 978 | _Request_ 979 | * method: 'textDocument/definition' 980 | * param: [`TextDocumentPosition`](#textdocumentposition) 981 | 982 | _Response_: 983 | * result: [`Location`](#location) | [`Location`](#location)[] 984 | * error: code and message set in case an exception happens during the definition request. 985 | 986 | #### Find References 987 | 988 | The references request is sent from the client to the server to resolve project-wide references for the symbol denoted by the given text document position. 989 | 990 | _Request_ 991 | * method: 'textDocument/references' 992 | * param: `ReferenceParams` defined as follows: 993 | ```typescript 994 | interface ReferenceParams extends TextDocumentPosition { 995 | context: ReferenceContext 996 | } 997 | ``` 998 | ```typescript 999 | interface ReferenceContext { 1000 | /** 1001 | * Include the declaration of the current symbol. 1002 | */ 1003 | includeDeclaration: boolean; 1004 | } 1005 | ``` 1006 | * error: code and message set in case an exception happens during the reference request. 1007 | 1008 | #### Document Highlights 1009 | 1010 | The document highlight request is sent from the client to the server to to resolve a document highlights for a given text document position. 1011 | 1012 | _Request_ 1013 | * method: 'textDocument/documentHighlight' 1014 | * param: [`TextDocumentPosition`](#textdocumentposition) 1015 | 1016 | _Response_ 1017 | * result: `DocumentHighlight` defined as follows: 1018 | ```typescript 1019 | /** 1020 | * A document highlight is a range inside a text document which deserves 1021 | * special attention. Usually a document highlight is visualized by changing 1022 | * the background color of its range. 1023 | */ 1024 | interface DocumentHighlight { 1025 | /** 1026 | * The range this highlight applies to. 1027 | */ 1028 | range: Range; 1029 | 1030 | /** 1031 | * The highlight kind, default is DocumentHighlightKind.Text. 1032 | */ 1033 | kind?: number; 1034 | } 1035 | ``` 1036 | ```typescript 1037 | /** 1038 | * A document highlight kind. 1039 | */ 1040 | enum DocumentHighlightKind { 1041 | /** 1042 | * A textual occurrance. 1043 | */ 1044 | Text = 1, 1045 | 1046 | /** 1047 | * Read-access of a symbol, like reading a variable. 1048 | */ 1049 | Read = 2, 1050 | 1051 | /** 1052 | * Write-access of a symbol, like writing to a variable. 1053 | */ 1054 | Write = 3 1055 | } 1056 | ``` 1057 | * error: code and message set in case an exception happens during the document highlight request. 1058 | 1059 | 1060 | #### Document Symbols 1061 | 1062 | The document symbol request is sent from the client to the server to list all symbols found in a given text document. 1063 | 1064 | _Request_ 1065 | * method: 'textDocument/documentSymbol' 1066 | * param: [`TextDocumentIdentifier`](#textdocumentidentifier) 1067 | 1068 | _Response_ 1069 | * result: `SymbolInformation`[] defined as follows: 1070 | ```typescript 1071 | /** 1072 | * Represents information about programming constructs like variables, classes, 1073 | * interfaces etc. 1074 | */ 1075 | interface SymbolInformation { 1076 | /** 1077 | * The name of this symbol. 1078 | */ 1079 | name: string; 1080 | 1081 | /** 1082 | * The kind of this symbol. 1083 | */ 1084 | kind: number; 1085 | 1086 | /** 1087 | * The location of this symbol. 1088 | */ 1089 | location: Location; 1090 | 1091 | /** 1092 | * The name of the symbol containing this symbol. 1093 | */ 1094 | containerName?: string; 1095 | } 1096 | ``` 1097 | Where the `kind` is defined like this: 1098 | ```typescript 1099 | /** 1100 | * A symbol kind. 1101 | */ 1102 | export enum SymbolKind { 1103 | File = 1, 1104 | Module = 2, 1105 | Namespace = 3, 1106 | Package = 4, 1107 | Class = 5, 1108 | Method = 6, 1109 | Property = 7, 1110 | Field = 8, 1111 | Constructor = 9, 1112 | Enum = 10, 1113 | Interface = 11, 1114 | Function = 12, 1115 | Variable = 13, 1116 | Constant = 14, 1117 | String = 15, 1118 | Number = 16, 1119 | Boolean = 17, 1120 | Array = 18, 1121 | } 1122 | ``` 1123 | * error: code and message set in case an exception happens during the document symbol request. 1124 | 1125 | #### Workspace Symbols 1126 | 1127 | The workspace symbol request is sent from the client to the server to list project-wide symbols matching the query string. 1128 | 1129 | _Request_ 1130 | * method: 'workspace/symbol' 1131 | * param: `WorkspaceSymbolParams` defined as follows: 1132 | ```typescript 1133 | /** 1134 | * The parameters of a Workspace Symbol Request. 1135 | */ 1136 | interface WorkspaceSymbolParams { 1137 | /** 1138 | * A non-empty query string 1139 | */ 1140 | query: string; 1141 | } 1142 | ``` 1143 | 1144 | _Response_ 1145 | * result: `SymbolInformation[]` as defined above. 1146 | * error: code and message set in case an exception happens during the workspace symbol request. 1147 | 1148 | #### Code Action 1149 | 1150 | The code action request is sent from the client to the server to compute commands for a given text document and range. The request is trigger when the user moves the cursor into an problem marker in the editor or presses the lightbulb associated with a marker. 1151 | 1152 | _Request_ 1153 | * method: 'textDocument/codeAction' 1154 | * param: `CodeActionParams` defined as follows: 1155 | ```typescript 1156 | /** 1157 | * Params for the CodeActionRequest 1158 | */ 1159 | interface CodeActionParams { 1160 | /** 1161 | * The document in which the command was invoked. 1162 | */ 1163 | textDocument: TextDocumentIdentifier; 1164 | 1165 | /** 1166 | * The range for which the command was invoked. 1167 | */ 1168 | range: Range; 1169 | 1170 | /** 1171 | * Context carrying additional information. 1172 | */ 1173 | context: CodeActionContext; 1174 | } 1175 | ``` 1176 | ```typescript 1177 | /** 1178 | * Contains additional diagnostic information about the context in which 1179 | * a code action is run. 1180 | */ 1181 | interface CodeActionContext { 1182 | /** 1183 | * An array of diagnostics. 1184 | */ 1185 | diagnostics: Diagnostic[]; 1186 | } 1187 | ``` 1188 | 1189 | _Response_ 1190 | * result: [`Command[]`](#command) defined as follows: 1191 | * error: code and message set in case an exception happens during the code action request. 1192 | 1193 | #### Code Lens 1194 | 1195 | The code lens request is sent from the client to the server to compute code lenses for a given text document. 1196 | 1197 | _Request_ 1198 | * method: 'textDocument/codeLens' 1199 | * param: [`TextDocumentIdentifier`](#textdocumentidentifier) 1200 | 1201 | _Response_ 1202 | * result: `CodeLens[]` defined as follows: 1203 | ```typescript 1204 | /** 1205 | * A code lens represents a command that should be shown along with 1206 | * source text, like the number of references, a way to run tests, etc. 1207 | * 1208 | * A code lens is _unresolved_ when no command is associated to it. For performance 1209 | * reasons the creation of a code lens and resolving should be done to two stages. 1210 | */ 1211 | export interface CodeLens { 1212 | /** 1213 | * The range in which this code lens is valid. Should only span a single line. 1214 | */ 1215 | range: Range; 1216 | 1217 | /** 1218 | * The command this code lens represents. 1219 | */ 1220 | command?: Command; 1221 | 1222 | /** 1223 | * An data entry field that is preserved on a code lens item between 1224 | * a code lens and a code lens resolve request. 1225 | */ 1226 | data?: any 1227 | } 1228 | ``` 1229 | * error: code and message set in case an exception happens during the code lens request. 1230 | 1231 | #### Code Lens Resolve 1232 | 1233 | The code lens resolve request is sent from the clien to the server to resolve the command for a given code lens item. 1234 | 1235 | _Request_ 1236 | * method: 'codeLens/resolve' 1237 | * param: `CodeLens` 1238 | 1239 | _Response_ 1240 | * result: `CodeLens` 1241 | * error: code and message set in case an exception happens during the code lens resolve request. 1242 | 1243 | #### Document Formatting 1244 | 1245 | The document formatting resquest is sent from the server to the client to format a whole document. 1246 | 1247 | _Request_ 1248 | * method: 'textDocument/formatting' 1249 | * param: `DocumentFormattingParams` defined as follows 1250 | ```typescript 1251 | interface DocumentFormattingParams { 1252 | /** 1253 | * The document to format. 1254 | */ 1255 | textDocument: TextDocumentIdentifier; 1256 | 1257 | /** 1258 | * The format options 1259 | */ 1260 | options: FormattingOptions; 1261 | } 1262 | ``` 1263 | ```typescript 1264 | /** 1265 | * Value-object describing what options formatting should use. 1266 | */ 1267 | interface FormattingOptions { 1268 | /** 1269 | * Size of a tab in spaces. 1270 | */ 1271 | tabSize: number; 1272 | 1273 | /** 1274 | * Prefer spaces over tabs. 1275 | */ 1276 | insertSpaces: boolean; 1277 | 1278 | /** 1279 | * Signature for further properties. 1280 | */ 1281 | [key: string]: boolean | number | string; 1282 | } 1283 | ``` 1284 | 1285 | _Response_ 1286 | * result: [`TextEdit[]`](#textedit) describing the modification to the document to be formatted. 1287 | * error: code and message set in case an exception happens during the formatting request. 1288 | 1289 | #### Document Range Formatting 1290 | 1291 | The document range formatting request is sent from the client to the server to format a given range in a document. 1292 | 1293 | _Request_ 1294 | * method: 'textDocument/rangeFormatting', 1295 | * param: `DocumentRangeFormattingParams` defined as follows 1296 | ```typescript 1297 | interface DocumentRangeFormattingParams { 1298 | /** 1299 | * The document to format. 1300 | */ 1301 | textDocument: TextDocumentIdentifier; 1302 | 1303 | /** 1304 | * The range to format 1305 | */ 1306 | range: Range; 1307 | 1308 | /** 1309 | * The format options 1310 | */ 1311 | options: FormattingOptions; 1312 | } 1313 | ``` 1314 | 1315 | _Response_ 1316 | * result: [`TextEdit[]`](#textedit) describing the modification to the document to be formatted. 1317 | * error: code and message set in case an exception happens during the range formatting request. 1318 | 1319 | #### Document on Type Formatting 1320 | 1321 | The document on type formatting request is sent from the client to the server to format parts of the document during typing. 1322 | 1323 | _Request_ 1324 | * method: 'textDocument/onTypeFormatting' 1325 | * param: `DocumentOnTypeFormattingParams` defined as follows 1326 | ```typescript 1327 | interface DocumentOnTypeFormattingParams { 1328 | /** 1329 | * The document to format. 1330 | */ 1331 | textDocument: TextDocumentIdentifier; 1332 | 1333 | /** 1334 | * The position at which this request was send. 1335 | */ 1336 | position: Position; 1337 | 1338 | /** 1339 | * The character that has been typed. 1340 | */ 1341 | ch: string; 1342 | 1343 | /** 1344 | * The format options. 1345 | */ 1346 | options: FormattingOptions; 1347 | } 1348 | ``` 1349 | 1350 | _Response_ 1351 | * result: [`TextEdit[]`](#textedit) describing the modification to the document. 1352 | * error: code and message set in case an exception happens during the range formatting request. 1353 | 1354 | #### Rename 1355 | 1356 | The rename request is sent from the client to the server to do a workspace wide rename of a symbol. 1357 | 1358 | _Request_ 1359 | * method: 'textDocument/rename' 1360 | * param: `RenameParams` defined as follows 1361 | ```typescript 1362 | export interface RenameParams { 1363 | /** 1364 | * The document to format. 1365 | */ 1366 | textDocument: TextDocumentIdentifier; 1367 | 1368 | /** 1369 | * The position at which this request was send. 1370 | */ 1371 | position: Position; 1372 | 1373 | /** 1374 | * The new name of the symbol. If the given name is not valid the 1375 | * request must return a [ResponseError](#ResponseError) with an 1376 | * appropriate message set. 1377 | */ 1378 | newName: string; 1379 | } 1380 | ``` 1381 | 1382 | _Response_ 1383 | * result: [`WorkspaceEdit`](#workspaceedit) describing the modification to the workspace. 1384 | * error: code and message set in case an exception happens during the rename request. 1385 | -------------------------------------------------------------------------------- /versions/protocol-2-x.md: -------------------------------------------------------------------------------- 1 | # Language Server Protocol 2 | 3 | This document describes version 2.0 - 2.1 of the language server protocol. Changes are marked with a change or new bar on the left hand side. Below is a summary of the major changes compared to version 1.0: 4 | 5 | - Consistent use of properties on request param objects. These properties are now structured like parameters in API's. So for example if an API takes a text document as the first parameter the corresponding parameter literal in the JSON RPC protocol now has a property `textDocument`. 6 | - Consistent support for language identifiers. This means that the language ID is passed to the server via the open notification. Further references to the text document don't transfer this information anymore. 7 | - Support for version numbers on documents. The initial version number is sent to the server via the open notification. Document change notification do carry information about version numbers as well. 8 | - Support for request cancellation. 9 | - Interface naming: using consistent names without `I` prefix. 10 | 11 | The 1.x version of this document can be found [here](https://github.com/Microsoft/language-server-protocol/blob/master/versions/protocol-1-x.md). 12 | 13 | ## Messages overview 14 | 15 | General 16 | 17 | * :leftwards_arrow_with_hook: [initialize](#initialize) 18 | * :leftwards_arrow_with_hook: [shutdown](#shutdown) 19 | * :arrow_right: [exit](#exit) 20 | * :arrow_right: [$/cancelRequest](#cancelRequest) 21 | 22 | Window 23 | 24 | * :arrow_left: [window/showMessage](#window_showMessage) 25 | * :arrow_right_hook: [window/showMessageRequest](#window_showMessageRequest) 26 | * :arrow_left: [window/logMessage](#window_logMessage) 27 | * :arrow_left: [telemetry/event](#telemetry_event) 28 | 29 | Workspace 30 | 31 | * :arrow_right: [workspace/didChangeConfiguration](#workspace_didChangeConfiguration) 32 | * :arrow_right: [workspace/didChangeWatchedFiles](#workspace_didChangeWatchedFiles) 33 | * :leftwards_arrow_with_hook: [workspace/symbol](#workspace_symbol) 34 | 35 | Document 36 | 37 | * :arrow_left: [textDocument/publishDiagnostics](#textDocument_publishDiagnostics) 38 | * :arrow_right: [textDocument/didChange](#textDocument_didChange) 39 | * :arrow_right: [textDocument/didClose](#textDocument_didClose) 40 | * :arrow_right: [textDocument/didOpen](#textDocument_didOpen) 41 | * :arrow_right: [textDocument/didSave](#textDocument_didSave) 42 | * :leftwards_arrow_with_hook: [textDocument/completion](#textDocument_completion) 43 | * :leftwards_arrow_with_hook: [completionItem/resolve](#completionItem_resolve) 44 | * :leftwards_arrow_with_hook: [textDocument/hover](#textDocument_hover) 45 | * :leftwards_arrow_with_hook: [textDocument/signatureHelp](#textDocument_signatureHelp) 46 | * :leftwards_arrow_with_hook: [textDocument/references](#textDocument_references) 47 | * :leftwards_arrow_with_hook: [textDocument/documentHighlight](#textDocument_documentHighlight) 48 | * :leftwards_arrow_with_hook: [textDocument/documentSymbol](#textDocument_documentSymbol) 49 | * :leftwards_arrow_with_hook: [textDocument/formatting](#textDocument_formatting) 50 | * :leftwards_arrow_with_hook: [textDocument/rangeFormatting](#textDocument_rangeFormatting) 51 | * :leftwards_arrow_with_hook: [textDocument/onTypeFormatting](#textDocument_onTypeFormatting) 52 | * :leftwards_arrow_with_hook: [textDocument/definition](#textDocument_definition) 53 | * :leftwards_arrow_with_hook: [textDocument/codeAction](#textDocument_codeAction) 54 | * :leftwards_arrow_with_hook: [textDocument/codeLens](#textDocument_codeLens) 55 | * :leftwards_arrow_with_hook: [codeLens/resolve](#codeLens_resolve) 56 | * :leftwards_arrow_with_hook: [textDocument/documentLink](#textDocument_documentLink) 57 | * :leftwards_arrow_with_hook: [documentLink/resolve](#documentLink_resolve) 58 | * :leftwards_arrow_with_hook: [textDocument/rename](#textDocument_rename) 59 | 60 | ## Base Protocol 61 | 62 | The base protocol consists of a header and a content part (comparable to HTTP). The header and content part are 63 | separated by a '\r\n'. 64 | 65 | ### Header Part 66 | 67 | The header part consists of header fields. Each header field is comprised of a name and a value, 68 | separated by ': ' (a colon and a space). 69 | Each header field is terminated by '\r\n'. 70 | Considering the last header field and the overall header itself are each terminated with '\r\n', 71 | and that at least one header is mandatory, this means that two '\r\n' sequences always 72 | immediately precede the content part of a message. 73 | 74 | Currently the following header fields are supported: 75 | 76 | | Header Field Name | Value Type | Description | 77 | |:------------------|:------------|:------------| 78 | | Content-Length | number | The length of the content part in bytes. This header is required. | 79 | | Content-Type | string | The mime type of the content part. Defaults to application/vscode-jsonrpc; charset=utf8 | 80 | 81 | The header part is encoded using the 'ascii' encoding. This includes the '\r\n' separating the header and content part. 82 | 83 | ### Content Part 84 | 85 | Contains the actual content of the message. The content part of a message uses [JSON-RPC](http://www.jsonrpc.org/) to describe requests, responses and notifications. The content part is encoded using the charset provided in the Content-Type field. It defaults to 'utf8', which is the only encoding supported right now. 86 | 87 | 88 | ### Example: 89 | 90 | ``` 91 | Content-Length: ...\r\n 92 | \r\n 93 | { 94 | "jsonrpc": "2.0", 95 | "id": 1, 96 | "method": "textDocument/didOpen", 97 | "params": { 98 | ... 99 | } 100 | } 101 | ``` 102 | ### Base Protocol JSON structures 103 | 104 | The following TypeScript definitions describe the base [JSON-RPC protocol](http://www.jsonrpc.org/specification): 105 | 106 | #### Abstract Message 107 | 108 | A general message as defined by JSON-RPC. The language server protocol always uses "2.0" as the jsonrpc version. 109 | 110 | ```typescript 111 | interface Message { 112 | jsonrpc: string; 113 | } 114 | ``` 115 | #### RequestMessage 116 | 117 | A request message to describe a request between the client and the server. Every processed request must send a response back to the sender of the request. 118 | 119 | ```typescript 120 | interface RequestMessage extends Message { 121 | 122 | /** 123 | * The request id. 124 | */ 125 | id: number | string; 126 | 127 | /** 128 | * The method to be invoked. 129 | */ 130 | method: string; 131 | 132 | /** 133 | * The method's params. 134 | */ 135 | params?: any 136 | } 137 | ``` 138 | 139 | #### Response Message 140 | 141 | Response Message sent as a result of a request. 142 | 143 | ```typescript 144 | interface ResponseMessage extends Message { 145 | /** 146 | * The request id. 147 | */ 148 | id: number | string; 149 | 150 | /** 151 | * The result of a request. This can be omitted in 152 | * the case of an error. 153 | */ 154 | result?: any; 155 | 156 | /** 157 | * The error object in case a request fails. 158 | */ 159 | error?: ResponseError; 160 | } 161 | 162 | interface ResponseError { 163 | /** 164 | * A number indicating the error type that occurred. 165 | */ 166 | code: number; 167 | 168 | /** 169 | * A string providing a short description of the error. 170 | */ 171 | message: string; 172 | 173 | /** 174 | * A Primitive or Structured value that contains additional 175 | * information about the error. Can be omitted. 176 | */ 177 | data?: D; 178 | } 179 | 180 | export namespace ErrorCodes { 181 | export const ParseError: number = -32700; 182 | export const InvalidRequest: number = -32600; 183 | export const MethodNotFound: number = -32601; 184 | export const InvalidParams: number = -32602; 185 | export const InternalError: number = -32603; 186 | export const serverErrorStart: number = -32099; 187 | export const serverErrorEnd: number = -32000; 188 | } 189 | ``` 190 | #### Notification Message 191 | 192 | A notification message. A processed notification message must not send a response back. They work like events. 193 | 194 | ```typescript 195 | interface NotificationMessage extends Message { 196 | /** 197 | * The method to be invoked. 198 | */ 199 | method: string; 200 | 201 | /** 202 | * The notification's params. 203 | */ 204 | params?: any 205 | } 206 | ``` 207 | 208 | #### Cancellation Support 209 | 210 | >**New:** The base protocol now offers support for request cancellation. To cancel a request, a notification message with the following properties is sent: 211 | 212 | _Notification_: 213 | * method: '$/cancelRequest' 214 | * params: `CancelParams` defined as follows: 215 | ```typescript 216 | interface CancelParams { 217 | /** 218 | * The request id to cancel. 219 | */ 220 | id: number | string; 221 | } 222 | ``` 223 | 224 | A request that got canceled still needs to return from the server and send a response back. It can not be left open / hanging. This is in line with the JSON RPC protocol that requires that every request sends a response back. In addition it allows for returning partial results on cancel. 225 | 226 | ## Language Server Protocol 227 | 228 | The language server protocol defines a set of JSON-RPC request, response and notification messages which are exchanged using the above base protocol. This section starts describing the basic JSON structures used in the protocol. The document uses TypeScript interfaces to describe these. Based on the basic JSON structures, the actual requests with their responses and the notifications are described. 229 | 230 | The protocol currently assumes that one server serves one tool. There is currently no support in the protocol to share one server between different tools. Such a sharing would require additional protocol to either lock a document to support concurrent editing. 231 | 232 | ### Basic JSON Structures 233 | 234 | #### URI 235 | 236 | URI's are transferred as strings. The URI's format is defined in [http://tools.ietf.org/html/rfc3986](http://tools.ietf.org/html/rfc3986) 237 | 238 | ``` 239 | foo://example.com:8042/over/there?name=ferret#nose 240 | \_/ \______________/\_________/ \_________/ \__/ 241 | | | | | | 242 | scheme authority path query fragment 243 | | _____________________|__ 244 | / \ / \ 245 | urn:example:animal:ferret:nose 246 | ``` 247 | 248 | We also maintain a node module to parse a string into `scheme`, `authority`, `path`, `query`, and `fragment` URI components. The GitHub repository is [https://github.com/Microsoft/vscode-uri](https://github.com/Microsoft/vscode-uri) the npm module is [https://www.npmjs.com/package/vscode-uri](https://www.npmjs.com/package/vscode-uri). 249 | 250 | 251 | #### Position 252 | 253 | Position in a text document expressed as zero-based line and character offset. A position is between two characters like an 'insert' cursor in a editor. 254 | 255 | ```typescript 256 | interface Position { 257 | /** 258 | * Line position in a document (zero-based). 259 | */ 260 | line: number; 261 | 262 | /** 263 | * Character offset on a line in a document (zero-based). 264 | */ 265 | character: number; 266 | } 267 | ``` 268 | #### Range 269 | 270 | A range in a text document expressed as (zero-based) start and end positions. A range is comparable to a selection in an editor. Therefore the end position is exclusive. 271 | 272 | ```typescript 273 | interface Range { 274 | /** 275 | * The range's start position. 276 | */ 277 | start: Position; 278 | 279 | /** 280 | * The range's end position. 281 | */ 282 | end: Position; 283 | } 284 | ``` 285 | 286 | #### Location 287 | 288 | Represents a location inside a resource, such as a line inside a text file. 289 | ```typescript 290 | interface Location { 291 | uri: string; 292 | range: Range; 293 | } 294 | ``` 295 | 296 | #### Diagnostic 297 | 298 | Represents a diagnostic, such as a compiler error or warning. Diagnostic objects are only valid in the scope of a resource. 299 | 300 | ```typescript 301 | interface Diagnostic { 302 | /** 303 | * The range at which the message applies. 304 | */ 305 | range: Range; 306 | 307 | /** 308 | * The diagnostic's severity. Can be omitted. If omitted it is up to the 309 | * client to interpret diagnostics as error, warning, info or hint. 310 | */ 311 | severity?: number; 312 | 313 | /** 314 | * The diagnostic's code. Can be omitted. 315 | */ 316 | code?: number | string; 317 | 318 | /** 319 | * A human-readable string describing the source of this 320 | * diagnostic, e.g. 'typescript' or 'super lint'. 321 | */ 322 | source?: string; 323 | 324 | /** 325 | * The diagnostic's message. 326 | */ 327 | message: string; 328 | } 329 | ``` 330 | 331 | The protocol currently supports the following diagnostic severities: 332 | 333 | ```typescript 334 | enum DiagnosticSeverity { 335 | /** 336 | * Reports an error. 337 | */ 338 | Error = 1, 339 | /** 340 | * Reports a warning. 341 | */ 342 | Warning = 2, 343 | /** 344 | * Reports an information. 345 | */ 346 | Information = 3, 347 | /** 348 | * Reports a hint. 349 | */ 350 | Hint = 4 351 | } 352 | ``` 353 | 354 | #### Command 355 | 356 | Represents a reference to a command. Provides a title which will be used to represent a command in the UI. Commands are identitifed using a string identifier and the protocol currently doesn't specify a set of well known commands. So executing a command requires some tool extension code. 357 | 358 | ```typescript 359 | interface Command { 360 | /** 361 | * Title of the command, like `save`. 362 | */ 363 | title: string; 364 | /** 365 | * The identifier of the actual command handler. 366 | */ 367 | command: string; 368 | /** 369 | * Arguments that the command handler should be 370 | * invoked with. 371 | */ 372 | arguments?: any[]; 373 | } 374 | ``` 375 | 376 | #### TextEdit 377 | 378 | A textual edit applicable to a text document. 379 | 380 | ```typescript 381 | interface TextEdit { 382 | /** 383 | * The range of the text document to be manipulated. To insert 384 | * text into a document create a range where start === end. 385 | */ 386 | range: Range; 387 | 388 | /** 389 | * The string to be inserted. For delete operations use an 390 | * empty string. 391 | */ 392 | newText: string; 393 | } 394 | ``` 395 | 396 | If n `TextEdit`s are applied to a text document all text edits describe changes to the initial document version. Execution wise text edits should applied from the bottom to the top of the text document. Overlapping text edits are not supported. 397 | 398 | #### WorkspaceEdit 399 | 400 | A workspace edit represents changes to many resources managed in the workspace. 401 | 402 | ```typescript 403 | interface WorkspaceEdit { 404 | /** 405 | * Holds changes to existing resources. 406 | */ 407 | changes: { [uri: string]: TextEdit[]; }; 408 | } 409 | ``` 410 | 411 | #### TextDocumentIdentifier 412 | 413 | Text documents are identified using a URI. On the protocol level, URIs are passed as strings. The corresponding JSON structure looks like this: 414 | ```typescript 415 | interface TextDocumentIdentifier { 416 | /** 417 | * The text document's URI. 418 | */ 419 | uri: string; 420 | } 421 | ``` 422 | 423 | #### TextDocumentItem 424 | 425 | >**New:** An item to transfer a text document from the client to the server. 426 | 427 | ```typescript 428 | interface TextDocumentItem { 429 | /** 430 | * The text document's URI. 431 | */ 432 | uri: string; 433 | 434 | /** 435 | * The text document's language identifier. 436 | */ 437 | languageId: string; 438 | 439 | /** 440 | * The version number of this document (it will strictly increase after each 441 | * change, including undo/redo). 442 | */ 443 | version: number; 444 | 445 | /** 446 | * The content of the opened text document. 447 | */ 448 | text: string; 449 | } 450 | ``` 451 | 452 | #### VersionedTextDocumentIdentifier 453 | 454 | >**New:** An identifier to denote a specific version of a text document. 455 | 456 | ```typescript 457 | interface VersionedTextDocumentIdentifier extends TextDocumentIdentifier { 458 | /** 459 | * The version number of this document. 460 | */ 461 | version: number; 462 | } 463 | ``` 464 | 465 | #### TextDocumentPositionParams 466 | 467 | >**Changed:** Was `TextDocumentPosition` in 1.0 with inlined parameters 468 | 469 | A parameter literal used in requests to pass a text document and a position inside that document. 470 | 471 | ```typescript 472 | interface TextDocumentPositionParams { 473 | /** 474 | * The text document. 475 | */ 476 | textDocument: TextDocumentIdentifier; 477 | 478 | /** 479 | * The position inside the text document. 480 | */ 481 | position: Position; 482 | } 483 | ``` 484 | 485 | ### Actual Protocol 486 | 487 | This section documents the actual language server protocol. It uses the following format: 488 | 489 | * a header describing the request 490 | * a _Request_ section describing the format of the request sent. The method is a string identifying the request the params are documented using a TypeScript interface 491 | * a _Response_ section describing the format of the response. The result item describes the returned data in case of a success. The error.data describes the returned data in case of an error. Please remember that in case of a failure the response already contains an error.code and an error.message field. These fields are only speced if the protocol forces the use of certain error codes or messages. In cases where the server can decide on these values freely they aren't listed here. 492 | 493 | #### Initialize Request 494 | 495 | The initialize request is sent as the first request from the client to the server. If the server receives request or notification before the `initialize` request it should act as follows: 496 | 497 | * for a request the respond should be errored with `code: -32001`. The message can be picked by the server. 498 | * notifications should be dropped. 499 | 500 | _Request_ 501 | * method: 'initialize' 502 | * params: `InitializeParams` defined as follows: 503 | ```typescript 504 | interface InitializeParams { 505 | /** 506 | * The process Id of the parent process that started 507 | * the server. Is null if the process has not been started by another process. 508 | * If the parent process is not alive then the server should exit (see exit notification) its process. 509 | */ 510 | processId?: number; 511 | 512 | /** 513 | * The rootPath of the workspace. Is null 514 | * if no folder is open. 515 | */ 516 | rootPath?: string; 517 | 518 | /** 519 | * User provided initialization options. 520 | */ 521 | initializationOptions?: any; 522 | 523 | /** 524 | * The capabilities provided by the client (editor) 525 | */ 526 | capabilities: ClientCapabilities; 527 | } 528 | ``` 529 | Where `ClientCapabilities` are currently empty: 530 | ```typescript 531 | interface ClientCapabilities { 532 | } 533 | ``` 534 | 535 | _Response_ 536 | * result: `InitializeResult` defined as follows: 537 | ```typescript 538 | interface InitializeResult { 539 | /** 540 | * The capabilities the language server provides. 541 | */ 542 | capabilities: ServerCapabilities; 543 | } 544 | ``` 545 | * error.data: 546 | ```typescript 547 | interface InitializeError { 548 | /** 549 | * Indicates whether the client should retry to send the 550 | * initilize request after showing the message provided 551 | * in the ResponseError. 552 | */ 553 | retry: boolean; 554 | } 555 | ``` 556 | The server can signal the following capabilities: 557 | ```typescript 558 | /** 559 | * Defines how the host (editor) should sync document changes to the language server. 560 | */ 561 | enum TextDocumentSyncKind { 562 | /** 563 | * Documents should not be synced at all. 564 | */ 565 | None = 0, 566 | /** 567 | * Documents are synced by always sending the full content of the document. 568 | */ 569 | Full = 1, 570 | /** 571 | * Documents are synced by sending the full content on open. After that only incremental 572 | * updates to the document are sent. 573 | */ 574 | Incremental = 2 575 | } 576 | ``` 577 | ```typescript 578 | /** 579 | * Completion options. 580 | */ 581 | interface CompletionOptions { 582 | /** 583 | * The server provides support to resolve additional information for a completion item. 584 | */ 585 | resolveProvider?: boolean; 586 | 587 | /** 588 | * The characters that trigger completion automatically. 589 | */ 590 | triggerCharacters?: string[]; 591 | } 592 | ``` 593 | ```typescript 594 | /** 595 | * Signature help options. 596 | */ 597 | interface SignatureHelpOptions { 598 | /** 599 | * The characters that trigger signature help automatically. 600 | */ 601 | triggerCharacters?: string[]; 602 | } 603 | ``` 604 | ```typescript 605 | /** 606 | * Code Lens options. 607 | */ 608 | interface CodeLensOptions { 609 | /** 610 | * Code lens has a resolve provider as well. 611 | */ 612 | resolveProvider?: boolean; 613 | } 614 | ``` 615 | ```typescript 616 | /** 617 | * Format document on type options 618 | */ 619 | interface DocumentOnTypeFormattingOptions { 620 | /** 621 | * A character on which formatting should be triggered, like `}`. 622 | */ 623 | firstTriggerCharacter: string; 624 | /** 625 | * More trigger characters. 626 | */ 627 | moreTriggerCharacter?: string[] 628 | } 629 | ``` 630 | ```typescript 631 | interface ServerCapabilities { 632 | /** 633 | * Defines how text documents are synced. 634 | */ 635 | textDocumentSync?: number; 636 | /** 637 | * The server provides hover support. 638 | */ 639 | hoverProvider?: boolean; 640 | /** 641 | * The server provides completion support. 642 | */ 643 | completionProvider?: CompletionOptions; 644 | /** 645 | * The server provides signature help support. 646 | */ 647 | signatureHelpProvider?: SignatureHelpOptions; 648 | /** 649 | * The server provides goto definition support. 650 | */ 651 | definitionProvider?: boolean; 652 | /** 653 | * The server provides find references support. 654 | */ 655 | referencesProvider?: boolean; 656 | /** 657 | * The server provides document highlight support. 658 | */ 659 | documentHighlightProvider?: boolean; 660 | /** 661 | * The server provides document symbol support. 662 | */ 663 | documentSymbolProvider?: boolean; 664 | /** 665 | * The server provides workspace symbol support. 666 | */ 667 | workspaceSymbolProvider?: boolean; 668 | /** 669 | * The server provides code actions. 670 | */ 671 | codeActionProvider?: boolean; 672 | /** 673 | * The server provides code lens. 674 | */ 675 | codeLensProvider?: CodeLensOptions; 676 | /** 677 | * The server provides document formatting. 678 | */ 679 | documentFormattingProvider?: boolean; 680 | /** 681 | * The server provides document range formatting. 682 | */ 683 | documentRangeFormattingProvider?: boolean; 684 | /** 685 | * The server provides document formatting on typing. 686 | */ 687 | documentOnTypeFormattingProvider?: DocumentOnTypeFormattingOptions; 688 | /** 689 | * The server provides rename support. 690 | */ 691 | renameProvider?: boolean 692 | } 693 | ``` 694 | 695 | #### Shutdown Request 696 | 697 | The shutdown request is sent from the client to the server. It asks the server to shut down, but to not exit (otherwise the response might not be delivered correctly to the client). There is a separate exit notification that asks the server to exit. 698 | 699 | _Request_ 700 | * method: 'shutdown' 701 | * params: undefined 702 | 703 | _Response_ 704 | * result: undefined 705 | * error: code and message set in case an exception happens during shutdown request. 706 | 707 | #### Exit Notification 708 | 709 | A notification to ask the server to exit its process. 710 | The server should exit with `success` code 0 if the shutdown request has been received before; otherwise with `error` code 1. 711 | 712 | _Notification_ 713 | * method: 'exit' 714 | * params: undefined 715 | 716 | #### ShowMessage Notification 717 | 718 | The show message notification is sent from a server to a client to ask the client to display a particular message in the user interface. 719 | 720 | _Notification_: 721 | * method: 'window/showMessage' 722 | * params: `ShowMessageParams` defined as follows: 723 | ```typescript 724 | interface ShowMessageParams { 725 | /** 726 | * The message type. See {@link MessageType}. 727 | */ 728 | type: number; 729 | 730 | /** 731 | * The actual message. 732 | */ 733 | message: string; 734 | } 735 | ``` 736 | Where the type is defined as follows: 737 | ```typescript 738 | enum MessageType { 739 | /** 740 | * An error message. 741 | */ 742 | Error = 1, 743 | /** 744 | * A warning message. 745 | */ 746 | Warning = 2, 747 | /** 748 | * An information message. 749 | */ 750 | Info = 3, 751 | /** 752 | * A log message. 753 | */ 754 | Log = 4 755 | } 756 | ``` 757 | 758 | #### ShowMessage Request 759 | 760 | >**New:** The show message request is sent from a server to a client to ask the client to display a particular message in the user interface. In addition to the show message notification the request allows to pass actions and to wait for an answer from the client. 761 | 762 | _Request_: 763 | * method: 'window/showMessageRequest' 764 | * params: `ShowMessageRequestParams` defined as follows: 765 | 766 | _Response_: 767 | * result: the selected `MessageActionItem` 768 | * error: code and message set in case an exception happens during showing a message. 769 | 770 | ```typescript 771 | interface ShowMessageRequestParams { 772 | /** 773 | * The message type. See {@link MessageType} 774 | */ 775 | type: number; 776 | 777 | /** 778 | * The actual message 779 | */ 780 | message: string; 781 | 782 | /** 783 | * The message action items to present. 784 | */ 785 | actions?: MessageActionItem[]; 786 | } 787 | ``` 788 | Where the `MessageActionItem` is defined as follows: 789 | ```typescript 790 | interface MessageActionItem { 791 | /** 792 | * A short title like 'Retry', 'Open Log' etc. 793 | */ 794 | title: string; 795 | } 796 | ``` 797 | 798 | #### LogMessage Notification 799 | 800 | The log message notification is sent from the server to the client to ask the client to log a particular message. 801 | 802 | _Notification_: 803 | * method: 'window/logMessage' 804 | * params: `LogMessageParams` defined as follows: 805 | ```typescript 806 | interface LogMessageParams { 807 | /** 808 | * The message type. See {@link MessageType} 809 | */ 810 | type: number; 811 | 812 | /** 813 | * The actual message 814 | */ 815 | message: string; 816 | } 817 | ``` 818 | Where type is defined as above. 819 | 820 | #### Telemetry Notification 821 | 822 | >**New:** The telemetry notification is sent from the server to the client to ask the client to log a telemetry event. 823 | 824 | _Notification_: 825 | * method: 'telemetry/event' 826 | * params: 'any' 827 | 828 | #### DidChangeConfiguration Notification 829 | 830 | A notification sent from the client to the server to signal the change of configuration settings. 831 | 832 | _Notification_: 833 | * method: 'workspace/didChangeConfiguration', 834 | * params: `DidChangeConfigurationParams` defined as follows: 835 | ```typescript 836 | interface DidChangeConfigurationParams { 837 | /** 838 | * The actual changed settings 839 | */ 840 | settings: any; 841 | } 842 | ``` 843 | 844 | #### DidOpenTextDocument Notification 845 | 846 | The document open notification is sent from the client to the server to signal newly opened text documents. The document's truth is now managed by the client and the server must not try to read the document's truth using the document's uri. 847 | 848 | _Notification_: 849 | * method: 'textDocument/didOpen' 850 | * params: `DidOpenTextDocumentParams` defined as follows: 851 | ```typescript 852 | interface DidOpenTextDocumentParams { 853 | /** 854 | * The document that was opened. 855 | */ 856 | textDocument: TextDocumentItem; 857 | } 858 | ``` 859 | 860 | #### DidChangeTextDocument Notification 861 | 862 | >**Changed:** The document change notification is sent from the client to the server to signal changes to a text document. In 2.0 the shape of the params has changed to include proper version numbers and language ids. 863 | 864 | _Notification_: 865 | * method: 'textDocument/didChange' 866 | * params: `DidChangeTextDocumentParams` defined as follows: 867 | ```typescript 868 | interface DidChangeTextDocumentParams { 869 | /** 870 | * The document that did change. The version number points 871 | * to the version after all provided content changes have 872 | * been applied. 873 | */ 874 | textDocument: VersionedTextDocumentIdentifier; 875 | 876 | /** 877 | * The actual content changes. 878 | */ 879 | contentChanges: TextDocumentContentChangeEvent[]; 880 | } 881 | ``` 882 | ```typescript 883 | /** 884 | * An event describing a change to a text document. If range and rangeLength are omitted 885 | * the new text is considered to be the full content of the document. 886 | */ 887 | interface TextDocumentContentChangeEvent { 888 | /** 889 | * The range of the document that changed. 890 | */ 891 | range?: Range; 892 | 893 | /** 894 | * The length of the range that got replaced. 895 | */ 896 | rangeLength?: number; 897 | 898 | /** 899 | * The new text of the document. 900 | */ 901 | text: string; 902 | } 903 | ``` 904 | 905 | #### DidCloseTextDocument Notification 906 | 907 | The document close notification is sent from the client to the server when the document got closed in the client. The document's truth now exists where the document's uri points to (e.g. if the document's uri is a file uri the truth now exists on disk). 908 | 909 | >**Changed:** In 2.0 the params are of type `DidCloseTextDocumentParams` which contains a reference to a text document. 910 | 911 | _Notification_: 912 | * method: 'textDocument/didClose' 913 | * params: `DidCloseTextDocumentParams` defined as follows: 914 | ```typescript 915 | interface DidCloseTextDocumentParams { 916 | /** 917 | * The document that was closed. 918 | */ 919 | textDocument: TextDocumentIdentifier; 920 | } 921 | ``` 922 | 923 | #### DidSaveTextDocument Notification 924 | 925 | >**New:** The document save notification is sent from the client to the server when the document was saved in the client. 926 | 927 | * method: 'textDocument/didSave' 928 | * params: `DidSaveTextDocumentParams` defined as follows: 929 | ```typescript 930 | interface DidSaveTextDocumentParams { 931 | /** 932 | * The document that was saved. 933 | */ 934 | textDocument: TextDocumentIdentifier; 935 | } 936 | ``` 937 | 938 | #### DidChangeWatchedFiles Notification 939 | 940 | The watched files notification is sent from the client to the server when the client detects changes to files watched by the language client. 941 | 942 | _Notification_: 943 | * method: 'workspace/didChangeWatchedFiles' 944 | * params: `DidChangeWatchedFilesParams` defined as follows: 945 | ```typescript 946 | interface DidChangeWatchedFilesParams { 947 | /** 948 | * The actual file events. 949 | */ 950 | changes: FileEvent[]; 951 | } 952 | ``` 953 | Where FileEvents are described as follows: 954 | ```typescript 955 | /** 956 | * The file event type. 957 | */ 958 | enum FileChangeType { 959 | /** 960 | * The file got created. 961 | */ 962 | Created = 1, 963 | /** 964 | * The file got changed. 965 | */ 966 | Changed = 2, 967 | /** 968 | * The file got deleted. 969 | */ 970 | Deleted = 3 971 | } 972 | ``` 973 | ```typescript 974 | /** 975 | * An event describing a file change. 976 | */ 977 | interface FileEvent { 978 | /** 979 | * The file's URI. 980 | */ 981 | uri: string; 982 | /** 983 | * The change type. 984 | */ 985 | type: number; 986 | } 987 | ``` 988 | 989 | #### PublishDiagnostics Notification 990 | 991 | Diagnostics notification are sent from the server to the client to signal results of validation runs. 992 | 993 | _Notification_ 994 | * method: 'textDocument/publishDiagnostics' 995 | * params: `PublishDiagnosticsParams` defined as follows: 996 | ```typescript 997 | interface PublishDiagnosticsParams { 998 | /** 999 | * The URI for which diagnostic information is reported. 1000 | */ 1001 | uri: string; 1002 | 1003 | /** 1004 | * An array of diagnostic information items. 1005 | */ 1006 | diagnostics: Diagnostic[]; 1007 | } 1008 | ``` 1009 | 1010 | #### Completion Request 1011 | 1012 | The Completion request is sent from the client to the server to compute completion items at a given cursor position. Completion items are presented in the [IntelliSense](https://code.visualstudio.com/docs/editor/editingevolved#_intellisense) user interface. If computing full completion items is expensive, servers can additionally provide a handler for the completion item resolve request ('completionItem/resolve'). This request is sent when a completion item is selected in the user interface. A typically use case is for example: the 'textDocument/completion' request doesn't fill in the `documentation` property for returned completion items since it is expensive to compute. When the item is selected in the user interface then a 'completionItem/resolve' request is sent with the selected completion item as a param. The returned completion item should have the documentation property filled in. 1013 | 1014 | >**Changed:** In 2.0 the request uses `TextDocumentPositionParams` with a proper `textDocument` and `position` property. In 1.0 the uri of the referenced text document was inlined into the params object. 1015 | 1016 | _Request_ 1017 | * method: 'textDocument/completion' 1018 | * params: [`TextDocumentPositionParams`](#textdocumentpositionparams) 1019 | 1020 | _Response_ 1021 | * result: `CompletionItem[] | CompletionList` 1022 | ```typescript 1023 | /** 1024 | * Represents a collection of [completion items](#CompletionItem) to be presented 1025 | * in the editor. 1026 | */ 1027 | interface CompletionList { 1028 | /** 1029 | * This list it not complete. Further typing should result in recomputing 1030 | * this list. 1031 | */ 1032 | isIncomplete: boolean; 1033 | /** 1034 | * The completion items. 1035 | */ 1036 | items: CompletionItem[]; 1037 | } 1038 | ``` 1039 | ```typescript 1040 | interface CompletionItem { 1041 | /** 1042 | * The label of this completion item. By default 1043 | * also the text that is inserted when selecting 1044 | * this completion. 1045 | */ 1046 | label: string; 1047 | /** 1048 | * The kind of this completion item. Based of the kind 1049 | * an icon is chosen by the editor. 1050 | */ 1051 | kind?: number; 1052 | /** 1053 | * A human-readable string with additional information 1054 | * about this item, like type or symbol information. 1055 | */ 1056 | detail?: string; 1057 | /** 1058 | * A human-readable string that represents a doc-comment. 1059 | */ 1060 | documentation?: string; 1061 | /** 1062 | * A string that shoud be used when comparing this item 1063 | * with other items. When `falsy` the label is used. 1064 | */ 1065 | sortText?: string; 1066 | /** 1067 | * A string that should be used when filtering a set of 1068 | * completion items. When `falsy` the label is used. 1069 | */ 1070 | filterText?: string; 1071 | /** 1072 | * A string that should be inserted a document when selecting 1073 | * this completion. When `falsy` the label is used. 1074 | */ 1075 | insertText?: string; 1076 | /** 1077 | * An edit which is applied to a document when selecting 1078 | * this completion. When an edit is provided the value of 1079 | * insertText is ignored. 1080 | */ 1081 | textEdit?: TextEdit; 1082 | /** 1083 | * An optional array of additional text edits that are applied when 1084 | * selecting this completion. Edits must not overlap with the main edit 1085 | * nor with themselves. 1086 | */ 1087 | additionalTextEdits?: TextEdit[]; 1088 | /** 1089 | * An optional command that is executed *after* inserting this completion. *Note* that 1090 | * additional modifications to the current document should be described with the 1091 | * additionalTextEdits-property. 1092 | */ 1093 | command?: Command; 1094 | /** 1095 | * An data entry field that is preserved on a completion item between 1096 | * a completion and a completion resolve request. 1097 | */ 1098 | data?: any 1099 | } 1100 | ``` 1101 | Where `CompletionItemKind` is defined as follows: 1102 | ```typescript 1103 | /** 1104 | * The kind of a completion entry. 1105 | */ 1106 | enum CompletionItemKind { 1107 | Text = 1, 1108 | Method = 2, 1109 | Function = 3, 1110 | Constructor = 4, 1111 | Field = 5, 1112 | Variable = 6, 1113 | Class = 7, 1114 | Interface = 8, 1115 | Module = 9, 1116 | Property = 10, 1117 | Unit = 11, 1118 | Value = 12, 1119 | Enum = 13, 1120 | Keyword = 14, 1121 | Snippet = 15, 1122 | Color = 16, 1123 | File = 17, 1124 | Reference = 18 1125 | } 1126 | ``` 1127 | * error: code and message set in case an exception happens during the completion request. 1128 | 1129 | #### Completion Item Resolve Request 1130 | 1131 | The request is sent from the client to the server to resolve additional information for a given completion item. 1132 | 1133 | _Request_ 1134 | * method: 'completionItem/resolve' 1135 | * params: `CompletionItem` 1136 | 1137 | _Response_ 1138 | * result: `CompletionItem` 1139 | * error: code and message set in case an exception happens during the completion resolve request. 1140 | 1141 | #### Hover Request 1142 | 1143 | The hover request is sent from the client to the server to request hover information at a given text document position. 1144 | 1145 | >**Changed:** In 2.0 the request uses `TextDocumentPositionParams` with a proper `textDocument` and `position` property. In 1.0 the uri of the referenced text document was inlined into the params object. 1146 | 1147 | _Request_ 1148 | * method: 'textDocument/hover' 1149 | * params: [`TextDocumentPositionParams`](#textdocumentpositionparams) 1150 | 1151 | _Response_ 1152 | * result: `Hover` defined as follows: 1153 | ```typescript 1154 | /** 1155 | * The result of a hover request. 1156 | */ 1157 | interface Hover { 1158 | /** 1159 | * The hover's content 1160 | */ 1161 | contents: MarkedString | MarkedString[]; 1162 | 1163 | /** 1164 | * An optional range is a range inside a text document 1165 | * that is used to visualize a hover, e.g. by changing the background color. 1166 | */ 1167 | range?: Range; 1168 | } 1169 | ``` 1170 | Where `MarkedString` is defined as follows: 1171 | ```typescript 1172 | /** 1173 | * The marked string is rendered: 1174 | * - as markdown if it is represented as a string 1175 | * - as code block of the given langauge if it is represented as a pair of a language and a value 1176 | * 1177 | * The pair of a language and a value is an equivalent to markdown: 1178 | * ```${language} 1179 | * ${value} 1180 | * ``` 1181 | */ 1182 | type MarkedString = string | { language: string; value: string }; 1183 | ``` 1184 | * error: code and message set in case an exception happens during the hover request. 1185 | 1186 | #### Signature Help Request 1187 | 1188 | The signature help request is sent from the client to the server to request signature information at a given cursor position. 1189 | 1190 | >**Changed:** In 2.0 the request uses `TextDocumentPositionParams` with proper `textDocument` and `position` properties. In 1.0 the uri of the referenced text document was inlined into the params object. 1191 | 1192 | _Request_ 1193 | * method: 'textDocument/signatureHelp' 1194 | * params: [`TextDocumentPositionParams`](#textdocumentpositionparams) 1195 | 1196 | _Response_ 1197 | * result: `SignatureHelp` defined as follows: 1198 | ```typescript 1199 | /** 1200 | * Signature help represents the signature of something 1201 | * callable. There can be multiple signature but only one 1202 | * active and only one active parameter. 1203 | */ 1204 | interface SignatureHelp { 1205 | /** 1206 | * One or more signatures. 1207 | */ 1208 | signatures: SignatureInformation[]; 1209 | 1210 | /** 1211 | * The active signature. 1212 | */ 1213 | activeSignature?: number; 1214 | 1215 | /** 1216 | * The active parameter of the active signature. 1217 | */ 1218 | activeParameter?: number; 1219 | } 1220 | ``` 1221 | ```typescript 1222 | /** 1223 | * Represents the signature of something callable. A signature 1224 | * can have a label, like a function-name, a doc-comment, and 1225 | * a set of parameters. 1226 | */ 1227 | interface SignatureInformation { 1228 | /** 1229 | * The label of this signature. Will be shown in 1230 | * the UI. 1231 | */ 1232 | label: string; 1233 | 1234 | /** 1235 | * The human-readable doc-comment of this signature. Will be shown 1236 | * in the UI but can be omitted. 1237 | */ 1238 | documentation?: string; 1239 | 1240 | /** 1241 | * The parameters of this signature. 1242 | */ 1243 | parameters?: ParameterInformation[]; 1244 | } 1245 | ``` 1246 | ```typescript 1247 | /** 1248 | * Represents a parameter of a callable-signature. A parameter can 1249 | * have a label and a doc-comment. 1250 | */ 1251 | interface ParameterInformation { 1252 | /** 1253 | * The label of this parameter. Will be shown in 1254 | * the UI. 1255 | */ 1256 | label: string; 1257 | 1258 | /** 1259 | * The human-readable doc-comment of this parameter. Will be shown 1260 | * in the UI but can be omitted. 1261 | */ 1262 | documentation?: string; 1263 | } 1264 | ``` 1265 | * error: code and message set in case an exception happens during the signature help request. 1266 | 1267 | #### Goto Definition Request 1268 | 1269 | The goto definition request is sent from the client to the server to resolve the definition location of a symbol at a given text document position. 1270 | 1271 | >**Changed:** In 2.0 the request uses `TextDocumentPositionParams` with proper `textDocument` and `position` properties. In 1.0 the uri of the referenced text document was inlined into the params object. 1272 | 1273 | _Request_ 1274 | * method: 'textDocument/definition' 1275 | * params: [`TextDocumentPositionParams`](#textdocumentpositionparams) 1276 | 1277 | _Response_: 1278 | * result: [`Location`](#location) | [`Location`](#location)[] 1279 | * error: code and message set in case an exception happens during the definition request. 1280 | 1281 | #### Find References Request 1282 | 1283 | The references request is sent from the client to the server to resolve project-wide references for the symbol denoted by the given text document position. 1284 | 1285 | >**Changed:** In 2.0 the request uses `TextDocumentPositionParams` with proper `textDocument` and `position` properties. In 1.0 the uri of the referenced text document was inlined into the params object. 1286 | 1287 | _Request_ 1288 | * method: 'textDocument/references' 1289 | * params: `ReferenceParams` defined as follows: 1290 | ```typescript 1291 | interface ReferenceParams extends TextDocumentPositionParams { 1292 | context: ReferenceContext 1293 | } 1294 | ``` 1295 | ```typescript 1296 | interface ReferenceContext { 1297 | /** 1298 | * Include the declaration of the current symbol. 1299 | */ 1300 | includeDeclaration: boolean; 1301 | } 1302 | ``` 1303 | _Response_: 1304 | * result: [`Location`](#location)[] 1305 | * error: code and message set in case an exception happens during the reference request. 1306 | 1307 | #### Document Highlights Request 1308 | 1309 | The document highlight request is sent from the client to the server to resolve a document highlights for a given text document position. 1310 | For programming languages this usually highlights all references to the symbol scoped to this file. However we kept 'textDocument/documentHighlight' 1311 | and 'textDocument/references' separate requests since the first one is allowed to be more fuzzy. Symbol matches usually have a `DocumentHighlightKind` 1312 | of `Read` or `Write` whereas fuzzy or textual matches use `Text`as the kind. 1313 | 1314 | >**Changed:** In 2.0 the request uses `TextDocumentPositionParams` with proper `textDocument` and `position` properties. In 1.0 the uri of the referenced text document was inlined into the params object. 1315 | 1316 | _Request_ 1317 | * method: 'textDocument/documentHighlight' 1318 | * params: [`TextDocumentPositionParams`](#textdocumentpositionparams) 1319 | 1320 | _Response_ 1321 | * result: `DocumentHighlight`[] defined as follows: 1322 | ```typescript 1323 | /** 1324 | * A document highlight is a range inside a text document which deserves 1325 | * special attention. Usually a document highlight is visualized by changing 1326 | * the background color of its range. 1327 | * 1328 | */ 1329 | interface DocumentHighlight { 1330 | /** 1331 | * The range this highlight applies to. 1332 | */ 1333 | range: Range; 1334 | 1335 | /** 1336 | * The highlight kind, default is DocumentHighlightKind.Text. 1337 | */ 1338 | kind?: number; 1339 | } 1340 | ``` 1341 | ```typescript 1342 | /** 1343 | * A document highlight kind. 1344 | */ 1345 | enum DocumentHighlightKind { 1346 | /** 1347 | * A textual occurrance. 1348 | */ 1349 | Text = 1, 1350 | 1351 | /** 1352 | * Read-access of a symbol, like reading a variable. 1353 | */ 1354 | Read = 2, 1355 | 1356 | /** 1357 | * Write-access of a symbol, like writing to a variable. 1358 | */ 1359 | Write = 3 1360 | } 1361 | ``` 1362 | * error: code and message set in case an exception happens during the document highlight request. 1363 | 1364 | 1365 | #### Document Symbols Request 1366 | 1367 | The document symbol request is sent from the client to the server to list all symbols found in a given text document. 1368 | 1369 | >**Changed:** In 2.0 the request uses `DocumentSymbolParams` instead of a single uri. 1370 | 1371 | _Request_ 1372 | * method: 'textDocument/documentSymbol' 1373 | * params: `DocumentSymbolParams` defined as follows: 1374 | ```typescript 1375 | interface DocumentSymbolParams { 1376 | /** 1377 | * The text document. 1378 | */ 1379 | textDocument: TextDocumentIdentifier; 1380 | } 1381 | ``` 1382 | 1383 | _Response_ 1384 | * result: `SymbolInformation`[] defined as follows: 1385 | ```typescript 1386 | /** 1387 | * Represents information about programming constructs like variables, classes, 1388 | * interfaces etc. 1389 | */ 1390 | interface SymbolInformation { 1391 | /** 1392 | * The name of this symbol. 1393 | */ 1394 | name: string; 1395 | 1396 | /** 1397 | * The kind of this symbol. 1398 | */ 1399 | kind: number; 1400 | 1401 | /** 1402 | * The location of this symbol. 1403 | */ 1404 | location: Location; 1405 | 1406 | /** 1407 | * The name of the symbol containing this symbol. 1408 | */ 1409 | containerName?: string; 1410 | } 1411 | ``` 1412 | Where the `kind` is defined like this: 1413 | ```typescript 1414 | /** 1415 | * A symbol kind. 1416 | */ 1417 | export enum SymbolKind { 1418 | File = 1, 1419 | Module = 2, 1420 | Namespace = 3, 1421 | Package = 4, 1422 | Class = 5, 1423 | Method = 6, 1424 | Property = 7, 1425 | Field = 8, 1426 | Constructor = 9, 1427 | Enum = 10, 1428 | Interface = 11, 1429 | Function = 12, 1430 | Variable = 13, 1431 | Constant = 14, 1432 | String = 15, 1433 | Number = 16, 1434 | Boolean = 17, 1435 | Array = 18, 1436 | } 1437 | ``` 1438 | * error: code and message set in case an exception happens during the document symbol request. 1439 | 1440 | #### Workspace Symbols Request 1441 | 1442 | The workspace symbol request is sent from the client to the server to list project-wide symbols matching the query string. 1443 | 1444 | _Request_ 1445 | * method: 'workspace/symbol' 1446 | * params: `WorkspaceSymbolParams` defined as follows: 1447 | ```typescript 1448 | /** 1449 | * The parameters of a Workspace Symbol Request. 1450 | */ 1451 | interface WorkspaceSymbolParams { 1452 | /** 1453 | * A non-empty query string 1454 | */ 1455 | query: string; 1456 | } 1457 | ``` 1458 | 1459 | _Response_ 1460 | * result: `SymbolInformation[]` as defined above. 1461 | * error: code and message set in case an exception happens during the workspace symbol request. 1462 | 1463 | #### Code Action Request 1464 | 1465 | The code action request is sent from the client to the server to compute commands for a given text document and range. The request is triggered when the user moves the cursor into a problem marker in the editor or presses the lightbulb associated with a marker. 1466 | 1467 | _Request_ 1468 | * method: 'textDocument/codeAction' 1469 | * params: `CodeActionParams` defined as follows: 1470 | ```typescript 1471 | /** 1472 | * Params for the CodeActionRequest 1473 | */ 1474 | interface CodeActionParams { 1475 | /** 1476 | * The document in which the command was invoked. 1477 | */ 1478 | textDocument: TextDocumentIdentifier; 1479 | 1480 | /** 1481 | * The range for which the command was invoked. 1482 | */ 1483 | range: Range; 1484 | 1485 | /** 1486 | * Context carrying additional information. 1487 | */ 1488 | context: CodeActionContext; 1489 | } 1490 | ``` 1491 | ```typescript 1492 | /** 1493 | * Contains additional diagnostic information about the context in which 1494 | * a code action is run. 1495 | */ 1496 | interface CodeActionContext { 1497 | /** 1498 | * An array of diagnostics. 1499 | */ 1500 | diagnostics: Diagnostic[]; 1501 | } 1502 | ``` 1503 | 1504 | _Response_ 1505 | * result: [`Command[]`](#command) defined as follows: 1506 | * error: code and message set in case an exception happens during the code action request. 1507 | 1508 | #### Code Lens Request 1509 | 1510 | The code lens request is sent from the client to the server to compute code lenses for a given text document. 1511 | 1512 | >**Changed:** In 2.0 the request uses `CodeLensParams` instead of a single uri. 1513 | 1514 | _Request_ 1515 | * method: 'textDocument/codeLens' 1516 | * params: `CodeLensParams` defined as follows: 1517 | ```typescript 1518 | interface CodeLensParams { 1519 | /** 1520 | * The document to request code lens for. 1521 | */ 1522 | textDocument: TextDocumentIdentifier; 1523 | } 1524 | ``` 1525 | 1526 | _Response_ 1527 | * result: `CodeLens[]` defined as follows: 1528 | ```typescript 1529 | /** 1530 | * A code lens represents a command that should be shown along with 1531 | * source text, like the number of references, a way to run tests, etc. 1532 | * 1533 | * A code lens is _unresolved_ when no command is associated to it. For performance 1534 | * reasons the creation of a code lens and resolving should be done in two stages. 1535 | */ 1536 | interface CodeLens { 1537 | /** 1538 | * The range in which this code lens is valid. Should only span a single line. 1539 | */ 1540 | range: Range; 1541 | 1542 | /** 1543 | * The command this code lens represents. 1544 | */ 1545 | command?: Command; 1546 | 1547 | /** 1548 | * A data entry field that is preserved on a code lens item between 1549 | * a code lens and a code lens resolve request. 1550 | */ 1551 | data?: any 1552 | } 1553 | ``` 1554 | * error: code and message set in case an exception happens during the code lens request. 1555 | 1556 | #### Code Lens Resolve Request 1557 | 1558 | The code lens resolve request is sent from the client to the server to resolve the command for a given code lens item. 1559 | 1560 | _Request_ 1561 | * method: 'codeLens/resolve' 1562 | * params: `CodeLens` 1563 | 1564 | _Response_ 1565 | * result: `CodeLens` 1566 | * error: code and message set in case an exception happens during the code lens resolve request. 1567 | 1568 | #### Document Link Request 1569 | 1570 | The document links request is sent from the client to the server to request the location of links in a document. 1571 | 1572 | _Request_ 1573 | * method: 'textDocument/documentLink' 1574 | * params: `DocumentLinkParams`, defined as follows 1575 | ```typescript 1576 | interface DocumentLinkParams { 1577 | /** 1578 | * The document to provide document links for. 1579 | */ 1580 | textDocument: TextDocumentIdentifier; 1581 | } 1582 | ``` 1583 | 1584 | _Response_ 1585 | * result: An array of `DocumentLink`, or `null` or `undefined`. 1586 | ``` 1587 | /** 1588 | * A document link is a range in a text document that links to an internal or external resource, like another 1589 | * text document or a web site. 1590 | */ 1591 | interface DocumentLink { 1592 | /** 1593 | * The range this link applies to. 1594 | */ 1595 | range: Range; 1596 | /** 1597 | * The uri this link points to. 1598 | */ 1599 | target: string; 1600 | } 1601 | ``` 1602 | * error: code and message set in case an exception happens during the document link request. 1603 | 1604 | #### Document Link Resolve Request 1605 | 1606 | The document link resolve request is sent from the client to the server to resolve the target of a given document link. 1607 | 1608 | _Request_ 1609 | * method: 'documentLink/resolve' 1610 | * params: `DocumentLink` 1611 | 1612 | _Response_ 1613 | * result: `DocumentLink` 1614 | * error: code and message set in case an exception happens during the document link resolve request. 1615 | 1616 | #### Document Formatting Request 1617 | 1618 | The document formatting request is sent from the server to the client to format a whole document. 1619 | 1620 | _Request_ 1621 | * method: 'textDocument/formatting' 1622 | * params: `DocumentFormattingParams` defined as follows 1623 | ```typescript 1624 | interface DocumentFormattingParams { 1625 | /** 1626 | * The document to format. 1627 | */ 1628 | textDocument: TextDocumentIdentifier; 1629 | 1630 | /** 1631 | * The format options. 1632 | */ 1633 | options: FormattingOptions; 1634 | } 1635 | ``` 1636 | ```typescript 1637 | /** 1638 | * Value-object describing what options formatting should use. 1639 | */ 1640 | interface FormattingOptions { 1641 | /** 1642 | * Size of a tab in spaces. 1643 | */ 1644 | tabSize: number; 1645 | 1646 | /** 1647 | * Prefer spaces over tabs. 1648 | */ 1649 | insertSpaces: boolean; 1650 | 1651 | /** 1652 | * Signature for further properties. 1653 | */ 1654 | [key: string]: boolean | number | string; 1655 | } 1656 | ``` 1657 | 1658 | _Response_ 1659 | * result: [`TextEdit[]`](#textedit) describing the modification to the document to be formatted. 1660 | * error: code and message set in case an exception happens during the formatting request. 1661 | 1662 | #### Document Range Formatting Request 1663 | 1664 | The document range formatting request is sent from the client to the server to format a given range in a document. 1665 | 1666 | _Request_ 1667 | * method: 'textDocument/rangeFormatting', 1668 | * params: `DocumentRangeFormattingParams` defined as follows 1669 | ```typescript 1670 | interface DocumentRangeFormattingParams { 1671 | /** 1672 | * The document to format. 1673 | */ 1674 | textDocument: TextDocumentIdentifier; 1675 | 1676 | /** 1677 | * The range to format 1678 | */ 1679 | range: Range; 1680 | 1681 | /** 1682 | * The format options 1683 | */ 1684 | options: FormattingOptions; 1685 | } 1686 | ``` 1687 | 1688 | _Response_ 1689 | * result: [`TextEdit[]`](#textedit) describing the modification to the document to be formatted. 1690 | * error: code and message set in case an exception happens during the range formatting request. 1691 | 1692 | #### Document on Type Formatting Request 1693 | 1694 | The document on type formatting request is sent from the client to the server to format parts of the document during typing. 1695 | 1696 | _Request_ 1697 | * method: 'textDocument/onTypeFormatting' 1698 | * params: `DocumentOnTypeFormattingParams` defined as follows 1699 | ```typescript 1700 | interface DocumentOnTypeFormattingParams { 1701 | /** 1702 | * The document to format. 1703 | */ 1704 | textDocument: TextDocumentIdentifier; 1705 | 1706 | /** 1707 | * The position at which this request was sent. 1708 | */ 1709 | position: Position; 1710 | 1711 | /** 1712 | * The character that has been typed. 1713 | */ 1714 | ch: string; 1715 | 1716 | /** 1717 | * The format options. 1718 | */ 1719 | options: FormattingOptions; 1720 | } 1721 | ``` 1722 | 1723 | _Response_ 1724 | * result: [`TextEdit[]`](#textedit) describing the modification to the document. 1725 | * error: code and message set in case an exception happens during the range formatting request. 1726 | 1727 | #### Rename Request 1728 | 1729 | The rename request is sent from the client to the server to perform a workspace-wide rename of a symbol. 1730 | 1731 | _Request_ 1732 | * method: 'textDocument/rename' 1733 | * params: `RenameParams` defined as follows 1734 | ```typescript 1735 | interface RenameParams { 1736 | /** 1737 | * The document to format. 1738 | */ 1739 | textDocument: TextDocumentIdentifier; 1740 | 1741 | /** 1742 | * The position at which this request was sent. 1743 | */ 1744 | position: Position; 1745 | 1746 | /** 1747 | * The new name of the symbol. If the given name is not valid the 1748 | * request must return a [ResponseError](#ResponseError) with an 1749 | * appropriate message set. 1750 | */ 1751 | newName: string; 1752 | } 1753 | ``` 1754 | 1755 | _Response_ 1756 | * result: [`WorkspaceEdit`](#workspaceedit) describing the modification to the workspace. 1757 | * error: code and message set in case an exception happens during the rename request. 1758 | 1759 | --------------------------------------------------------------------------------