From 099684c11cea132503057732da40855d0b2b572b Mon Sep 17 00:00:00 2001 From: Dirk Baeumer Date: Mon, 7 Mar 2022 16:03:50 +0100 Subject: [PATCH 1/2] Split specification --- _data/specifications.yml | 2 +- .../lsp/3.17/language/callHierarchy.md | 209 ++ .../lsp/3.17/language/codeAction.md | 459 +++ _specifications/lsp/3.17/language/codeLens.md | 144 + .../lsp/3.17/language/colorPresentation.md | 67 + .../lsp/3.17/language/documentColor.md | 114 + .../lsp/3.17/language/documentHighlight.md | 108 + .../lsp/3.17/language/documentLink.md | 121 + .../lsp/3.17/language/documentSymbol.md | 293 ++ .../lsp/3.17/language/foldingRange.md | 148 + .../lsp/3.17/language/formatting.md | 108 + .../lsp/3.17/language/implementation.md | 70 + .../lsp/3.17/language/linkedEditingRange.md | 84 + _specifications/lsp/3.17/language/moniker.md | 162 + .../lsp/3.17/language/onTypeFormatting.md | 72 + .../lsp/3.17/language/rangeFormatting.md | 69 + .../lsp/3.17/language/references.md | 67 + _specifications/lsp/3.17/language/rename.md | 130 + .../lsp/3.17/language/selectionRange.md | 94 + .../lsp/3.17/language/semanticTokens.md | 526 +++ .../3.17/specification.md} | 3084 +---------------- 21 files changed, 3066 insertions(+), 3065 deletions(-) create mode 100644 _specifications/lsp/3.17/language/callHierarchy.md create mode 100644 _specifications/lsp/3.17/language/codeAction.md create mode 100644 _specifications/lsp/3.17/language/codeLens.md create mode 100644 _specifications/lsp/3.17/language/colorPresentation.md create mode 100644 _specifications/lsp/3.17/language/documentColor.md create mode 100644 _specifications/lsp/3.17/language/documentHighlight.md create mode 100644 _specifications/lsp/3.17/language/documentLink.md create mode 100644 _specifications/lsp/3.17/language/documentSymbol.md create mode 100644 _specifications/lsp/3.17/language/foldingRange.md create mode 100644 _specifications/lsp/3.17/language/formatting.md create mode 100644 _specifications/lsp/3.17/language/implementation.md create mode 100644 _specifications/lsp/3.17/language/linkedEditingRange.md create mode 100644 _specifications/lsp/3.17/language/moniker.md create mode 100644 _specifications/lsp/3.17/language/onTypeFormatting.md create mode 100644 _specifications/lsp/3.17/language/rangeFormatting.md create mode 100644 _specifications/lsp/3.17/language/references.md create mode 100644 _specifications/lsp/3.17/language/rename.md create mode 100644 _specifications/lsp/3.17/language/selectionRange.md create mode 100644 _specifications/lsp/3.17/language/semanticTokens.md rename _specifications/{specification-3-17.md => lsp/3.17/specification.md} (67%) diff --git a/_data/specifications.yml b/_data/specifications.yml index 7d4dbe40a..3fb77b7cf 100644 --- a/_data/specifications.yml +++ b/_data/specifications.yml @@ -4,7 +4,7 @@ - title: 3.16 (Current) url: /specifications/specification-current - title: 3.17 (Upcoming) - url: /specifications/specification-3-17 + url: /specifications/lsp/3.17/specification - title: 3.15 (Previous) url: /specifications/specification-3-15 - title: LSIF diff --git a/_specifications/lsp/3.17/language/callHierarchy.md b/_specifications/lsp/3.17/language/callHierarchy.md new file mode 100644 index 000000000..4486ea14d --- /dev/null +++ b/_specifications/lsp/3.17/language/callHierarchy.md @@ -0,0 +1,209 @@ +#### Prepare Call Hierarchy Request (:leftwards_arrow_with_hook:) + +> *Since version 3.16.0* + +The call hierarchy request is sent from the client to the server to return a call hierarchy for the language element of given text document positions. The call hierarchy requests are executed in two steps: + + 1. first a call hierarchy item is resolved for the given text document position + 1. for a call hierarchy item the incoming or outgoing call hierarchy items are resolved. + +_Client Capability_: + +* property name (optional): `textDocument.callHierarchy` +* property type: `CallHierarchyClientCapabilities` defined as follows: + +
+ +```typescript +interface CallHierarchyClientCapabilities { + /** + * Whether implementation supports dynamic registration. If this is set to + * `true` the client supports the new `(TextDocumentRegistrationOptions & + * StaticRegistrationOptions)` return value for the corresponding server + * capability as well. + */ + dynamicRegistration?: boolean; +} +``` + +_Server Capability_: + +* property name (optional): `callHierarchyProvider` +* property type: `boolean | CallHierarchyOptions | CallHierarchyRegistrationOptions` where `CallHierarchyOptions` is defined as follows: + +
+ +```typescript +export interface CallHierarchyOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `CallHierarchyRegistrationOptions` defined as follows: + +
+ +```typescript +export interface CallHierarchyRegistrationOptions extends + TextDocumentRegistrationOptions, CallHierarchyOptions, + StaticRegistrationOptions { +} +``` + +_Request_: + +* method: `textDocument/prepareCallHierarchy` +* params: `CallHierarchyPrepareParams` defined as follows: + +
+ +```typescript +export interface CallHierarchyPrepareParams extends TextDocumentPositionParams, + WorkDoneProgressParams { +} +``` + +_Response_: + +* result: `CallHierarchyItem[] | null` defined as follows: + +
+ +```typescript +export interface CallHierarchyItem { + /** + * The name of this item. + */ + name: string; + + /** + * The kind of this item. + */ + kind: SymbolKind; + + /** + * Tags for this item. + */ + tags?: SymbolTag[]; + + /** + * More detail for this item, e.g. the signature of a function. + */ + detail?: string; + + /** + * The resource identifier of this item. + */ + uri: DocumentUri; + + /** + * The range enclosing this symbol not including leading/trailing whitespace + * but everything else, e.g. comments and code. + */ + range: Range; + + /** + * The range that should be selected and revealed when this symbol is being + * picked, e.g. the name of a function. Must be contained by the + * [`range`](#CallHierarchyItem.range). + */ + selectionRange: Range; + + /** + * A data entry field that is preserved between a call hierarchy prepare and + * incoming calls or outgoing calls requests. + */ + data?: unknown; +} +``` + +* error: code and message set in case an exception happens during the 'textDocument/prepareCallHierarchy' request + +#### Call Hierarchy Incoming Calls (:leftwards_arrow_with_hook:) + +> *Since version 3.16.0* + +The request is sent from the client to the server to resolve incoming calls for a given call hierarchy item. The request doesn't define its own client and server capabilities. It is only issued if a server registers for the [`textDocument/prepareCallHierarchy` request](#textDocument_prepareCallHierarchy). + +_Request_: + +* method: `callHierarchy/incomingCalls` +* params: `CallHierarchyIncomingCallsParams` defined as follows: + +
+ +```typescript +export interface CallHierarchyIncomingCallsParams extends + WorkDoneProgressParams, PartialResultParams { + item: CallHierarchyItem; +} +``` + +_Response_: + +* result: `CallHierarchyIncomingCall[] | null` defined as follows: + +
+ +```typescript +export interface CallHierarchyIncomingCall { + + /** + * The item that makes the call. + */ + from: CallHierarchyItem; + + /** + * The ranges at which the calls appear. This is relative to the caller + * denoted by [`this.from`](#CallHierarchyIncomingCall.from). + */ + fromRanges: Range[]; +} +``` + +* partial result: `CallHierarchyIncomingCall[]` +* error: code and message set in case an exception happens during the 'callHierarchy/incomingCalls' request + +#### Call Hierarchy Outgoing Calls (:leftwards_arrow_with_hook:) + +> *Since version 3.16.0* + +The request is sent from the client to the server to resolve outgoing calls for a given call hierarchy item. The request doesn't define its own client and server capabilities. It is only issued if a server registers for the [`textDocument/prepareCallHierarchy` request](#textDocument_prepareCallHierarchy). + +_Request_: + +* method: `callHierarchy/outgoingCalls` +* params: `CallHierarchyOutgoingCallsParams` defined as follows: + +
+ +```typescript +export interface CallHierarchyOutgoingCallsParams extends + WorkDoneProgressParams, PartialResultParams { + item: CallHierarchyItem; +} +``` + +_Response_: + +* result: `CallHierarchyOutgoingCall[] | null` defined as follows: + +
+ +```typescript +export interface CallHierarchyOutgoingCall { + + /** + * The item that is called. + */ + to: CallHierarchyItem; + + /** + * The range at which this item is called. This is the range relative to + * the caller, e.g the item passed to `callHierarchy/outgoingCalls` request. + */ + fromRanges: Range[]; +} +``` + +* partial result: `CallHierarchyOutgoingCall[]` +* error: code and message set in case an exception happens during the 'callHierarchy/outgoingCalls' request diff --git a/_specifications/lsp/3.17/language/codeAction.md b/_specifications/lsp/3.17/language/codeAction.md new file mode 100644 index 000000000..2d6b50335 --- /dev/null +++ b/_specifications/lsp/3.17/language/codeAction.md @@ -0,0 +1,459 @@ +#### Code Action Request (:leftwards_arrow_with_hook:) + +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. The result of a `textDocument/codeAction` request is an array of `Command` literals which are typically presented in the user interface. To ensure that a server is useful in many clients the commands specified in a code actions should be handled by the server and not by the client (see `workspace/executeCommand` and `ServerCapabilities.executeCommandProvider`). If the client supports providing edits with a code action then that mode should be used. + +*Since version 3.16.0:* a client can offer a server to delay the computation of code action properties during a 'textDocument/codeAction' request: + +This is useful for cases where it is expensive to compute the value of a property (for example the `edit` property). Clients signal this through the `codeAction.resolveSupport` capability which lists all properties a client can resolve lazily. The server capability `codeActionProvider.resolveProvider` signals that a server will offer a `codeAction/resolve` route. To help servers to uniquely identify a code action in the resolve request, a code action literal can optional carry a data property. This is also guarded by an additional client capability `codeAction.dataSupport`. In general, a client should offer data support if it offers resolve support. It should also be noted that servers shouldn't alter existing attributes of a code action in a codeAction/resolve request. + +> *Since version 3.8.0:* support for CodeAction literals to enable the following scenarios: + +- the ability to directly return a workspace edit from the code action request. This avoids having another server roundtrip to execute an actual code action. However server providers should be aware that if the code action is expensive to compute or the edits are huge it might still be beneficial if the result is simply a command and the actual edit is only computed when needed. +- the ability to group code actions using a kind. Clients are allowed to ignore that information. However it allows them to better group code action for example into corresponding menus (e.g. all refactor code actions into a refactor menu). + +Clients need to announce their support for code action literals (e.g. literals of type `CodeAction`) and code action kinds via the corresponding client capability `codeAction.codeActionLiteralSupport`. + +_Client Capability_: +* property name (optional): `textDocument.codeAction` +* property type: `CodeActionClientCapabilities` defined as follows: + +
+ +```typescript +export interface CodeActionClientCapabilities { + /** + * Whether code action supports dynamic registration. + */ + dynamicRegistration?: boolean; + + /** + * The client supports code action literals as a valid + * response of the `textDocument/codeAction` request. + * + * @since 3.8.0 + */ + codeActionLiteralSupport?: { + /** + * The code action kind is supported with the following value + * set. + */ + codeActionKind: { + + /** + * The code action kind values the client supports. When this + * property exists the client also guarantees that it will + * handle values outside its set gracefully and falls back + * to a default value when unknown. + */ + valueSet: CodeActionKind[]; + }; + }; + + /** + * Whether code action supports the `isPreferred` property. + * + * @since 3.15.0 + */ + isPreferredSupport?: boolean; + + /** + * Whether code action supports the `disabled` property. + * + * @since 3.16.0 + */ + disabledSupport?: boolean; + + /** + * Whether code action supports the `data` property which is + * preserved between a `textDocument/codeAction` and a + * `codeAction/resolve` request. + * + * @since 3.16.0 + */ + dataSupport?: boolean; + + + /** + * Whether the client supports resolving additional code action + * properties via a separate `codeAction/resolve` request. + * + * @since 3.16.0 + */ + resolveSupport?: { + /** + * The properties that a client can resolve lazily. + */ + properties: string[]; + }; + + /** + * Whether the client honors the change annotations in + * text edits and resource operations returned via the + * `CodeAction#edit` property by for example presenting + * the workspace edit in the user interface and asking + * for confirmation. + * + * @since 3.16.0 + */ + honorsChangeAnnotations?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `codeActionProvider` +* property type: `boolean | CodeActionOptions` where `CodeActionOptions` is defined as follows: + +
+ +```typescript +export interface CodeActionOptions extends WorkDoneProgressOptions { + /** + * CodeActionKinds that this server may return. + * + * The list of kinds may be generic, such as `CodeActionKind.Refactor`, + * or the server may list out every specific kind they provide. + */ + codeActionKinds?: CodeActionKind[]; + + /** + * The server provides support to resolve additional + * information for a code action. + * + * @since 3.16.0 + */ + resolveProvider?: boolean; +} +``` + +_Registration Options_: `CodeActionRegistrationOptions` defined as follows: + +
+ +```typescript +export interface CodeActionRegistrationOptions extends + TextDocumentRegistrationOptions, CodeActionOptions { +} +``` + +_Request_: +* method: `textDocument/codeAction` +* params: `CodeActionParams` defined as follows: + +
+ +```typescript +/** + * Params for the CodeActionRequest + */ +export interface CodeActionParams extends WorkDoneProgressParams, + PartialResultParams { + /** + * The document in which the command was invoked. + */ + textDocument: TextDocumentIdentifier; + + /** + * The range for which the command was invoked. + */ + range: Range; + + /** + * Context carrying additional information. + */ + context: CodeActionContext; +} +``` + +
+ +```typescript +/** + * The kind of a code action. + * + * Kinds are a hierarchical list of identifiers separated by `.`, + * e.g. `"refactor.extract.function"`. + * + * The set of kinds is open and client needs to announce the kinds it supports + * to the server during initialization. + */ +export type CodeActionKind = string; + +/** + * A set of predefined code action kinds. + */ +export namespace CodeActionKind { + + /** + * Empty kind. + */ + export const Empty: CodeActionKind = ''; + + /** + * Base kind for quickfix actions: 'quickfix'. + */ + export const QuickFix: CodeActionKind = 'quickfix'; + + /** + * Base kind for refactoring actions: 'refactor'. + */ + export const Refactor: CodeActionKind = 'refactor'; + + /** + * Base kind for refactoring extraction actions: 'refactor.extract'. + * + * Example extract actions: + * + * - Extract method + * - Extract function + * - Extract variable + * - Extract interface from class + * - ... + */ + export const RefactorExtract: CodeActionKind = 'refactor.extract'; + + /** + * Base kind for refactoring inline actions: 'refactor.inline'. + * + * Example inline actions: + * + * - Inline function + * - Inline variable + * - Inline constant + * - ... + */ + export const RefactorInline: CodeActionKind = 'refactor.inline'; + + /** + * Base kind for refactoring rewrite actions: 'refactor.rewrite'. + * + * Example rewrite actions: + * + * - Convert JavaScript function to class + * - Add or remove parameter + * - Encapsulate field + * - Make method static + * - Move method to base class + * - ... + */ + export const RefactorRewrite: CodeActionKind = 'refactor.rewrite'; + + /** + * Base kind for source actions: `source`. + * + * Source code actions apply to the entire file. + */ + export const Source: CodeActionKind = 'source'; + + /** + * Base kind for an organize imports source action: + * `source.organizeImports`. + */ + export const SourceOrganizeImports: CodeActionKind = + 'source.organizeImports'; + + /** + * Base kind for a 'fix all' source action: `source.fixAll`. + * + * 'Fix all' actions automatically fix errors that have a clear fix that + * do not require user input. They should not suppress errors or perform + * unsafe fixes such as generating new types or classes. + * + * @since 3.17.0 + */ + export const SourceFixAll: CodeActionKind = 'source.fixAll'; +} +``` + +
+ +```typescript +/** + * Contains additional diagnostic information about the context in which + * a code action is run. + */ +export interface CodeActionContext { + /** + * An array of diagnostics known on the client side overlapping the range + * provided to the `textDocument/codeAction` request. They are provided so + * that the server knows which errors are currently presented to the user + * for the given range. There is no guarantee that these accurately reflect + * the error state of the resource. The primary parameter + * to compute code actions is the provided range. + */ + diagnostics: Diagnostic[]; + + /** + * Requested kind of actions to return. + * + * Actions not of this kind are filtered out by the client before being + * shown. So servers can omit computing them. + */ + only?: CodeActionKind[]; + + /** + * The reason why code actions were requested. + * + * @since 3.17.0 + */ + triggerKind?: CodeActionTriggerKind; +} +``` + +
+ +```typescript +/** + * The reason why code actions were requested. + * + * @since 3.17.0 - proposed state + */ +export namespace CodeActionTriggerKind { + /** + * Code actions were explicitly requested by the user or by an extension. + */ + export const Invoked: 1 = 1; + + /** + * Code actions were requested automatically. + * + * This typically happens when current selection in a file changes, but can + * also be triggered when file content changes. + */ + export const Automatic: 2 = 2; +} + +export type CodeActionTriggerKind = 1 | 2; +``` + +_Response_: +* result: `(Command | CodeAction)[]` \| `null` where `CodeAction` is defined as follows: + +
+ +```typescript +/** + * A code action represents a change that can be performed in code, e.g. to fix + * a problem or to refactor code. + * + * A CodeAction must set either `edit` and/or a `command`. If both are supplied, + * the `edit` is applied first, then the `command` is executed. + */ +export interface CodeAction { + + /** + * A short, human-readable, title for this code action. + */ + title: string; + + /** + * The kind of the code action. + * + * Used to filter code actions. + */ + kind?: CodeActionKind; + + /** + * The diagnostics that this code action resolves. + */ + diagnostics?: Diagnostic[]; + + /** + * Marks this as a preferred action. Preferred actions are used by the + * `auto fix` command and can be targeted by keybindings. + * + * A quick fix should be marked preferred if it properly addresses the + * underlying error. A refactoring should be marked preferred if it is the + * most reasonable choice of actions to take. + * + * @since 3.15.0 + */ + isPreferred?: boolean; + + /** + * Marks that the code action cannot currently be applied. + * + * Clients should follow the following guidelines regarding disabled code + * actions: + * + * - Disabled code actions are not shown in automatic lightbulbs code + * action menus. + * + * - Disabled actions are shown as faded out in the code action menu when + * the user request a more specific type of code action, such as + * refactorings. + * + * - If the user has a keybinding that auto applies a code action and only + * a disabled code actions are returned, the client should show the user + * an error message with `reason` in the editor. + * + * @since 3.16.0 + */ + disabled?: { + + /** + * Human readable description of why the code action is currently + * disabled. + * + * This is displayed in the code actions UI. + */ + reason: string; + }; + + /** + * The workspace edit this code action performs. + */ + edit?: WorkspaceEdit; + + /** + * A command this code action executes. If a code action + * provides an edit and a command, first the edit is + * executed and then the command. + */ + command?: Command; + + /** + * A data entry field that is preserved on a code action between + * a `textDocument/codeAction` and a `codeAction/resolve` request. + * + * @since 3.16.0 + */ + data?: LSPAny; +} +``` +* partial result: `(Command | CodeAction)[]` +* error: code and message set in case an exception happens during the code action request. + +#### Code Action Resolve Request (:leftwards_arrow_with_hook:) + +> *Since version 3.16.0* + +The request is sent from the client to the server to resolve additional information for a given code action. This is usually used to compute +the `edit` property of a code action to avoid its unnecessary computation during the `textDocument/codeAction` request. + +Consider the clients announces the `edit` property as a property that can be resolved lazy using the client capability + +```typescript +textDocument.codeAction.resolveSupport = { properties: ['edit'] }; +``` + +then a code action + +```typescript +{ + "title": "Do Foo" +} +``` + +needs to be resolved using the `codeAction/resolve` request before it can be applied. + +_Client Capability_: +* property name (optional): `textDocument.codeAction.resolveSupport` +* property type: `{ properties: string[]; }` + +_Request_: +* method: `codeAction/resolve` +* params: `CodeAction` + +_Response_: +* result: `CodeAction` +* error: code and message set in case an exception happens during the completion resolve request. diff --git a/_specifications/lsp/3.17/language/codeLens.md b/_specifications/lsp/3.17/language/codeLens.md new file mode 100644 index 000000000..3d8c9d232 --- /dev/null +++ b/_specifications/lsp/3.17/language/codeLens.md @@ -0,0 +1,144 @@ +#### Code Lens Request (:leftwards_arrow_with_hook:) + +The code lens request is sent from the client to the server to compute code lenses for a given text document. + +_Client Capability_: +* property name (optional): `textDocument.codeLens` +* property type: `CodeLensClientCapabilities` defined as follows: + +
+ +```typescript +export interface CodeLensClientCapabilities { + /** + * Whether code lens supports dynamic registration. + */ + dynamicRegistration?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `codeLensProvider` +* property type: `CodeLensOptions` defined as follows: + +
+ +```typescript +export interface CodeLensOptions extends WorkDoneProgressOptions { + /** + * Code lens has a resolve provider as well. + */ + resolveProvider?: boolean; +} +``` + +_Registration Options_: `CodeLensRegistrationOptions` defined as follows: + +
+ +```typescript +export interface CodeLensRegistrationOptions extends + TextDocumentRegistrationOptions, CodeLensOptions { +} +``` + +_Request_: +* method: `textDocument/codeLens` +* params: `CodeLensParams` defined as follows: + +
+ +```typescript +interface CodeLensParams extends WorkDoneProgressParams, PartialResultParams { + /** + * The document to request code lens for. + */ + textDocument: TextDocumentIdentifier; +} +``` + +_Response_: +* result: `CodeLens[]` \| `null` defined as follows: + +
+ +```typescript +/** + * A code lens represents a command that should be shown along with + * source text, like the number of references, a way to run tests, etc. + * + * A code lens is _unresolved_ when no command is associated to it. For + * performance reasons the creation of a code lens and resolving should be done + * in two stages. + */ +interface CodeLens { + /** + * The range in which this code lens is valid. Should only span a single + * line. + */ + range: Range; + + /** + * The command this code lens represents. + */ + command?: Command; + + /** + * A data entry field that is preserved on a code lens item between + * a code lens and a code lens resolve request. + */ + data?: LSPAny; +} +``` +* partial result: `CodeLens[]` +* error: code and message set in case an exception happens during the code lens request. + +#### Code Lens Resolve Request (:leftwards_arrow_with_hook:) + +The code lens resolve request is sent from the client to the server to resolve the command for a given code lens item. + +_Request_: +* method: `codeLens/resolve` +* params: `CodeLens` + +_Response_: +* result: `CodeLens` +* error: code and message set in case an exception happens during the code lens resolve request. + +#### Code Lens Refresh Request (:arrow_right_hook:) + +> *Since version 3.16.0* + +The `workspace/codeLens/refresh` request is sent from the server to the client. Servers can use it to ask clients to refresh the code lenses currently shown in editors. As a result the client should ask the server to recompute the code lenses for these editors. This is useful if a server detects a configuration change which requires a re-calculation of all code lenses. Note that the client still has the freedom to delay the re-calculation of the code lenses if for example an editor is currently not visible. + +_Client Capability_: + +* property name (optional): `workspace.codeLens` +* property type: `CodeLensWorkspaceClientCapabilities` defined as follows: + +
+ +```typescript +export interface CodeLensWorkspaceClientCapabilities { + /** + * Whether the client implementation supports a refresh request sent from the + * server to the client. + * + * Note that this event is global and will force the client to refresh all + * code lenses currently shown. It should be used with absolute care and is + * useful for situation where a server for example detect a project wide + * change that requires such a calculation. + */ + refreshSupport?: boolean; +} +``` + +_Request_: + +* method: `workspace/codeLens/refresh` +* params: none + +_Response_: + +* result: void +* error: code and message set in case an exception happens during the 'workspace/codeLens/refresh' request diff --git a/_specifications/lsp/3.17/language/colorPresentation.md b/_specifications/lsp/3.17/language/colorPresentation.md new file mode 100644 index 000000000..b02ac3503 --- /dev/null +++ b/_specifications/lsp/3.17/language/colorPresentation.md @@ -0,0 +1,67 @@ +#### Color Presentation Request (:leftwards_arrow_with_hook:) + +> *Since version 3.6.0* + +The color presentation request is sent from the client to the server to obtain a list of presentations for a color value at a given location. Clients can use the result to +- modify a color reference. +- show in a color picker and let users pick one of the presentations + +This request has no special capabilities and registration options since it is send as a resolve request for the `textDocument/documentColor` request. + +_Request_: + +* method: `textDocument/colorPresentation` +* params: `ColorPresentationParams` defined as follows + +
+ +```typescript +interface ColorPresentationParams extends WorkDoneProgressParams, + PartialResultParams { + /** + * The text document. + */ + textDocument: TextDocumentIdentifier; + + /** + * The color information to request presentations for. + */ + color: Color; + + /** + * The range where the color would be inserted. Serves as a context. + */ + range: Range; +} +``` + +_Response_: +* result: `ColorPresentation[]` defined as follows: + +
+ +```typescript +interface ColorPresentation { + /** + * The label of this color presentation. It will be shown on the color + * picker header. By default this is also the text that is inserted when + * selecting this color presentation. + */ + label: string; + /** + * An [edit](#TextEdit) which is applied to a document when selecting + * this presentation for the color. When `falsy` the + * [label](#ColorPresentation.label) is used. + */ + textEdit?: TextEdit; + /** + * An optional array of additional [text edits](#TextEdit) that are applied + * when selecting this color presentation. Edits must not overlap with the + * main [edit](#ColorPresentation.textEdit) nor with themselves. + */ + additionalTextEdits?: TextEdit[]; +} +``` + +* partial result: `ColorPresentation[]` +* error: code and message set in case an exception happens during the 'textDocument/colorPresentation' request diff --git a/_specifications/lsp/3.17/language/documentColor.md b/_specifications/lsp/3.17/language/documentColor.md new file mode 100644 index 000000000..eaa00d97c --- /dev/null +++ b/_specifications/lsp/3.17/language/documentColor.md @@ -0,0 +1,114 @@ +#### Document Color Request (:leftwards_arrow_with_hook:) + +> *Since version 3.6.0* + +The document color request is sent from the client to the server to list all color references found in a given text document. Along with the range, a color value in RGB is returned. + +Clients can use the result to decorate color references in an editor. For example: +- Color boxes showing the actual color next to the reference +- Show a color picker when a color reference is edited + +_Client Capability_: +* property name (optional): `textDocument.colorProvider` +* property type: `DocumentColorClientCapabilities` defined as follows: + +
+ +```typescript +export interface DocumentColorClientCapabilities { + /** + * Whether document color supports dynamic registration. + */ + dynamicRegistration?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `colorProvider` +* property type: `boolean | DocumentColorOptions | DocumentColorRegistrationOptions` where `DocumentColorOptions` is defined as follows: + +
+ +```typescript +export interface DocumentColorOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `DocumentColorRegistrationOptions` defined as follows: + +
+ +```typescript +export interface DocumentColorRegistrationOptions extends + TextDocumentRegistrationOptions, StaticRegistrationOptions, + DocumentColorOptions { +} +``` + +_Request_: + +* method: `textDocument/documentColor` +* params: `DocumentColorParams` defined as follows + +
+ +```typescript +interface DocumentColorParams extends WorkDoneProgressParams, + PartialResultParams { + /** + * The text document. + */ + textDocument: TextDocumentIdentifier; +} +``` + +_Response_: +* result: `ColorInformation[]` defined as follows: + +
+ +```typescript +interface ColorInformation { + /** + * The range in the document where this color appears. + */ + range: Range; + + /** + * The actual color value for this color range. + */ + color: Color; +} +``` + +
+ +```typescript +/** + * Represents a color in RGBA space. + */ +interface Color { + + /** + * The red component of this color in the range [0-1]. + */ + readonly red: decimal; + + /** + * The green component of this color in the range [0-1]. + */ + readonly green: decimal; + + /** + * The blue component of this color in the range [0-1]. + */ + readonly blue: decimal; + + /** + * The alpha component of this color in the range [0-1]. + */ + readonly alpha: decimal; +} +``` +* partial result: `ColorInformation[]` +* error: code and message set in case an exception happens during the 'textDocument/documentColor' request diff --git a/_specifications/lsp/3.17/language/documentHighlight.md b/_specifications/lsp/3.17/language/documentHighlight.md new file mode 100644 index 000000000..a27e99f2a --- /dev/null +++ b/_specifications/lsp/3.17/language/documentHighlight.md @@ -0,0 +1,108 @@ +#### Document Highlights Request (:leftwards_arrow_with_hook:) + +The document highlight request is sent from the client to the server to resolve a document highlights for a given text document position. +For programming languages this usually highlights all references to the symbol scoped to this file. However we kept 'textDocument/documentHighlight' +and 'textDocument/references' separate requests since the first one is allowed to be more fuzzy. Symbol matches usually have a `DocumentHighlightKind` +of `Read` or `Write` whereas fuzzy or textual matches use `Text`as the kind. + +_Client Capability_: +* property name (optional): `textDocument.documentHighlight` +* property type: `DocumentHighlightClientCapabilities` defined as follows: + +
+ +```typescript +export interface DocumentHighlightClientCapabilities { + /** + * Whether document highlight supports dynamic registration. + */ + dynamicRegistration?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `documentHighlightProvider` +* property type: `boolean | DocumentHighlightOptions` where `DocumentHighlightOptions` is defined as follows: + +
+ +```typescript +export interface DocumentHighlightOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `DocumentHighlightRegistrationOptions` defined as follows: + +
+ +```typescript +export interface DocumentHighlightRegistrationOptions extends + TextDocumentRegistrationOptions, DocumentHighlightOptions { +} +``` + +_Request_: +* method: `textDocument/documentHighlight` +* params: `DocumentHighlightParams` defined as follows: + +
+ +```typescript +export interface DocumentHighlightParams extends TextDocumentPositionParams, + WorkDoneProgressParams, PartialResultParams { +} +``` + +_Response_: +* result: `DocumentHighlight[]` \| `null` defined as follows: + +
+ +```typescript +/** + * A document highlight is a range inside a text document which deserves + * special attention. Usually a document highlight is visualized by changing + * the background color of its range. + * + */ +export interface DocumentHighlight { + /** + * The range this highlight applies to. + */ + range: Range; + + /** + * The highlight kind, default is DocumentHighlightKind.Text. + */ + kind?: DocumentHighlightKind; +} +``` + +
+ +```typescript +/** + * A document highlight kind. + */ +export namespace DocumentHighlightKind { + /** + * A textual occurrence. + */ + export const Text = 1; + + /** + * Read-access of a symbol, like reading a variable. + */ + export const Read = 2; + + /** + * Write-access of a symbol, like writing to a variable. + */ + export const Write = 3; +} + +export type DocumentHighlightKind = 1 | 2 | 3; +``` + +* partial result: `DocumentHighlight[]` +* error: code and message set in case an exception happens during the document highlight request. diff --git a/_specifications/lsp/3.17/language/documentLink.md b/_specifications/lsp/3.17/language/documentLink.md new file mode 100644 index 000000000..25bd6db4e --- /dev/null +++ b/_specifications/lsp/3.17/language/documentLink.md @@ -0,0 +1,121 @@ +#### Document Link Request (:leftwards_arrow_with_hook:) + +The document links request is sent from the client to the server to request the location of links in a document. + +_Client Capability_: +* property name (optional): `textDocument.documentLink` +* property type: `DocumentLinkClientCapabilities` defined as follows: + +
+ +```typescript +export interface DocumentLinkClientCapabilities { + /** + * Whether document link supports dynamic registration. + */ + dynamicRegistration?: boolean; + + /** + * Whether the client supports the `tooltip` property on `DocumentLink`. + * + * @since 3.15.0 + */ + tooltipSupport?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `documentLinkProvider` +* property type: `DocumentLinkOptions` defined as follows: + +
+ +```typescript +export interface DocumentLinkOptions extends WorkDoneProgressOptions { + /** + * Document links have a resolve provider as well. + */ + resolveProvider?: boolean; +} +``` + +_Registration Options_: `DocumentLinkRegistrationOptions` defined as follows: + +
+ +```typescript +export interface DocumentLinkRegistrationOptions extends + TextDocumentRegistrationOptions, DocumentLinkOptions { +} +``` + +_Request_: +* method: `textDocument/documentLink` +* params: `DocumentLinkParams` defined as follows: + +
+ +```typescript +interface DocumentLinkParams extends WorkDoneProgressParams, + PartialResultParams { + /** + * The document to provide document links for. + */ + textDocument: TextDocumentIdentifier; +} +``` + +_Response_: +* result: `DocumentLink[]` \| `null`. + +
+ +```typescript +/** + * A document link is a range in a text document that links to an internal or + * external resource, like another text document or a web site. + */ +interface DocumentLink { + /** + * The range this link applies to. + */ + range: Range; + + /** + * The uri this link points to. If missing a resolve request is sent later. + */ + target?: DocumentUri; + + /** + * The tooltip text when you hover over this link. + * + * If a tooltip is provided, is will be displayed in a string that includes + * instructions on how to trigger the link, such as `{0} (ctrl + click)`. + * The specific instructions vary depending on OS, user settings, and + * localization. + * + * @since 3.15.0 + */ + tooltip?: string; + + /** + * A data entry field that is preserved on a document link between a + * DocumentLinkRequest and a DocumentLinkResolveRequest. + */ + data?: LSPAny; +} +``` +* partial result: `DocumentLink[]` +* error: code and message set in case an exception happens during the document link request. + +#### Document Link Resolve Request (:leftwards_arrow_with_hook:) + +The document link resolve request is sent from the client to the server to resolve the target of a given document link. + +_Request_: +* method: `documentLink/resolve` +* params: `DocumentLink` + +_Response_: +* result: `DocumentLink` +* error: code and message set in case an exception happens during the document link resolve request. diff --git a/_specifications/lsp/3.17/language/documentSymbol.md b/_specifications/lsp/3.17/language/documentSymbol.md new file mode 100644 index 000000000..4375388e0 --- /dev/null +++ b/_specifications/lsp/3.17/language/documentSymbol.md @@ -0,0 +1,293 @@ +#### Document Symbols Request (:leftwards_arrow_with_hook:) + +The document symbol request is sent from the client to the server. The returned result is either + +- `SymbolInformation[]` which is a flat list of all symbols found in a given text document. Then neither the symbol's location range nor the symbol's container name should be used to infer a hierarchy. +- `DocumentSymbol[]` which is a hierarchy of symbols found in a given text document. + +Servers should whenever possible return `DocumentSymbol` since it is the richer data structure. + +_Client Capability_: +* property name (optional): `textDocument.documentSymbol` +* property type: `DocumentSymbolClientCapabilities` defined as follows: + +
+ +```typescript +export interface DocumentSymbolClientCapabilities { + /** + * Whether document symbol supports dynamic registration. + */ + dynamicRegistration?: boolean; + + /** + * Specific capabilities for the `SymbolKind` in the + * `textDocument/documentSymbol` request. + */ + symbolKind?: { + /** + * The symbol kind values the client supports. When this + * property exists the client also guarantees that it will + * handle values outside its set gracefully and falls back + * to a default value when unknown. + * + * If this property is not present the client only supports + * the symbol kinds from `File` to `Array` as defined in + * the initial version of the protocol. + */ + valueSet?: SymbolKind[]; + }; + + /** + * The client supports hierarchical document symbols. + */ + hierarchicalDocumentSymbolSupport?: boolean; + + /** + * The client supports tags on `SymbolInformation`. Tags are supported on + * `DocumentSymbol` if `hierarchicalDocumentSymbolSupport` is set to true. + * Clients supporting tags have to handle unknown tags gracefully. + * + * @since 3.16.0 + */ + tagSupport?: { + /** + * The tags supported by the client. + */ + valueSet: SymbolTag[]; + }; + + /** + * The client supports an additional label presented in the UI when + * registering a document symbol provider. + * + * @since 3.16.0 + */ + labelSupport?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `documentSymbolProvider` +* property type: `boolean | DocumentSymbolOptions` where `DocumentSymbolOptions` is defined as follows: + +
+ +```typescript +export interface DocumentSymbolOptions extends WorkDoneProgressOptions { + /** + * A human-readable string that is shown when multiple outlines trees + * are shown for the same document. + * + * @since 3.16.0 + */ + label?: string; +} +``` + +_Registration Options_: `DocumentSymbolRegistrationOptions` defined as follows: + +
+ +```typescript +export interface DocumentSymbolRegistrationOptions extends + TextDocumentRegistrationOptions, DocumentSymbolOptions { +} +``` + +_Request_: +* method: `textDocument/documentSymbol` +* params: `DocumentSymbolParams` defined as follows: + +
+ +```typescript +export interface DocumentSymbolParams extends WorkDoneProgressParams, + PartialResultParams { + /** + * The text document. + */ + textDocument: TextDocumentIdentifier; +} +``` + +_Response_: +* result: `DocumentSymbol[]` \| `SymbolInformation[]` \| `null` defined as follows: + +
+ +```typescript +/** + * A symbol kind. + */ +export namespace SymbolKind { + export const File = 1; + export const Module = 2; + export const Namespace = 3; + export const Package = 4; + export const Class = 5; + export const Method = 6; + export const Property = 7; + export const Field = 8; + export const Constructor = 9; + export const Enum = 10; + export const Interface = 11; + export const Function = 12; + export const Variable = 13; + export const Constant = 14; + export const String = 15; + export const Number = 16; + export const Boolean = 17; + export const Array = 18; + export const Object = 19; + export const Key = 20; + export const Null = 21; + export const EnumMember = 22; + export const Struct = 23; + export const Event = 24; + export const Operator = 25; + export const TypeParameter = 26; +} +``` + +
+ +```typescript +/** + * Symbol tags are extra annotations that tweak the rendering of a symbol. + * + * @since 3.16 + */ +export namespace SymbolTag { + + /** + * Render a symbol as obsolete, usually using a strike-out. + */ + export const Deprecated: 1 = 1; +} + +export type SymbolTag = 1; +``` + +
+ +```typescript +/** + * Represents programming constructs like variables, classes, interfaces etc. + * that appear in a document. Document symbols can be hierarchical and they + * have two ranges: one that encloses its definition and one that points to its + * most interesting range, e.g. the range of an identifier. + */ +export interface DocumentSymbol { + + /** + * The name of this symbol. Will be displayed in the user interface and + * therefore must not be an empty string or a string only consisting of + * white spaces. + */ + name: string; + + /** + * More detail for this symbol, e.g the signature of a function. + */ + detail?: string; + + /** + * The kind of this symbol. + */ + kind: SymbolKind; + + /** + * Tags for this document symbol. + * + * @since 3.16.0 + */ + tags?: SymbolTag[]; + + /** + * Indicates if this symbol is deprecated. + * + * @deprecated Use tags instead + */ + deprecated?: boolean; + + /** + * The range enclosing this symbol not including leading/trailing whitespace + * but everything else like comments. This information is typically used to + * determine if the clients cursor is inside the symbol to reveal in the + * symbol in the UI. + */ + range: Range; + + /** + * The range that should be selected and revealed when this symbol is being + * picked, e.g. the name of a function. Must be contained by the `range`. + */ + selectionRange: Range; + + /** + * Children of this symbol, e.g. properties of a class. + */ + children?: DocumentSymbol[]; +} +``` + +
+ +```typescript +/** + * Represents information about programming constructs like variables, classes, + * interfaces etc. + * + * @deprecated use DocumentSymbol or WorkspaceSymbol instead. + */ +export interface SymbolInformation { + /** + * The name of this symbol. + */ + name: string; + + /** + * The kind of this symbol. + */ + kind: SymbolKind; + + /** + * Tags for this symbol. + * + * @since 3.16.0 + */ + tags?: SymbolTag[]; + + /** + * Indicates if this symbol is deprecated. + * + * @deprecated Use tags instead + */ + deprecated?: boolean; + + /** + * The location of this symbol. The location's range is used by a tool + * to reveal the location in the editor. If the symbol is selected in the + * tool the range's start information is used to position the cursor. So + * the range usually spans more then the actual symbol's name and does + * normally include things like visibility modifiers. + * + * The range doesn't have to denote a node range in the sense of a abstract + * syntax tree. It can therefore not be used to re-construct a hierarchy of + * the symbols. + */ + location: Location; + + /** + * The name of the symbol containing this symbol. This information is for + * user interface purposes (e.g. to render a qualifier in the user interface + * if necessary). It can't be used to re-infer a hierarchy for the document + * symbols. + */ + containerName?: string; +} +``` + +* partial result: `DocumentSymbol[]` \| `SymbolInformation[]`. `DocumentSymbol[]` and `SymbolInformation[]` can not be mixed. That means the first chunk defines the type of all the other chunks. +* error: code and message set in case an exception happens during the document symbol request. diff --git a/_specifications/lsp/3.17/language/foldingRange.md b/_specifications/lsp/3.17/language/foldingRange.md new file mode 100644 index 000000000..d58229a26 --- /dev/null +++ b/_specifications/lsp/3.17/language/foldingRange.md @@ -0,0 +1,148 @@ +#### Folding Range Request (:leftwards_arrow_with_hook:) + +> *Since version 3.10.0* + +The folding range request is sent from the client to the server to return all folding ranges found in a given text document. + +_Client Capability_: +* property name (optional): `textDocument.foldingRange` +* property type: `FoldingRangeClientCapabilities` defined as follows: + +
+ +```typescript +export interface FoldingRangeClientCapabilities { + /** + * Whether implementation supports dynamic registration for folding range + * providers. If this is set to `true` the client supports the new + * `FoldingRangeRegistrationOptions` return value for the corresponding + * server capability as well. + */ + dynamicRegistration?: boolean; + /** + * The maximum number of folding ranges that the client prefers to receive + * per document. The value serves as a hint, servers are free to follow the + * limit. + */ + rangeLimit?: uinteger; + /** + * If set, the client signals that it only supports folding complete lines. + * If set, client will ignore specified `startCharacter` and `endCharacter` + * properties in a FoldingRange. + */ + lineFoldingOnly?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `foldingRangeProvider` +* property type: `boolean | FoldingRangeOptions | FoldingRangeRegistrationOptions` where `FoldingRangeOptions` is defined as follows: + +
+ +```typescript +export interface FoldingRangeOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `FoldingRangeRegistrationOptions` defined as follows: + +
+ +```typescript +export interface FoldingRangeRegistrationOptions extends + TextDocumentRegistrationOptions, FoldingRangeOptions, + StaticRegistrationOptions { +} +``` + +_Request_: + +* method: `textDocument/foldingRange` +* params: `FoldingRangeParams` defined as follows + +
+ +```typescript +export interface FoldingRangeParams extends WorkDoneProgressParams, + PartialResultParams { + /** + * The text document. + */ + textDocument: TextDocumentIdentifier; +} +``` + +_Response_: +* result: `FoldingRange[] | null` defined as follows: + +
+ +```typescript +/** + * Enum of known range kinds + */ +export enum FoldingRangeKind { + /** + * Folding range for a comment + */ + Comment = 'comment', + /** + * Folding range for a imports or includes + */ + Imports = 'imports', + /** + * Folding range for a region (e.g. `#region`) + */ + Region = 'region' +} +``` + +
+ +```typescript +/** + * Represents a folding range. To be valid, start and end line must be bigger + * than zero and smaller than the number of lines in the document. Clients + * are free to ignore invalid ranges. + */ +export interface FoldingRange { + + /** + * The zero-based start line of the range to fold. The folded area starts + * after the line's last character. To be valid, the end must be zero or + * larger and smaller than the number of lines in the document. + */ + startLine: uinteger; + + /** + * The zero-based character offset from where the folded range starts. If + * not defined, defaults to the length of the start line. + */ + startCharacter?: uinteger; + + /** + * The zero-based end line of the range to fold. The folded area ends with + * the line's last character. To be valid, the end must be zero or larger + * and smaller than the number of lines in the document. + */ + endLine: uinteger; + + /** + * The zero-based character offset before the folded range ends. If not + * defined, defaults to the length of the end line. + */ + endCharacter?: uinteger; + + /** + * Describes the kind of the folding range such as `comment` or `region`. + * The kind is used to categorize folding ranges and used by commands like + * 'Fold all comments'. See [FoldingRangeKind](#FoldingRangeKind) for an + * enumeration of standardized kinds. + */ + kind?: string; +} +``` + +* partial result: `FoldingRange[]` +* error: code and message set in case an exception happens during the 'textDocument/foldingRange' request diff --git a/_specifications/lsp/3.17/language/formatting.md b/_specifications/lsp/3.17/language/formatting.md new file mode 100644 index 000000000..26ef83018 --- /dev/null +++ b/_specifications/lsp/3.17/language/formatting.md @@ -0,0 +1,108 @@ +#### Document Formatting Request (:leftwards_arrow_with_hook:) + +The document formatting request is sent from the client to the server to format a whole document. + +_Client Capability_: +* property name (optional): `textDocument.formatting` +* property type: `DocumentFormattingClientCapabilities` defined as follows: + +
+ +```typescript +export interface DocumentFormattingClientCapabilities { + /** + * Whether formatting supports dynamic registration. + */ + dynamicRegistration?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `documentFormattingProvider` +* property type: `boolean | DocumentFormattingOptions` where `DocumentFormattingOptions` is defined as follows: + +
+ +```typescript +export interface DocumentFormattingOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `DocumentFormattingRegistrationOptions` defined as follows: + +
+ +```typescript +export interface DocumentFormattingRegistrationOptions extends + TextDocumentRegistrationOptions, DocumentFormattingOptions { +} +``` + +_Request_: +* method: `textDocument/formatting` +* params: `DocumentFormattingParams` defined as follows + +
+ +```typescript +interface DocumentFormattingParams extends WorkDoneProgressParams { + /** + * The document to format. + */ + textDocument: TextDocumentIdentifier; + + /** + * The format options. + */ + options: FormattingOptions; +} +``` + +
+ +```typescript +/** + * Value-object describing what options formatting should use. + */ +interface FormattingOptions { + /** + * Size of a tab in spaces. + */ + tabSize: uinteger; + + /** + * Prefer spaces over tabs. + */ + insertSpaces: boolean; + + /** + * Trim trailing whitespace on a line. + * + * @since 3.15.0 + */ + trimTrailingWhitespace?: boolean; + + /** + * Insert a newline character at the end of the file if one does not exist. + * + * @since 3.15.0 + */ + insertFinalNewline?: boolean; + + /** + * Trim all newlines after the final newline at the end of the file. + * + * @since 3.15.0 + */ + trimFinalNewlines?: boolean; + + /** + * Signature for further properties. + */ + [key: string]: boolean | integer | string; +} +``` + +_Response_: +* result: [`TextEdit[]`](#textEdit) \| `null` describing the modification to the document to be formatted. +* error: code and message set in case an exception happens during the formatting request. diff --git a/_specifications/lsp/3.17/language/implementation.md b/_specifications/lsp/3.17/language/implementation.md new file mode 100644 index 000000000..505e2af7b --- /dev/null +++ b/_specifications/lsp/3.17/language/implementation.md @@ -0,0 +1,70 @@ +#### Goto Implementation Request (:leftwards_arrow_with_hook:) + +> *Since version 3.6.0* + +The go to implementation request is sent from the client to the server to resolve the implementation location of a symbol at a given text document position. + +The result type [`LocationLink`](#locationLink)[] got introduced with version 3.14.0 and depends on the corresponding client capability `textDocument.implementation.linkSupport`. + +_Client Capability_: +* property name (optional): `textDocument.implementation` +* property type: `ImplementationClientCapabilities` defined as follows: + +
+ +```typescript +export interface ImplementationClientCapabilities { + /** + * Whether implementation supports dynamic registration. If this is set to + * `true` the client supports the new `ImplementationRegistrationOptions` + * return value for the corresponding server capability as well. + */ + dynamicRegistration?: boolean; + + /** + * The client supports additional metadata in the form of definition links. + * + * @since 3.14.0 + */ + linkSupport?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `implementationProvider` +* property type: `boolean | ImplementationOptions | ImplementationRegistrationOptions` where `ImplementationOptions` is defined as follows: + +
+ +```typescript +export interface ImplementationOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `ImplementationRegistrationOptions` defined as follows: + +
+ +```typescript +export interface ImplementationRegistrationOptions extends + TextDocumentRegistrationOptions, ImplementationOptions, + StaticRegistrationOptions { +} +``` + +_Request_: +* method: `textDocument/implementation` +* params: `ImplementationParams` defined as follows: + +
+ +```typescript +export interface ImplementationParams extends TextDocumentPositionParams, + WorkDoneProgressParams, PartialResultParams { +} +``` + +_Response_: +* result: [`Location`](#location) \| [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] \| `null` +* partial result: [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] +* error: code and message set in case an exception happens during the definition request. diff --git a/_specifications/lsp/3.17/language/linkedEditingRange.md b/_specifications/lsp/3.17/language/linkedEditingRange.md new file mode 100644 index 000000000..ca68b0bd1 --- /dev/null +++ b/_specifications/lsp/3.17/language/linkedEditingRange.md @@ -0,0 +1,84 @@ +#### Linked Editing Range(:leftwards_arrow_with_hook:) + +> *Since version 3.16.0* + +The linked editing request is sent from the client to the server to return for a given position in a document the range of the symbol at the position and all ranges that have the same content. Optionally a word pattern can be returned to describe valid contents. A rename to one of the ranges can be applied to all other ranges if the new content is valid. If no result-specific word pattern is provided, the word pattern from the client's language configuration is used. + +_Client Capabilities_: + +* property name (optional): `textDocument.linkedEditingRange` +* property type: `LinkedEditingRangeClientCapabilities` defined as follows: + +
+ +```typescript +export interface LinkedEditingRangeClientCapabilities { + /** + * Whether implementation supports dynamic registration. + * If this is set to `true` the client supports the new + * `(TextDocumentRegistrationOptions & StaticRegistrationOptions)` + * return value for the corresponding server capability as well. + */ + dynamicRegistration?: boolean; +} +``` + +_Server Capability_: + +* property name (optional): `linkedEditingRangeProvider` +* property type: `boolean` \| `LinkedEditingRangeOptions` \| `LinkedEditingRangeRegistrationOptions` defined as follows: + +
+ +```typescript +export interface LinkedEditingRangeOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `LinkedEditingRangeRegistrationOptions` defined as follows: + +
+ +```typescript +export interface LinkedEditingRangeRegistrationOptions extends + TextDocumentRegistrationOptions, LinkedEditingRangeOptions, + StaticRegistrationOptions { +} +``` + +_Request_: + +* method: `textDocument/linkedEditingRange` +* params: `LinkedEditingRangeParams` defined as follows: + +
+ +```typescript +export interface LinkedEditingRangeParams extends TextDocumentPositionParams, + WorkDoneProgressParams { +} +``` + +_Response_: + +* result: `LinkedEditingRanges` \| `null` defined as follows: + +
+ +```typescript +export interface LinkedEditingRanges { + /** + * A list of ranges that can be renamed together. The ranges must have + * identical length and contain identical text content. The ranges cannot overlap. + */ + ranges: Range[]; + + /** + * An optional word pattern (regular expression) that describes valid contents for + * the given ranges. If no pattern is provided, the client configuration's word + * pattern will be used. + */ + wordPattern?: string; +} +``` +* error: code and message set in case an exception happens during the 'textDocument/linkedEditingRange' request diff --git a/_specifications/lsp/3.17/language/moniker.md b/_specifications/lsp/3.17/language/moniker.md new file mode 100644 index 000000000..ff8af24ff --- /dev/null +++ b/_specifications/lsp/3.17/language/moniker.md @@ -0,0 +1,162 @@ +#### Monikers (:leftwards_arrow_with_hook:) + +> *Since version 3.16.0* + +Language Server Index Format (LSIF) introduced the concept of symbol monikers to help associate symbols across different indexes. This request adds capability for LSP server implementations to provide the same symbol moniker information given a text document position. Clients can utilize this method to get the moniker at the current location in a file user is editing and do further code navigation queries in other services that rely on LSIF indexes and link symbols together. + +The `textDocument/moniker` request is sent from the client to the server to get the symbol monikers for a given text document position. An array of Moniker types is returned as response to indicate possible monikers at the given location. If no monikers can be calculated, an empty array or `null` should be returned. + +_Client Capabilities_: + +* property name (optional): `textDocument.moniker` +* property type: `MonikerClientCapabilities` defined as follows: + +
+ +```typescript +interface MonikerClientCapabilities { + /** + * Whether implementation supports dynamic registration. If this is set to + * `true` the client supports the new `(TextDocumentRegistrationOptions & + * StaticRegistrationOptions)` return value for the corresponding server + * capability as well. + */ + dynamicRegistration?: boolean; +} +``` + +_Server Capability_: + +* property name (optional): `monikerProvider` +* property type: `boolean | MonikerOptions | MonikerRegistrationOptions` is defined as follows: + +
+ +```typescript +export interface MonikerOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `MonikerRegistrationOptions` defined as follows: + +
+ +```typescript +export interface MonikerRegistrationOptions extends + TextDocumentRegistrationOptions, MonikerOptions { +} +``` + +_Request_: + +* method: `textDocument/moniker` +* params: `MonikerParams` defined as follows: + +
+ +```typescript +export interface MonikerParams extends TextDocumentPositionParams, + WorkDoneProgressParams, PartialResultParams { +} +``` + +_Response_: + +* result: `Moniker[] | null` +* partial result: `Moniker[]` +* error: code and message set in case an exception happens during the 'textDocument/moniker' request + +`Moniker` is defined as follows: + +
+ +```typescript +/** + * Moniker uniqueness level to define scope of the moniker. + */ +export enum UniquenessLevel { + /** + * The moniker is only unique inside a document + */ + document = 'document', + + /** + * The moniker is unique inside a project for which a dump got created + */ + project = 'project', + + /** + * The moniker is unique inside the group to which a project belongs + */ + group = 'group', + + /** + * The moniker is unique inside the moniker scheme. + */ + scheme = 'scheme', + + /** + * The moniker is globally unique + */ + global = 'global' +} +``` + +
+ +```typescript +/** + * The moniker kind. + */ +export enum MonikerKind { + /** + * The moniker represent a symbol that is imported into a project + */ + import = 'import', + + /** + * The moniker represents a symbol that is exported from a project + */ + export = 'export', + + /** + * The moniker represents a symbol that is local to a project (e.g. a local + * variable of a function, a class not visible outside the project, ...) + */ + local = 'local' +} +``` + +
+ +```typescript +/** + * Moniker definition to match LSIF 0.5 moniker definition. + */ +export interface Moniker { + /** + * The scheme of the moniker. For example tsc or .Net + */ + scheme: string; + + /** + * The identifier of the moniker. The value is opaque in LSIF however + * schema owners are allowed to define the structure if they want. + */ + identifier: string; + + /** + * The scope in which the moniker is unique + */ + unique: UniquenessLevel; + + /** + * The moniker kind if known. + */ + kind?: MonikerKind; +} +``` + +##### Notes + +Server implementations of this method should ensure that the moniker calculation matches to those used in the corresponding LSIF implementation to ensure symbols can be associated correctly across IDE sessions and LSIF indexes. \ No newline at end of file diff --git a/_specifications/lsp/3.17/language/onTypeFormatting.md b/_specifications/lsp/3.17/language/onTypeFormatting.md new file mode 100644 index 000000000..8af04d323 --- /dev/null +++ b/_specifications/lsp/3.17/language/onTypeFormatting.md @@ -0,0 +1,72 @@ +#### Document on Type Formatting Request (:leftwards_arrow_with_hook:) + +The document on type formatting request is sent from the client to the server to format parts of the document during typing. + +_Client Capability_: +* property name (optional): `textDocument.onTypeFormatting` +* property type: `DocumentOnTypeFormattingClientCapabilities` defined as follows: + +
+ +```typescript +export interface DocumentOnTypeFormattingClientCapabilities { + /** + * Whether on type formatting supports dynamic registration. + */ + dynamicRegistration?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `documentOnTypeFormattingProvider` +* property type: `DocumentOnTypeFormattingOptions` defined as follows: + +
+ +```typescript +export interface DocumentOnTypeFormattingOptions { + /** + * A character on which formatting should be triggered, like `}`. + */ + firstTriggerCharacter: string; + + /** + * More trigger characters. + */ + moreTriggerCharacter?: string[]; +} +``` + +_Registration Options_: `DocumentOnTypeFormattingRegistrationOptions` defined as follows: + +
+ +```typescript +export interface DocumentOnTypeFormattingRegistrationOptions extends + TextDocumentRegistrationOptions, DocumentOnTypeFormattingOptions { +} +``` + +_Request_: +* method: `textDocument/onTypeFormatting` +* params: `DocumentOnTypeFormattingParams` defined as follows: + +
+ +```typescript +interface DocumentOnTypeFormattingParams extends TextDocumentPositionParams { + /** + * The character that has been typed. + */ + ch: string; + + /** + * The format options. + */ + options: FormattingOptions; +} +``` + +_Response_: +* result: [`TextEdit[]`](#textEdit) \| `null` describing the modification to the document. +* error: code and message set in case an exception happens during the range formatting request. diff --git a/_specifications/lsp/3.17/language/rangeFormatting.md b/_specifications/lsp/3.17/language/rangeFormatting.md new file mode 100644 index 000000000..957f73419 --- /dev/null +++ b/_specifications/lsp/3.17/language/rangeFormatting.md @@ -0,0 +1,69 @@ +#### Document Range Formatting Request (:leftwards_arrow_with_hook:) + +The document range formatting request is sent from the client to the server to format a given range in a document. + +_Client Capability_: +* property name (optional): `textDocument.rangeFormatting` +* property type: `DocumentRangeFormattingClientCapabilities` defined as follows: + +
+ +```typescript +export interface DocumentRangeFormattingClientCapabilities { + /** + * Whether formatting supports dynamic registration. + */ + dynamicRegistration?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `documentRangeFormattingProvider` +* property type: `boolean | DocumentRangeFormattingOptions` where `DocumentRangeFormattingOptions` is defined as follows: + +
+ +```typescript +export interface DocumentRangeFormattingOptions extends + WorkDoneProgressOptions { +} +``` + +_Registration Options_: `DocumentFormattingRegistrationOptions` defined as follows: + +
+ +```typescript +export interface DocumentRangeFormattingRegistrationOptions extends + TextDocumentRegistrationOptions, DocumentRangeFormattingOptions { +} +``` + +_Request_: +* method: `textDocument/rangeFormatting`, +* params: `DocumentRangeFormattingParams` defined as follows: + +
+ +```typescript +interface DocumentRangeFormattingParams extends WorkDoneProgressParams { + /** + * The document to format. + */ + textDocument: TextDocumentIdentifier; + + /** + * The range to format + */ + range: Range; + + /** + * The format options + */ + options: FormattingOptions; +} +``` + +_Response_: +* result: [`TextEdit[]`](#textEdit) \| `null` describing the modification to the document to be formatted. +* error: code and message set in case an exception happens during the range formatting request. diff --git a/_specifications/lsp/3.17/language/references.md b/_specifications/lsp/3.17/language/references.md new file mode 100644 index 000000000..e7d2e0303 --- /dev/null +++ b/_specifications/lsp/3.17/language/references.md @@ -0,0 +1,67 @@ +#### Find References Request (:leftwards_arrow_with_hook:) + +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. + +_Client Capability_: +* property name (optional): `textDocument.references` +* property type: `ReferenceClientCapabilities` defined as follows: + +
+ +```typescript +export interface ReferenceClientCapabilities { + /** + * Whether references supports dynamic registration. + */ + dynamicRegistration?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `referencesProvider` +* property type: `boolean | ReferenceOptions` where `ReferenceOptions` is defined as follows: + +
+ +```typescript +export interface ReferenceOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `ReferenceRegistrationOptions` defined as follows: + +
+ +```typescript +export interface ReferenceRegistrationOptions extends + TextDocumentRegistrationOptions, ReferenceOptions { +} +``` + +_Request_: +* method: `textDocument/references` +* params: `ReferenceParams` defined as follows: + +
+ +```typescript +export interface ReferenceParams extends TextDocumentPositionParams, + WorkDoneProgressParams, PartialResultParams { + context: ReferenceContext; +} +``` + +
+ +```typescript +export interface ReferenceContext { + /** + * Include the declaration of the current symbol. + */ + includeDeclaration: boolean; +} +``` +_Response_: +* result: [`Location`](#location)[] \| `null` +* partial result: [`Location`](#location)[] +* error: code and message set in case an exception happens during the reference request. diff --git a/_specifications/lsp/3.17/language/rename.md b/_specifications/lsp/3.17/language/rename.md new file mode 100644 index 000000000..ec39eace3 --- /dev/null +++ b/_specifications/lsp/3.17/language/rename.md @@ -0,0 +1,130 @@ +#### Rename Request (:leftwards_arrow_with_hook:) + +The rename request is sent from the client to the server to ask the server to compute a workspace change so that the client can perform a workspace-wide rename of a symbol. + +_Client Capability_: +* property name (optional): `textDocument.rename` +* property type: `RenameClientCapabilities` defined as follows: + +
+ +```typescript +export namespace PrepareSupportDefaultBehavior { + /** + * The client's default behavior is to select the identifier + * according the to language's syntax rule. + */ + export const Identifier: 1 = 1; +} +``` + +
+ +```typescript +export interface RenameClientCapabilities { + /** + * Whether rename supports dynamic registration. + */ + dynamicRegistration?: boolean; + + /** + * Client supports testing for validity of rename operations + * before execution. + * + * @since version 3.12.0 + */ + prepareSupport?: boolean; + + /** + * Client supports the default behavior result + * (`{ defaultBehavior: boolean }`). + * + * The value indicates the default behavior used by the + * client. + * + * @since version 3.16.0 + */ + prepareSupportDefaultBehavior?: PrepareSupportDefaultBehavior; + + /** + * Whether th client honors the change annotations in + * text edits and resource operations returned via the + * rename request's workspace edit by for example presenting + * the workspace edit in the user interface and asking + * for confirmation. + * + * @since 3.16.0 + */ + honorsChangeAnnotations?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `renameProvider` +* property type: `boolean | RenameOptions` where `RenameOptions` is defined as follows: + +`RenameOptions` may only be specified if the client states that it supports `prepareSupport` in its initial `initialize` request. + +
+ +```typescript +export interface RenameOptions extends WorkDoneProgressOptions { + /** + * Renames should be checked and tested before being executed. + */ + prepareProvider?: boolean; +} +``` + +_Registration Options_: `RenameRegistrationOptions` defined as follows: + +
+ +```typescript +export interface RenameRegistrationOptions extends + TextDocumentRegistrationOptions, RenameOptions { +} +``` + +_Request_: +* method: `textDocument/rename` +* params: `RenameParams` defined as follows + +
+ +```typescript +interface RenameParams extends TextDocumentPositionParams, + WorkDoneProgressParams { + /** + * The new name of the symbol. If the given name is not valid the + * request must return a [ResponseError](#ResponseError) with an + * appropriate message set. + */ + newName: string; +} +``` + +_Response_: +* result: [`WorkspaceEdit`](#workspaceedit) \| `null` describing the modification to the workspace. `null` should be treated the same was as [`WorkspaceEdit`](#workspaceedit) with no changes (no change was required). +* error: code and message set in case when rename could not be performed for any reason. Examples include: there is nothing at given `position` to rename (like a space), given symbol does not support renaming by the server or the code is invalid (e.g. does not compile). + +#### Prepare Rename Request (:leftwards_arrow_with_hook:) + +> *Since version 3.12.0* + +The prepare rename request is sent from the client to the server to setup and test the validity of a rename operation at a given location. + +_Request_: +* method: `textDocument/prepareRename` +* params: `PrepareRenameParams` defined as follows: + +
+ +```typescript +export interface PrepareRenameParams extends TextDocumentPositionParams { +} +``` + +_Response_: +* result: `Range | { range: Range, placeholder: string } | { defaultBehavior: boolean } | null` describing a [`Range`](#range) of the string to rename and optionally a placeholder text of the string content to be renamed. If `{ defaultBehavior: boolean }` is returned (since 3.16) the rename position is valid and the client should use its default behavior to compute the rename range. If `null` is returned then it is deemed that a 'textDocument/rename' request is not valid at the given position. +* error: code and message set in case the element can't be renamed. Clients should show the information in their user interface. diff --git a/_specifications/lsp/3.17/language/selectionRange.md b/_specifications/lsp/3.17/language/selectionRange.md new file mode 100644 index 000000000..c85db1695 --- /dev/null +++ b/_specifications/lsp/3.17/language/selectionRange.md @@ -0,0 +1,94 @@ +#### Selection Range Request (:leftwards_arrow_with_hook:) + +> *Since version 3.15.0* + +The selection range request is sent from the client to the server to return suggested selection ranges at an array of given positions. A selection range is a range around the cursor position which the user might be interested in selecting. + +A selection range in the return array is for the position in the provided parameters at the same index. Therefore positions[i] must be contained in result[i].range. To allow for results where some positions have selection ranges and others do not, result[i].range is allowed to be the empty range at positions[i]. + +Typically, but not necessary, selection ranges correspond to the nodes of the syntax tree. + +_Client Capability_: +* property name (optional): `textDocument.selectionRange` +* property type: `SelectionRangeClientCapabilities` defined as follows: + +
+ +```typescript +export interface SelectionRangeClientCapabilities { + /** + * Whether implementation supports dynamic registration for selection range + * providers. If this is set to `true` the client supports the new + * `SelectionRangeRegistrationOptions` return value for the corresponding + * server capability as well. + */ + dynamicRegistration?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `selectionRangeProvider` +* property type: `boolean | SelectionRangeOptions | SelectionRangeRegistrationOptions` where `SelectionRangeOptions` is defined as follows: + +
+ +```typescript +export interface SelectionRangeOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `SelectionRangeRegistrationOptions` defined as follows: + +
+ +```typescript +export interface SelectionRangeRegistrationOptions extends + SelectionRangeOptions, TextDocumentRegistrationOptions, + StaticRegistrationOptions { +} +``` + +_Request_: + +* method: `textDocument/selectionRange` +* params: `SelectionRangeParams` defined as follows: + +
+ +```typescript +export interface SelectionRangeParams extends WorkDoneProgressParams, + PartialResultParams { + /** + * The text document. + */ + textDocument: TextDocumentIdentifier; + + /** + * The positions inside the text document. + */ + positions: Position[]; +} +``` + +_Response_: + +* result: `SelectionRange[] | null` defined as follows: + +
+ +```typescript +export interface SelectionRange { + /** + * The [range](#Range) of this selection range. + */ + range: Range; + /** + * The parent selection range containing this range. Therefore + * `parent.range` must contain `this.range`. + */ + parent?: SelectionRange; +} +``` + +* partial result: `SelectionRange[]` +* error: code and message set in case an exception happens during the 'textDocument/selectionRange' request diff --git a/_specifications/lsp/3.17/language/semanticTokens.md b/_specifications/lsp/3.17/language/semanticTokens.md new file mode 100644 index 000000000..26f2cdbf5 --- /dev/null +++ b/_specifications/lsp/3.17/language/semanticTokens.md @@ -0,0 +1,526 @@ +#### Semantic Tokens (:leftwards_arrow_with_hook:) + +> *Since version 3.16.0* + +The request is sent from the client to the server to resolve semantic tokens for a given file. Semantic tokens are used to add additional color information to a file that depends on language specific symbol information. A semantic token request usually produces a large result. The protocol therefore supports encoding tokens with numbers. In addition optional support for deltas is available. + +_General Concepts_ + +Tokens are represented using one token type combined with n token modifiers. A token type is something like `class` or `function` and token modifiers are like `static` or `async`. The protocol defines a set of token types and modifiers but clients are allowed to extend these and announce the values they support in the corresponding client capability. The predefined values are: + +
+ +```typescript +export enum SemanticTokenTypes { + namespace = 'namespace', + /** + * Represents a generic type. Acts as a fallback for types which + * can't be mapped to a specific type like class or enum. + */ + type = 'type', + class = 'class', + enum = 'enum', + interface = 'interface', + struct = 'struct', + typeParameter = 'typeParameter', + parameter = 'parameter', + variable = 'variable', + property = 'property', + enumMember = 'enumMember', + event = 'event', + function = 'function', + method = 'method', + macro = 'macro', + keyword = 'keyword', + modifier = 'modifier', + comment = 'comment', + string = 'string', + number = 'number', + regexp = 'regexp', + operator = 'operator' +} +``` + +
+ +```typescript +export enum SemanticTokenModifiers { + declaration = 'declaration', + definition = 'definition', + readonly = 'readonly', + static = 'static', + deprecated = 'deprecated', + abstract = 'abstract', + async = 'async', + modification = 'modification', + documentation = 'documentation', + defaultLibrary = 'defaultLibrary' +} +``` + +The protocol defines an additional token format capability to allow future extensions of the format. The only format that is currently specified is `relative` expressing that the tokens are described using relative positions (see Integer Encoding for Tokens below). + +
+ +```typescript +export namespace TokenFormat { + export const Relative: 'relative' = 'relative'; +} + +export type TokenFormat = 'relative'; +``` + +_Integer Encoding for Tokens_ + +On the capability level types and modifiers are defined using strings. However the real encoding happens using numbers. The server therefore needs to let the client know which numbers it is using for which types and modifiers. They do so using a legend, which is defined as follows: + +
+ +```typescript +export interface SemanticTokensLegend { + /** + * The token types a server uses. + */ + tokenTypes: string[]; + + /** + * The token modifiers a server uses. + */ + tokenModifiers: string[]; +} +``` + +Token types are looked up by index, so a `tokenType` value of `1` means `tokenTypes[1]`. Since a token type can have n modifiers, multiple token modifiers can be set by using bit flags, +so a `tokenModifier` value of `3` is first viewed as binary `0b00000011`, which means `[tokenModifiers[0], tokenModifiers[1]]` because bits 0 and 1 are set. + +There are different ways how the position of a token can be expressed in a file. Absolute positions or relative positions. The protocol for the token format `relative` uses relative positions, because most tokens remain stable relative to each other when edits are made in a file. This simplifies the computation of a delta if a server supports it. So each token is represented using 5 integers. A specific token `i` in the file consists of the following array indices: + +- at index `5*i` - `deltaLine`: token line number, relative to the previous token +- at index `5*i+1` - `deltaStart`: token start character, relative to the previous token (relative to 0 or the previous token's start if they are on the same line) +- at index `5*i+2` - `length`: the length of the token. +- at index `5*i+3` - `tokenType`: will be looked up in `SemanticTokensLegend.tokenTypes`. We currently ask that `tokenType` < 65536. +- at index `5*i+4` - `tokenModifiers`: each set bit will be looked up in `SemanticTokensLegend.tokenModifiers` + +Whether a token can span multiple lines is defined by the client capability `multilineTokenSupport`. If multiline tokens are not supported and a tokens length takes it past the end of the line, it should be treated as if the token ends at the end of the line and will not wrap onto the next line. + +The client capability `overlappingTokenSupport` defines whether tokens can overlap each other. + +Lets look at a concrete example which uses single line tokens without overlaps for encoding a file with 3 tokens in a number array. We start with absolute positions to demonstrate how they can easily be transformed into relative positions: + +```typescript +{ line: 2, startChar: 5, length: 3, tokenType: "property", + tokenModifiers: ["private", "static"] +}, +{ line: 2, startChar: 10, length: 4, tokenType: "type", tokenModifiers: [] }, +{ line: 5, startChar: 2, length: 7, tokenType: "class", tokenModifiers: [] } +``` + +First of all, a legend must be devised. This legend must be provided up-front on registration and capture all possible token types and modifiers. For the example we use this legend: + +```typescript +{ + tokenTypes: ['property', 'type', 'class'], + tokenModifiers: ['private', 'static'] +} +``` + +The first transformation step is to encode `tokenType` and `tokenModifiers` as integers using the legend. As said, token types are looked up by index, so a `tokenType` value of `1` means `tokenTypes[1]`. Multiple token modifiers can be set by using bit flags, so a `tokenModifier` value of `3` is first viewed as binary `0b00000011`, which means `[tokenModifiers[0], tokenModifiers[1]]` because bits 0 and 1 are set. Using this legend, the tokens now are: + +```typescript +{ line: 2, startChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 }, +{ line: 2, startChar: 10, length: 4, tokenType: 1, tokenModifiers: 0 }, +{ line: 5, startChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 } +``` + +The next step is to represent each token relative to the previous token in the file. In this case, the second token is on the same line as the first token, so the `startChar` of the second token is made relative to the `startChar` of the first token, so it will be `10 - 5`. The third token is on a different line than the second token, so the `startChar` of the third token will not be altered: + +```typescript +{ deltaLine: 2, deltaStartChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 }, +{ deltaLine: 0, deltaStartChar: 5, length: 4, tokenType: 1, tokenModifiers: 0 }, +{ deltaLine: 3, deltaStartChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 } +``` + +Finally, the last step is to inline each of the 5 fields for a token in a single array, which is a memory friendly representation: + +```typescript +// 1st token, 2nd token, 3rd token +[ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] +``` + +Now assume that the user types a new empty line at the beginning of the file which results in the following tokens in the file: + +```typescript +{ line: 3, startChar: 5, length: 3, tokenType: "property", + tokenModifiers: ["private", "static"] +}, +{ line: 3, startChar: 10, length: 4, tokenType: "type", tokenModifiers: [] }, +{ line: 6, startChar: 2, length: 7, tokenType: "class", tokenModifiers: [] } +``` + +Running the same transformations as above will result in the following number array: + +```typescript +// 1st token, 2nd token, 3rd token +[ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0] +``` + +The delta is now expressed on these number arrays without any form of interpretation what these numbers mean. This is comparable to the text document edits send from the server to the client to modify the content of a file. Those are character based and don't make any assumption about the meaning of the characters. So `[ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ]` can be transformed into `[ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0]` using the following edit description: `{ start: 0, deleteCount: 1, data: [3] }` which tells the client to simply replace the first number (e.g. `2`) in the array with `3`. + +Semantic token edits behave conceptually like [text edits](#textEditArray) on documents: if an edit description consists of n edits all n edits are based on the same state Sm of the number array. They will move the number array from state Sm to Sm+1. A client applying the edits must not assume that they are sorted. An easy algorithm to apply them to the number array is to sort the edits and apply them from the back to the front of the number array. + +_Client Capability_: + +The following client capabilities are defined for semantic token requests sent from the client to the server: + +* property name (optional): `textDocument.semanticTokens` +* property type: `SemanticTokensClientCapabilities` defined as follows: + +
+ +```typescript +interface SemanticTokensClientCapabilities { + /** + * Whether implementation supports dynamic registration. If this is set to + * `true` the client supports the new `(TextDocumentRegistrationOptions & + * StaticRegistrationOptions)` return value for the corresponding server + * capability as well. + */ + dynamicRegistration?: boolean; + + /** + * Which requests the client supports and might send to the server + * depending on the server's capability. Please note that clients might not + * show semantic tokens or degrade some of the user experience if a range + * or full request is advertised by the client but not provided by the + * server. If for example the client capability `requests.full` and + * `request.range` are both set to true but the server only provides a + * range provider the client might not render a minimap correctly or might + * even decide to not show any semantic tokens at all. + */ + requests: { + /** + * The client will send the `textDocument/semanticTokens/range` request + * if the server provides a corresponding handler. + */ + range?: boolean | { + }; + + /** + * The client will send the `textDocument/semanticTokens/full` request + * if the server provides a corresponding handler. + */ + full?: boolean | { + /** + * The client will send the `textDocument/semanticTokens/full/delta` + * request if the server provides a corresponding handler. + */ + delta?: boolean; + }; + }; + + /** + * The token types that the client supports. + */ + tokenTypes: string[]; + + /** + * The token modifiers that the client supports. + */ + tokenModifiers: string[]; + + /** + * The formats the clients supports. + */ + formats: TokenFormat[]; + + /** + * Whether the client supports tokens that can overlap each other. + */ + overlappingTokenSupport?: boolean; + + /** + * Whether the client supports tokens that can span multiple lines. + */ + multilineTokenSupport?: boolean; + + /** + * Whether the client allows the server to actively cancel a + * semantic token request, e.g. supports returning + * ErrorCodes.ServerCancelled. If a server does the client + * needs to retrigger the request. + * + * @since 3.17.0 + */ + serverCancelSupport?: boolean; + + /** + * Whether the client uses semantic tokens to augment existing + * syntax tokens. If set to `true` client side created syntax + * tokens and semantic tokens are both used for colorization. If + * set to `false` the client only uses the returned semantic tokens + * for colorization. + * + * If the value is `undefined` then the client behavior is not + * specified. + * + * @since 3.17.0 + */ + augmentsSyntaxTokens?: boolean; +} +``` + +_Server Capability_: + +The following server capabilities are defined for semantic tokens: + +* property name (optional): `semanticTokensProvider` +* property type: `SemanticTokensOptions | SemanticTokensRegistrationOptions` where `SemanticTokensOptions` is defined as follows: + +
+ +```typescript +export interface SemanticTokensOptions extends WorkDoneProgressOptions { + /** + * The legend used by the server + */ + legend: SemanticTokensLegend; + + /** + * Server supports providing semantic tokens for a specific range + * of a document. + */ + range?: boolean | { + }; + + /** + * Server supports providing semantic tokens for a full document. + */ + full?: boolean | { + /** + * The server supports deltas for full documents. + */ + delta?: boolean; + }; +} +``` + +_Registration Options_: `SemanticTokensRegistrationOptions` defined as follows: + +
+ +```typescript +export interface SemanticTokensRegistrationOptions extends + TextDocumentRegistrationOptions, SemanticTokensOptions, + StaticRegistrationOptions { +} +``` + +Since the registration option handles range, full and delta requests the method used to register for semantic tokens requests is `textDocument/semanticTokens` and not one of the specific methods described below. + +**Requesting semantic tokens for a whole file** + +_Request_: + +
+ +* method: `textDocument/semanticTokens/full` +* params: `SemanticTokensParams` defined as follows: + +
+ +```typescript +export interface SemanticTokensParams extends WorkDoneProgressParams, + PartialResultParams { + /** + * The text document. + */ + textDocument: TextDocumentIdentifier; +} +``` + +_Response_: + +* result: `SemanticTokens | null` where `SemanticTokens` is defined as follows: + +
+ +```typescript +export interface SemanticTokens { + /** + * An optional result id. If provided and clients support delta updating + * the client will include the result id in the next semantic token request. + * A server can then instead of computing all semantic tokens again simply + * send a delta. + */ + resultId?: string; + + /** + * The actual tokens. + */ + data: uinteger[]; +} +``` + +* partial result: `SemanticTokensPartialResult` defines as follows: + +
+ +```typescript +export interface SemanticTokensPartialResult { + data: uinteger[]; +} +``` + +* error: code and message set in case an exception happens during the 'textDocument/semanticTokens/full' request + +**Requesting semantic token delta for a whole file** + +_Request_: + +
+ +* method: `textDocument/semanticTokens/full/delta` +* params: `SemanticTokensDeltaParams` defined as follows: + +
+ +```typescript +export interface SemanticTokensDeltaParams extends WorkDoneProgressParams, + PartialResultParams { + /** + * The text document. + */ + textDocument: TextDocumentIdentifier; + + /** + * The result id of a previous response. The result Id can either point to + * a full response or a delta response depending on what was received last. + */ + previousResultId: string; +} +``` + +_Response_: + +* result: `SemanticTokens | SemanticTokensDelta | null` where `SemanticTokensDelta` is defined as follows: + +
+ +```typescript +export interface SemanticTokensDelta { + readonly resultId?: string; + /** + * The semantic token edits to transform a previous result into a new + * result. + */ + edits: SemanticTokensEdit[]; +} +``` + +
+ +```typescript +export interface SemanticTokensEdit { + /** + * The start offset of the edit. + */ + start: uinteger; + + /** + * The count of elements to remove. + */ + deleteCount: uinteger; + + /** + * The elements to insert. + */ + data?: uinteger[]; +} +``` + +* partial result: `SemanticTokensDeltaPartialResult` defines as follows: + +
+ +```typescript +export interface SemanticTokensDeltaPartialResult { + edits: SemanticTokensEdit[]; +} +``` + +* error: code and message set in case an exception happens during the 'textDocument/semanticTokens/full/delta' request + +**Requesting semantic tokens for a range** + +There are two uses cases where it can be beneficial to only compute semantic tokens for a visible range: + +- for faster rendering of the tokens in the user interface when a user opens a file. In this use cases servers should also implement the `textDocument/semanticTokens/full` request as well to allow for flicker free scrolling and semantic coloring of a minimap. +- if computing semantic tokens for a full document is too expensive servers can only provide a range call. In this case the client might not render a minimap correctly or might even decide to not show any semantic tokens at all. + +_Request_: + +
+ +* method: `textDocument/semanticTokens/range` +* params: `SemanticTokensRangeParams` defined as follows: + +
+ +```typescript +export interface SemanticTokensRangeParams extends WorkDoneProgressParams, + PartialResultParams { + /** + * The text document. + */ + textDocument: TextDocumentIdentifier; + + /** + * The range the semantic tokens are requested for. + */ + range: Range; +} +``` + +_Response_: + +* result: `SemanticTokens | null` +* partial result: `SemanticTokensPartialResult` +* error: code and message set in case an exception happens during the 'textDocument/semanticTokens/range' request + +**Requesting a refresh of all semantic tokens** + +The `workspace/semanticTokens/refresh` request is sent from the server to the client. Servers can use it to ask clients to refresh the editors for which this server provides semantic tokens. As a result the client should ask the server to recompute the semantic tokens for these editors. This is useful if a server detects a project wide configuration change which requires a re-calculation of all semantic tokens. Note that the client still has the freedom to delay the re-calculation of the semantic tokens if for example an editor is currently not visible. + +_Client Capability_: + +* property name (optional): `workspace.semanticTokens` +* property type: `SemanticTokensWorkspaceClientCapabilities` defined as follows: + +
+ +```typescript +export interface SemanticTokensWorkspaceClientCapabilities { + /** + * Whether the client implementation supports a refresh request sent from + * the server to the client. + * + * Note that this event is global and will force the client to refresh all + * semantic tokens currently shown. It should be used with absolute care + * and is useful for situation where a server for example detect a project + * wide change that requires such a calculation. + */ + refreshSupport?: boolean; +} +``` + +_Request_: + +
+ +* method: `workspace/semanticTokens/refresh` +* params: none + +_Response_: + +* result: void +* error: code and message set in case an exception happens during the 'workspace/semanticTokens/refresh' request diff --git a/_specifications/specification-3-17.md b/_specifications/lsp/3.17/specification.md similarity index 67% rename from _specifications/specification-3-17.md rename to _specifications/lsp/3.17/specification.md index 11367115f..0678e1b81 100644 --- a/_specifications/specification-3-17.md +++ b/_specifications/lsp/3.17/specification.md @@ -476,7 +476,7 @@ The only regular expression flag that a client needs to support is 'i' to specif The protocol supports two kind of enumerations: (a) integer based enumerations and (b) strings based enumerations. Integer based enumerations usually start with `1`. The onces that don't are historical and they were kept to stay backwards compatible. If appropriate the value set of an enumeration is announced by the defining side (e.g. client or server) and transmitted to the other side during the initialize handshake. An example is the `CompletionItemKind` enumeration. It is announced by the client using the `textDocument.completion.completionItemKind` client property. -To support the evolution of enumerations the using side of an enumeration shouldn't fail on a enumeration value it doesn't know. It should simply ignore it as a value it can use and try to do its best to preserve the value on round trips. Lets look at the `CompletionItemKind` enumeration as an example again: if in a future version of the specification an additional completion item kind with the value `n` gets added and announced by a client a (older) server not knowing about the value should not fail but simply ignore the value as a usable item kind. +To support the evolution of enumerations the using side of an enumeration shouldn't fail on an enumeration value it doesn't know. It should simply ignore it as a value it can use and try to do its best to preserve the value on round trips. Lets look at the `CompletionItemKind` enumeration as an example again: if in a future version of the specification an additional completion item kind with the value `n` gets added and announced by a client a (older) server not knowing about the value should not fail but simply ignore the value as a usable item kind. #### Text Documents @@ -6112,3069 +6112,25 @@ _Response_: * partial result: [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] * error: code and message set in case an exception happens during the definition request. -#### Goto Implementation Request (:leftwards_arrow_with_hook:) - -> *Since version 3.6.0* - -The go to implementation request is sent from the client to the server to resolve the implementation location of a symbol at a given text document position. - -The result type [`LocationLink`](#locationLink)[] got introduced with version 3.14.0 and depends on the corresponding client capability `textDocument.implementation.linkSupport`. - -_Client Capability_: -* property name (optional): `textDocument.implementation` -* property type: `ImplementationClientCapabilities` defined as follows: - -
- -```typescript -export interface ImplementationClientCapabilities { - /** - * Whether implementation supports dynamic registration. If this is set to - * `true` the client supports the new `ImplementationRegistrationOptions` - * return value for the corresponding server capability as well. - */ - dynamicRegistration?: boolean; - - /** - * The client supports additional metadata in the form of definition links. - * - * @since 3.14.0 - */ - linkSupport?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `implementationProvider` -* property type: `boolean | ImplementationOptions | ImplementationRegistrationOptions` where `ImplementationOptions` is defined as follows: - -
- -```typescript -export interface ImplementationOptions extends WorkDoneProgressOptions { -} -``` - -_Registration Options_: `ImplementationRegistrationOptions` defined as follows: - -
- -```typescript -export interface ImplementationRegistrationOptions extends - TextDocumentRegistrationOptions, ImplementationOptions, - StaticRegistrationOptions { -} -``` - -_Request_: -* method: `textDocument/implementation` -* params: `ImplementationParams` defined as follows: - -
- -```typescript -export interface ImplementationParams extends TextDocumentPositionParams, - WorkDoneProgressParams, PartialResultParams { -} -``` - -_Response_: -* result: [`Location`](#location) \| [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] \| `null` -* partial result: [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] -* error: code and message set in case an exception happens during the definition request. - -#### Find References Request (:leftwards_arrow_with_hook:) - -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. - -_Client Capability_: -* property name (optional): `textDocument.references` -* property type: `ReferenceClientCapabilities` defined as follows: - -
- -```typescript -export interface ReferenceClientCapabilities { - /** - * Whether references supports dynamic registration. - */ - dynamicRegistration?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `referencesProvider` -* property type: `boolean | ReferenceOptions` where `ReferenceOptions` is defined as follows: - -
- -```typescript -export interface ReferenceOptions extends WorkDoneProgressOptions { -} -``` - -_Registration Options_: `ReferenceRegistrationOptions` defined as follows: - -
- -```typescript -export interface ReferenceRegistrationOptions extends - TextDocumentRegistrationOptions, ReferenceOptions { -} -``` - -_Request_: -* method: `textDocument/references` -* params: `ReferenceParams` defined as follows: - -
- -```typescript -export interface ReferenceParams extends TextDocumentPositionParams, - WorkDoneProgressParams, PartialResultParams { - context: ReferenceContext; -} -``` - -
- -```typescript -export interface ReferenceContext { - /** - * Include the declaration of the current symbol. - */ - includeDeclaration: boolean; -} -``` -_Response_: -* result: [`Location`](#location)[] \| `null` -* partial result: [`Location`](#location)[] -* error: code and message set in case an exception happens during the reference request. - -#### Document Highlights Request (:leftwards_arrow_with_hook:) - -The document highlight request is sent from the client to the server to resolve a document highlights for a given text document position. -For programming languages this usually highlights all references to the symbol scoped to this file. However we kept 'textDocument/documentHighlight' -and 'textDocument/references' separate requests since the first one is allowed to be more fuzzy. Symbol matches usually have a `DocumentHighlightKind` -of `Read` or `Write` whereas fuzzy or textual matches use `Text`as the kind. - -_Client Capability_: -* property name (optional): `textDocument.documentHighlight` -* property type: `DocumentHighlightClientCapabilities` defined as follows: - -
- -```typescript -export interface DocumentHighlightClientCapabilities { - /** - * Whether document highlight supports dynamic registration. - */ - dynamicRegistration?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `documentHighlightProvider` -* property type: `boolean | DocumentHighlightOptions` where `DocumentHighlightOptions` is defined as follows: - -
- -```typescript -export interface DocumentHighlightOptions extends WorkDoneProgressOptions { -} -``` - -_Registration Options_: `DocumentHighlightRegistrationOptions` defined as follows: - -
- -```typescript -export interface DocumentHighlightRegistrationOptions extends - TextDocumentRegistrationOptions, DocumentHighlightOptions { -} -``` - -_Request_: -* method: `textDocument/documentHighlight` -* params: `DocumentHighlightParams` defined as follows: - -
- -```typescript -export interface DocumentHighlightParams extends TextDocumentPositionParams, - WorkDoneProgressParams, PartialResultParams { -} -``` - -_Response_: -* result: `DocumentHighlight[]` \| `null` defined as follows: - -
- -```typescript -/** - * A document highlight is a range inside a text document which deserves - * special attention. Usually a document highlight is visualized by changing - * the background color of its range. - * - */ -export interface DocumentHighlight { - /** - * The range this highlight applies to. - */ - range: Range; - - /** - * The highlight kind, default is DocumentHighlightKind.Text. - */ - kind?: DocumentHighlightKind; -} -``` - -
- -```typescript -/** - * A document highlight kind. - */ -export namespace DocumentHighlightKind { - /** - * A textual occurrence. - */ - export const Text = 1; - - /** - * Read-access of a symbol, like reading a variable. - */ - export const Read = 2; - - /** - * Write-access of a symbol, like writing to a variable. - */ - export const Write = 3; -} - -export type DocumentHighlightKind = 1 | 2 | 3; -``` - -* partial result: `DocumentHighlight[]` -* error: code and message set in case an exception happens during the document highlight request. - -#### Document Symbols Request (:leftwards_arrow_with_hook:) - -The document symbol request is sent from the client to the server. The returned result is either - -- `SymbolInformation[]` which is a flat list of all symbols found in a given text document. Then neither the symbol's location range nor the symbol's container name should be used to infer a hierarchy. -- `DocumentSymbol[]` which is a hierarchy of symbols found in a given text document. - -Servers should whenever possible return `DocumentSymbol` since it is the richer data structure. - -_Client Capability_: -* property name (optional): `textDocument.documentSymbol` -* property type: `DocumentSymbolClientCapabilities` defined as follows: - -
- -```typescript -export interface DocumentSymbolClientCapabilities { - /** - * Whether document symbol supports dynamic registration. - */ - dynamicRegistration?: boolean; - - /** - * Specific capabilities for the `SymbolKind` in the - * `textDocument/documentSymbol` request. - */ - symbolKind?: { - /** - * The symbol kind values the client supports. When this - * property exists the client also guarantees that it will - * handle values outside its set gracefully and falls back - * to a default value when unknown. - * - * If this property is not present the client only supports - * the symbol kinds from `File` to `Array` as defined in - * the initial version of the protocol. - */ - valueSet?: SymbolKind[]; - }; - - /** - * The client supports hierarchical document symbols. - */ - hierarchicalDocumentSymbolSupport?: boolean; - - /** - * The client supports tags on `SymbolInformation`. Tags are supported on - * `DocumentSymbol` if `hierarchicalDocumentSymbolSupport` is set to true. - * Clients supporting tags have to handle unknown tags gracefully. - * - * @since 3.16.0 - */ - tagSupport?: { - /** - * The tags supported by the client. - */ - valueSet: SymbolTag[]; - }; - - /** - * The client supports an additional label presented in the UI when - * registering a document symbol provider. - * - * @since 3.16.0 - */ - labelSupport?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `documentSymbolProvider` -* property type: `boolean | DocumentSymbolOptions` where `DocumentSymbolOptions` is defined as follows: - -
- -```typescript -export interface DocumentSymbolOptions extends WorkDoneProgressOptions { - /** - * A human-readable string that is shown when multiple outlines trees - * are shown for the same document. - * - * @since 3.16.0 - */ - label?: string; -} -``` - -_Registration Options_: `DocumentSymbolRegistrationOptions` defined as follows: - -
- -```typescript -export interface DocumentSymbolRegistrationOptions extends - TextDocumentRegistrationOptions, DocumentSymbolOptions { -} -``` - -_Request_: -* method: `textDocument/documentSymbol` -* params: `DocumentSymbolParams` defined as follows: - -
- -```typescript -export interface DocumentSymbolParams extends WorkDoneProgressParams, - PartialResultParams { - /** - * The text document. - */ - textDocument: TextDocumentIdentifier; -} -``` - -_Response_: -* result: `DocumentSymbol[]` \| `SymbolInformation[]` \| `null` defined as follows: - -
- -```typescript -/** - * A symbol kind. - */ -export namespace SymbolKind { - export const File = 1; - export const Module = 2; - export const Namespace = 3; - export const Package = 4; - export const Class = 5; - export const Method = 6; - export const Property = 7; - export const Field = 8; - export const Constructor = 9; - export const Enum = 10; - export const Interface = 11; - export const Function = 12; - export const Variable = 13; - export const Constant = 14; - export const String = 15; - export const Number = 16; - export const Boolean = 17; - export const Array = 18; - export const Object = 19; - export const Key = 20; - export const Null = 21; - export const EnumMember = 22; - export const Struct = 23; - export const Event = 24; - export const Operator = 25; - export const TypeParameter = 26; -} -``` - -
- -```typescript -/** - * Symbol tags are extra annotations that tweak the rendering of a symbol. - * - * @since 3.16 - */ -export namespace SymbolTag { - - /** - * Render a symbol as obsolete, usually using a strike-out. - */ - export const Deprecated: 1 = 1; -} - -export type SymbolTag = 1; -``` - -
- -```typescript -/** - * Represents programming constructs like variables, classes, interfaces etc. - * that appear in a document. Document symbols can be hierarchical and they - * have two ranges: one that encloses its definition and one that points to its - * most interesting range, e.g. the range of an identifier. - */ -export interface DocumentSymbol { - - /** - * The name of this symbol. Will be displayed in the user interface and - * therefore must not be an empty string or a string only consisting of - * white spaces. - */ - name: string; - - /** - * More detail for this symbol, e.g the signature of a function. - */ - detail?: string; - - /** - * The kind of this symbol. - */ - kind: SymbolKind; - - /** - * Tags for this document symbol. - * - * @since 3.16.0 - */ - tags?: SymbolTag[]; - - /** - * Indicates if this symbol is deprecated. - * - * @deprecated Use tags instead - */ - deprecated?: boolean; - - /** - * The range enclosing this symbol not including leading/trailing whitespace - * but everything else like comments. This information is typically used to - * determine if the clients cursor is inside the symbol to reveal in the - * symbol in the UI. - */ - range: Range; - - /** - * The range that should be selected and revealed when this symbol is being - * picked, e.g. the name of a function. Must be contained by the `range`. - */ - selectionRange: Range; - - /** - * Children of this symbol, e.g. properties of a class. - */ - children?: DocumentSymbol[]; -} -``` - -
- -```typescript -/** - * Represents information about programming constructs like variables, classes, - * interfaces etc. - * - * @deprecated use DocumentSymbol or WorkspaceSymbol instead. - */ -export interface SymbolInformation { - /** - * The name of this symbol. - */ - name: string; - - /** - * The kind of this symbol. - */ - kind: SymbolKind; - - /** - * Tags for this symbol. - * - * @since 3.16.0 - */ - tags?: SymbolTag[]; - - /** - * Indicates if this symbol is deprecated. - * - * @deprecated Use tags instead - */ - deprecated?: boolean; - - /** - * The location of this symbol. The location's range is used by a tool - * to reveal the location in the editor. If the symbol is selected in the - * tool the range's start information is used to position the cursor. So - * the range usually spans more then the actual symbol's name and does - * normally include things like visibility modifiers. - * - * The range doesn't have to denote a node range in the sense of a abstract - * syntax tree. It can therefore not be used to re-construct a hierarchy of - * the symbols. - */ - location: Location; - - /** - * The name of the symbol containing this symbol. This information is for - * user interface purposes (e.g. to render a qualifier in the user interface - * if necessary). It can't be used to re-infer a hierarchy for the document - * symbols. - */ - containerName?: string; -} -``` - -* partial result: `DocumentSymbol[]` \| `SymbolInformation[]`. `DocumentSymbol[]` and `SymbolInformation[]` can not be mixed. That means the first chunk defines the type of all the other chunks. -* error: code and message set in case an exception happens during the document symbol request. - -#### Code Action Request (:leftwards_arrow_with_hook:) - -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. The result of a `textDocument/codeAction` request is an array of `Command` literals which are typically presented in the user interface. To ensure that a server is useful in many clients the commands specified in a code actions should be handled by the server and not by the client (see `workspace/executeCommand` and `ServerCapabilities.executeCommandProvider`). If the client supports providing edits with a code action then that mode should be used. - -*Since version 3.16.0:* a client can offer a server to delay the computation of code action properties during a 'textDocument/codeAction' request: - -This is useful for cases where it is expensive to compute the value of a property (for example the `edit` property). Clients signal this through the `codeAction.resolveSupport` capability which lists all properties a client can resolve lazily. The server capability `codeActionProvider.resolveProvider` signals that a server will offer a `codeAction/resolve` route. To help servers to uniquely identify a code action in the resolve request, a code action literal can optional carry a data property. This is also guarded by an additional client capability `codeAction.dataSupport`. In general, a client should offer data support if it offers resolve support. It should also be noted that servers shouldn't alter existing attributes of a code action in a codeAction/resolve request. - -> *Since version 3.8.0:* support for CodeAction literals to enable the following scenarios: - -- the ability to directly return a workspace edit from the code action request. This avoids having another server roundtrip to execute an actual code action. However server providers should be aware that if the code action is expensive to compute or the edits are huge it might still be beneficial if the result is simply a command and the actual edit is only computed when needed. -- the ability to group code actions using a kind. Clients are allowed to ignore that information. However it allows them to better group code action for example into corresponding menus (e.g. all refactor code actions into a refactor menu). - -Clients need to announce their support for code action literals (e.g. literals of type `CodeAction`) and code action kinds via the corresponding client capability `codeAction.codeActionLiteralSupport`. - -_Client Capability_: -* property name (optional): `textDocument.codeAction` -* property type: `CodeActionClientCapabilities` defined as follows: - -
- -```typescript -export interface CodeActionClientCapabilities { - /** - * Whether code action supports dynamic registration. - */ - dynamicRegistration?: boolean; - - /** - * The client supports code action literals as a valid - * response of the `textDocument/codeAction` request. - * - * @since 3.8.0 - */ - codeActionLiteralSupport?: { - /** - * The code action kind is supported with the following value - * set. - */ - codeActionKind: { - - /** - * The code action kind values the client supports. When this - * property exists the client also guarantees that it will - * handle values outside its set gracefully and falls back - * to a default value when unknown. - */ - valueSet: CodeActionKind[]; - }; - }; - - /** - * Whether code action supports the `isPreferred` property. - * - * @since 3.15.0 - */ - isPreferredSupport?: boolean; - - /** - * Whether code action supports the `disabled` property. - * - * @since 3.16.0 - */ - disabledSupport?: boolean; - - /** - * Whether code action supports the `data` property which is - * preserved between a `textDocument/codeAction` and a - * `codeAction/resolve` request. - * - * @since 3.16.0 - */ - dataSupport?: boolean; - - - /** - * Whether the client supports resolving additional code action - * properties via a separate `codeAction/resolve` request. - * - * @since 3.16.0 - */ - resolveSupport?: { - /** - * The properties that a client can resolve lazily. - */ - properties: string[]; - }; - - /** - * Whether the client honors the change annotations in - * text edits and resource operations returned via the - * `CodeAction#edit` property by for example presenting - * the workspace edit in the user interface and asking - * for confirmation. - * - * @since 3.16.0 - */ - honorsChangeAnnotations?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `codeActionProvider` -* property type: `boolean | CodeActionOptions` where `CodeActionOptions` is defined as follows: - -
- -```typescript -export interface CodeActionOptions extends WorkDoneProgressOptions { - /** - * CodeActionKinds that this server may return. - * - * The list of kinds may be generic, such as `CodeActionKind.Refactor`, - * or the server may list out every specific kind they provide. - */ - codeActionKinds?: CodeActionKind[]; - - /** - * The server provides support to resolve additional - * information for a code action. - * - * @since 3.16.0 - */ - resolveProvider?: boolean; -} -``` - -_Registration Options_: `CodeActionRegistrationOptions` defined as follows: - -
- -```typescript -export interface CodeActionRegistrationOptions extends - TextDocumentRegistrationOptions, CodeActionOptions { -} -``` - -_Request_: -* method: `textDocument/codeAction` -* params: `CodeActionParams` defined as follows: - -
- -```typescript -/** - * Params for the CodeActionRequest - */ -export interface CodeActionParams extends WorkDoneProgressParams, - PartialResultParams { - /** - * The document in which the command was invoked. - */ - textDocument: TextDocumentIdentifier; - - /** - * The range for which the command was invoked. - */ - range: Range; - - /** - * Context carrying additional information. - */ - context: CodeActionContext; -} -``` - -
- -```typescript -/** - * The kind of a code action. - * - * Kinds are a hierarchical list of identifiers separated by `.`, - * e.g. `"refactor.extract.function"`. - * - * The set of kinds is open and client needs to announce the kinds it supports - * to the server during initialization. - */ -export type CodeActionKind = string; - -/** - * A set of predefined code action kinds. - */ -export namespace CodeActionKind { - - /** - * Empty kind. - */ - export const Empty: CodeActionKind = ''; - - /** - * Base kind for quickfix actions: 'quickfix'. - */ - export const QuickFix: CodeActionKind = 'quickfix'; - - /** - * Base kind for refactoring actions: 'refactor'. - */ - export const Refactor: CodeActionKind = 'refactor'; - - /** - * Base kind for refactoring extraction actions: 'refactor.extract'. - * - * Example extract actions: - * - * - Extract method - * - Extract function - * - Extract variable - * - Extract interface from class - * - ... - */ - export const RefactorExtract: CodeActionKind = 'refactor.extract'; - - /** - * Base kind for refactoring inline actions: 'refactor.inline'. - * - * Example inline actions: - * - * - Inline function - * - Inline variable - * - Inline constant - * - ... - */ - export const RefactorInline: CodeActionKind = 'refactor.inline'; - - /** - * Base kind for refactoring rewrite actions: 'refactor.rewrite'. - * - * Example rewrite actions: - * - * - Convert JavaScript function to class - * - Add or remove parameter - * - Encapsulate field - * - Make method static - * - Move method to base class - * - ... - */ - export const RefactorRewrite: CodeActionKind = 'refactor.rewrite'; - - /** - * Base kind for source actions: `source`. - * - * Source code actions apply to the entire file. - */ - export const Source: CodeActionKind = 'source'; - - /** - * Base kind for an organize imports source action: - * `source.organizeImports`. - */ - export const SourceOrganizeImports: CodeActionKind = - 'source.organizeImports'; - - /** - * Base kind for a 'fix all' source action: `source.fixAll`. - * - * 'Fix all' actions automatically fix errors that have a clear fix that - * do not require user input. They should not suppress errors or perform - * unsafe fixes such as generating new types or classes. - * - * @since 3.17.0 - */ - export const SourceFixAll: CodeActionKind = 'source.fixAll'; -} -``` - -
- -```typescript -/** - * Contains additional diagnostic information about the context in which - * a code action is run. - */ -export interface CodeActionContext { - /** - * An array of diagnostics known on the client side overlapping the range - * provided to the `textDocument/codeAction` request. They are provided so - * that the server knows which errors are currently presented to the user - * for the given range. There is no guarantee that these accurately reflect - * the error state of the resource. The primary parameter - * to compute code actions is the provided range. - */ - diagnostics: Diagnostic[]; - - /** - * Requested kind of actions to return. - * - * Actions not of this kind are filtered out by the client before being - * shown. So servers can omit computing them. - */ - only?: CodeActionKind[]; - - /** - * The reason why code actions were requested. - * - * @since 3.17.0 - */ - triggerKind?: CodeActionTriggerKind; -} -``` - -
- -```typescript -/** - * The reason why code actions were requested. - * - * @since 3.17.0 - proposed state - */ -export namespace CodeActionTriggerKind { - /** - * Code actions were explicitly requested by the user or by an extension. - */ - export const Invoked: 1 = 1; - - /** - * Code actions were requested automatically. - * - * This typically happens when current selection in a file changes, but can - * also be triggered when file content changes. - */ - export const Automatic: 2 = 2; -} - -export type CodeActionTriggerKind = 1 | 2; -``` - -_Response_: -* result: `(Command | CodeAction)[]` \| `null` where `CodeAction` is defined as follows: - -
- -```typescript -/** - * A code action represents a change that can be performed in code, e.g. to fix - * a problem or to refactor code. - * - * A CodeAction must set either `edit` and/or a `command`. If both are supplied, - * the `edit` is applied first, then the `command` is executed. - */ -export interface CodeAction { - - /** - * A short, human-readable, title for this code action. - */ - title: string; - - /** - * The kind of the code action. - * - * Used to filter code actions. - */ - kind?: CodeActionKind; - - /** - * The diagnostics that this code action resolves. - */ - diagnostics?: Diagnostic[]; - - /** - * Marks this as a preferred action. Preferred actions are used by the - * `auto fix` command and can be targeted by keybindings. - * - * A quick fix should be marked preferred if it properly addresses the - * underlying error. A refactoring should be marked preferred if it is the - * most reasonable choice of actions to take. - * - * @since 3.15.0 - */ - isPreferred?: boolean; - - /** - * Marks that the code action cannot currently be applied. - * - * Clients should follow the following guidelines regarding disabled code - * actions: - * - * - Disabled code actions are not shown in automatic lightbulbs code - * action menus. - * - * - Disabled actions are shown as faded out in the code action menu when - * the user request a more specific type of code action, such as - * refactorings. - * - * - If the user has a keybinding that auto applies a code action and only - * a disabled code actions are returned, the client should show the user - * an error message with `reason` in the editor. - * - * @since 3.16.0 - */ - disabled?: { - - /** - * Human readable description of why the code action is currently - * disabled. - * - * This is displayed in the code actions UI. - */ - reason: string; - }; - - /** - * The workspace edit this code action performs. - */ - edit?: WorkspaceEdit; - - /** - * A command this code action executes. If a code action - * provides an edit and a command, first the edit is - * executed and then the command. - */ - command?: Command; - - /** - * A data entry field that is preserved on a code action between - * a `textDocument/codeAction` and a `codeAction/resolve` request. - * - * @since 3.16.0 - */ - data?: LSPAny; -} -``` -* partial result: `(Command | CodeAction)[]` -* error: code and message set in case an exception happens during the code action request. - -#### Code Action Resolve Request (:leftwards_arrow_with_hook:) - -> *Since version 3.16.0* - -The request is sent from the client to the server to resolve additional information for a given code action. This is usually used to compute -the `edit` property of a code action to avoid its unnecessary computation during the `textDocument/codeAction` request. - -Consider the clients announces the `edit` property as a property that can be resolved lazy using the client capability - -```typescript -textDocument.codeAction.resolveSupport = { properties: ['edit'] }; -``` - -then a code action - -```typescript -{ - "title": "Do Foo" -} -``` - -needs to be resolved using the `codeAction/resolve` request before it can be applied. - -_Client Capability_: -* property name (optional): `textDocument.codeAction.resolveSupport` -* property type: `{ properties: string[]; }` - -_Request_: -* method: `codeAction/resolve` -* params: `CodeAction` - -_Response_: -* result: `CodeAction` -* error: code and message set in case an exception happens during the completion resolve request. - -#### Code Lens Request (:leftwards_arrow_with_hook:) - -The code lens request is sent from the client to the server to compute code lenses for a given text document. - -_Client Capability_: -* property name (optional): `textDocument.codeLens` -* property type: `CodeLensClientCapabilities` defined as follows: - -
- -```typescript -export interface CodeLensClientCapabilities { - /** - * Whether code lens supports dynamic registration. - */ - dynamicRegistration?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `codeLensProvider` -* property type: `CodeLensOptions` defined as follows: - -
- -```typescript -export interface CodeLensOptions extends WorkDoneProgressOptions { - /** - * Code lens has a resolve provider as well. - */ - resolveProvider?: boolean; -} -``` - -_Registration Options_: `CodeLensRegistrationOptions` defined as follows: - -
- -```typescript -export interface CodeLensRegistrationOptions extends - TextDocumentRegistrationOptions, CodeLensOptions { -} -``` - -_Request_: -* method: `textDocument/codeLens` -* params: `CodeLensParams` defined as follows: - -
- -```typescript -interface CodeLensParams extends WorkDoneProgressParams, PartialResultParams { - /** - * The document to request code lens for. - */ - textDocument: TextDocumentIdentifier; -} -``` - -_Response_: -* result: `CodeLens[]` \| `null` defined as follows: - -
- -```typescript -/** - * A code lens represents a command that should be shown along with - * source text, like the number of references, a way to run tests, etc. - * - * A code lens is _unresolved_ when no command is associated to it. For - * performance reasons the creation of a code lens and resolving should be done - * in two stages. - */ -interface CodeLens { - /** - * The range in which this code lens is valid. Should only span a single - * line. - */ - range: Range; - - /** - * The command this code lens represents. - */ - command?: Command; - - /** - * A data entry field that is preserved on a code lens item between - * a code lens and a code lens resolve request. - */ - data?: LSPAny; -} -``` -* partial result: `CodeLens[]` -* error: code and message set in case an exception happens during the code lens request. - -#### Code Lens Resolve Request (:leftwards_arrow_with_hook:) - -The code lens resolve request is sent from the client to the server to resolve the command for a given code lens item. - -_Request_: -* method: `codeLens/resolve` -* params: `CodeLens` - -_Response_: -* result: `CodeLens` -* error: code and message set in case an exception happens during the code lens resolve request. - -#### Code Lens Refresh Request (:arrow_right_hook:) - -> *Since version 3.16.0* - -The `workspace/codeLens/refresh` request is sent from the server to the client. Servers can use it to ask clients to refresh the code lenses currently shown in editors. As a result the client should ask the server to recompute the code lenses for these editors. This is useful if a server detects a configuration change which requires a re-calculation of all code lenses. Note that the client still has the freedom to delay the re-calculation of the code lenses if for example an editor is currently not visible. - -_Client Capability_: - -* property name (optional): `workspace.codeLens` -* property type: `CodeLensWorkspaceClientCapabilities` defined as follows: - -
- -```typescript -export interface CodeLensWorkspaceClientCapabilities { - /** - * Whether the client implementation supports a refresh request sent from the - * server to the client. - * - * Note that this event is global and will force the client to refresh all - * code lenses currently shown. It should be used with absolute care and is - * useful for situation where a server for example detect a project wide - * change that requires such a calculation. - */ - refreshSupport?: boolean; -} -``` - -_Request_: - -* method: `workspace/codeLens/refresh` -* params: none - -_Response_: - -* result: void -* error: code and message set in case an exception happens during the 'workspace/codeLens/refresh' request - -#### Document Link Request (:leftwards_arrow_with_hook:) - -The document links request is sent from the client to the server to request the location of links in a document. - -_Client Capability_: -* property name (optional): `textDocument.documentLink` -* property type: `DocumentLinkClientCapabilities` defined as follows: - -
- -```typescript -export interface DocumentLinkClientCapabilities { - /** - * Whether document link supports dynamic registration. - */ - dynamicRegistration?: boolean; - - /** - * Whether the client supports the `tooltip` property on `DocumentLink`. - * - * @since 3.15.0 - */ - tooltipSupport?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `documentLinkProvider` -* property type: `DocumentLinkOptions` defined as follows: - -
- -```typescript -export interface DocumentLinkOptions extends WorkDoneProgressOptions { - /** - * Document links have a resolve provider as well. - */ - resolveProvider?: boolean; -} -``` - -_Registration Options_: `DocumentLinkRegistrationOptions` defined as follows: - -
- -```typescript -export interface DocumentLinkRegistrationOptions extends - TextDocumentRegistrationOptions, DocumentLinkOptions { -} -``` - -_Request_: -* method: `textDocument/documentLink` -* params: `DocumentLinkParams` defined as follows: - -
- -```typescript -interface DocumentLinkParams extends WorkDoneProgressParams, - PartialResultParams { - /** - * The document to provide document links for. - */ - textDocument: TextDocumentIdentifier; -} -``` - -_Response_: -* result: `DocumentLink[]` \| `null`. - -
- -```typescript -/** - * A document link is a range in a text document that links to an internal or - * external resource, like another text document or a web site. - */ -interface DocumentLink { - /** - * The range this link applies to. - */ - range: Range; - - /** - * The uri this link points to. If missing a resolve request is sent later. - */ - target?: DocumentUri; - - /** - * The tooltip text when you hover over this link. - * - * If a tooltip is provided, is will be displayed in a string that includes - * instructions on how to trigger the link, such as `{0} (ctrl + click)`. - * The specific instructions vary depending on OS, user settings, and - * localization. - * - * @since 3.15.0 - */ - tooltip?: string; - - /** - * A data entry field that is preserved on a document link between a - * DocumentLinkRequest and a DocumentLinkResolveRequest. - */ - data?: LSPAny; -} -``` -* partial result: `DocumentLink[]` -* error: code and message set in case an exception happens during the document link request. - -#### Document Link Resolve Request (:leftwards_arrow_with_hook:) - -The document link resolve request is sent from the client to the server to resolve the target of a given document link. - -_Request_: -* method: `documentLink/resolve` -* params: `DocumentLink` - -_Response_: -* result: `DocumentLink` -* error: code and message set in case an exception happens during the document link resolve request. - -#### Document Color Request (:leftwards_arrow_with_hook:) - -> *Since version 3.6.0* - -The document color request is sent from the client to the server to list all color references found in a given text document. Along with the range, a color value in RGB is returned. - -Clients can use the result to decorate color references in an editor. For example: -- Color boxes showing the actual color next to the reference -- Show a color picker when a color reference is edited - -_Client Capability_: -* property name (optional): `textDocument.colorProvider` -* property type: `DocumentColorClientCapabilities` defined as follows: - -
- -```typescript -export interface DocumentColorClientCapabilities { - /** - * Whether document color supports dynamic registration. - */ - dynamicRegistration?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `colorProvider` -* property type: `boolean | DocumentColorOptions | DocumentColorRegistrationOptions` where `DocumentColorOptions` is defined as follows: - -
- -```typescript -export interface DocumentColorOptions extends WorkDoneProgressOptions { -} -``` - -_Registration Options_: `DocumentColorRegistrationOptions` defined as follows: - -
- -```typescript -export interface DocumentColorRegistrationOptions extends - TextDocumentRegistrationOptions, StaticRegistrationOptions, - DocumentColorOptions { -} -``` - -_Request_: - -* method: `textDocument/documentColor` -* params: `DocumentColorParams` defined as follows - -
- -```typescript -interface DocumentColorParams extends WorkDoneProgressParams, - PartialResultParams { - /** - * The text document. - */ - textDocument: TextDocumentIdentifier; -} -``` - -_Response_: -* result: `ColorInformation[]` defined as follows: - -
- -```typescript -interface ColorInformation { - /** - * The range in the document where this color appears. - */ - range: Range; - - /** - * The actual color value for this color range. - */ - color: Color; -} -``` - -
- -```typescript -/** - * Represents a color in RGBA space. - */ -interface Color { - - /** - * The red component of this color in the range [0-1]. - */ - readonly red: decimal; - - /** - * The green component of this color in the range [0-1]. - */ - readonly green: decimal; - - /** - * The blue component of this color in the range [0-1]. - */ - readonly blue: decimal; - - /** - * The alpha component of this color in the range [0-1]. - */ - readonly alpha: decimal; -} -``` -* partial result: `ColorInformation[]` -* error: code and message set in case an exception happens during the 'textDocument/documentColor' request - -#### Color Presentation Request (:leftwards_arrow_with_hook:) - -> *Since version 3.6.0* - -The color presentation request is sent from the client to the server to obtain a list of presentations for a color value at a given location. Clients can use the result to -- modify a color reference. -- show in a color picker and let users pick one of the presentations - -This request has no special capabilities and registration options since it is send as a resolve request for the `textDocument/documentColor` request. - -_Request_: - -* method: `textDocument/colorPresentation` -* params: `ColorPresentationParams` defined as follows - -
- -```typescript -interface ColorPresentationParams extends WorkDoneProgressParams, - PartialResultParams { - /** - * The text document. - */ - textDocument: TextDocumentIdentifier; - - /** - * The color information to request presentations for. - */ - color: Color; - - /** - * The range where the color would be inserted. Serves as a context. - */ - range: Range; -} -``` - -_Response_: -* result: `ColorPresentation[]` defined as follows: - -
- -```typescript -interface ColorPresentation { - /** - * The label of this color presentation. It will be shown on the color - * picker header. By default this is also the text that is inserted when - * selecting this color presentation. - */ - label: string; - /** - * An [edit](#TextEdit) which is applied to a document when selecting - * this presentation for the color. When `falsy` the - * [label](#ColorPresentation.label) is used. - */ - textEdit?: TextEdit; - /** - * An optional array of additional [text edits](#TextEdit) that are applied - * when selecting this color presentation. Edits must not overlap with the - * main [edit](#ColorPresentation.textEdit) nor with themselves. - */ - additionalTextEdits?: TextEdit[]; -} -``` - -* partial result: `ColorPresentation[]` -* error: code and message set in case an exception happens during the 'textDocument/colorPresentation' request - -#### Document Formatting Request (:leftwards_arrow_with_hook:) - -The document formatting request is sent from the client to the server to format a whole document. - -_Client Capability_: -* property name (optional): `textDocument.formatting` -* property type: `DocumentFormattingClientCapabilities` defined as follows: - -
- -```typescript -export interface DocumentFormattingClientCapabilities { - /** - * Whether formatting supports dynamic registration. - */ - dynamicRegistration?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `documentFormattingProvider` -* property type: `boolean | DocumentFormattingOptions` where `DocumentFormattingOptions` is defined as follows: - -
- -```typescript -export interface DocumentFormattingOptions extends WorkDoneProgressOptions { -} -``` - -_Registration Options_: `DocumentFormattingRegistrationOptions` defined as follows: - -
- -```typescript -export interface DocumentFormattingRegistrationOptions extends - TextDocumentRegistrationOptions, DocumentFormattingOptions { -} -``` - -_Request_: -* method: `textDocument/formatting` -* params: `DocumentFormattingParams` defined as follows - -
- -```typescript -interface DocumentFormattingParams extends WorkDoneProgressParams { - /** - * The document to format. - */ - textDocument: TextDocumentIdentifier; - - /** - * The format options. - */ - options: FormattingOptions; -} -``` - -
- -```typescript -/** - * Value-object describing what options formatting should use. - */ -interface FormattingOptions { - /** - * Size of a tab in spaces. - */ - tabSize: uinteger; - - /** - * Prefer spaces over tabs. - */ - insertSpaces: boolean; - - /** - * Trim trailing whitespace on a line. - * - * @since 3.15.0 - */ - trimTrailingWhitespace?: boolean; - - /** - * Insert a newline character at the end of the file if one does not exist. - * - * @since 3.15.0 - */ - insertFinalNewline?: boolean; - - /** - * Trim all newlines after the final newline at the end of the file. - * - * @since 3.15.0 - */ - trimFinalNewlines?: boolean; - - /** - * Signature for further properties. - */ - [key: string]: boolean | integer | string; -} -``` - -_Response_: -* result: [`TextEdit[]`](#textEdit) \| `null` describing the modification to the document to be formatted. -* error: code and message set in case an exception happens during the formatting request. - -#### Document Range Formatting Request (:leftwards_arrow_with_hook:) - -The document range formatting request is sent from the client to the server to format a given range in a document. - -_Client Capability_: -* property name (optional): `textDocument.rangeFormatting` -* property type: `DocumentRangeFormattingClientCapabilities` defined as follows: - -
- -```typescript -export interface DocumentRangeFormattingClientCapabilities { - /** - * Whether formatting supports dynamic registration. - */ - dynamicRegistration?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `documentRangeFormattingProvider` -* property type: `boolean | DocumentRangeFormattingOptions` where `DocumentRangeFormattingOptions` is defined as follows: - -
- -```typescript -export interface DocumentRangeFormattingOptions extends - WorkDoneProgressOptions { -} -``` - -_Registration Options_: `DocumentFormattingRegistrationOptions` defined as follows: - -
- -```typescript -export interface DocumentRangeFormattingRegistrationOptions extends - TextDocumentRegistrationOptions, DocumentRangeFormattingOptions { -} -``` - -_Request_: -* method: `textDocument/rangeFormatting`, -* params: `DocumentRangeFormattingParams` defined as follows: - -
- -```typescript -interface DocumentRangeFormattingParams extends WorkDoneProgressParams { - /** - * The document to format. - */ - textDocument: TextDocumentIdentifier; - - /** - * The range to format - */ - range: Range; - - /** - * The format options - */ - options: FormattingOptions; -} -``` - -_Response_: -* result: [`TextEdit[]`](#textEdit) \| `null` describing the modification to the document to be formatted. -* error: code and message set in case an exception happens during the range formatting request. - -#### Document on Type Formatting Request (:leftwards_arrow_with_hook:) - -The document on type formatting request is sent from the client to the server to format parts of the document during typing. - -_Client Capability_: -* property name (optional): `textDocument.onTypeFormatting` -* property type: `DocumentOnTypeFormattingClientCapabilities` defined as follows: - -
- -```typescript -export interface DocumentOnTypeFormattingClientCapabilities { - /** - * Whether on type formatting supports dynamic registration. - */ - dynamicRegistration?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `documentOnTypeFormattingProvider` -* property type: `DocumentOnTypeFormattingOptions` defined as follows: - -
- -```typescript -export interface DocumentOnTypeFormattingOptions { - /** - * A character on which formatting should be triggered, like `}`. - */ - firstTriggerCharacter: string; - - /** - * More trigger characters. - */ - moreTriggerCharacter?: string[]; -} -``` - -_Registration Options_: `DocumentOnTypeFormattingRegistrationOptions` defined as follows: - -
- -```typescript -export interface DocumentOnTypeFormattingRegistrationOptions extends - TextDocumentRegistrationOptions, DocumentOnTypeFormattingOptions { -} -``` - -_Request_: -* method: `textDocument/onTypeFormatting` -* params: `DocumentOnTypeFormattingParams` defined as follows: - -
- -```typescript -interface DocumentOnTypeFormattingParams extends TextDocumentPositionParams { - /** - * The character that has been typed. - */ - ch: string; - - /** - * The format options. - */ - options: FormattingOptions; -} -``` - -_Response_: -* result: [`TextEdit[]`](#textEdit) \| `null` describing the modification to the document. -* error: code and message set in case an exception happens during the range formatting request. - -#### Rename Request (:leftwards_arrow_with_hook:) - -The rename request is sent from the client to the server to ask the server to compute a workspace change so that the client can perform a workspace-wide rename of a symbol. - -_Client Capability_: -* property name (optional): `textDocument.rename` -* property type: `RenameClientCapabilities` defined as follows: - -
- -```typescript -export namespace PrepareSupportDefaultBehavior { - /** - * The client's default behavior is to select the identifier - * according the to language's syntax rule. - */ - export const Identifier: 1 = 1; -} -``` - -
- -```typescript -export interface RenameClientCapabilities { - /** - * Whether rename supports dynamic registration. - */ - dynamicRegistration?: boolean; - - /** - * Client supports testing for validity of rename operations - * before execution. - * - * @since version 3.12.0 - */ - prepareSupport?: boolean; - - /** - * Client supports the default behavior result - * (`{ defaultBehavior: boolean }`). - * - * The value indicates the default behavior used by the - * client. - * - * @since version 3.16.0 - */ - prepareSupportDefaultBehavior?: PrepareSupportDefaultBehavior; - - /** - * Whether th client honors the change annotations in - * text edits and resource operations returned via the - * rename request's workspace edit by for example presenting - * the workspace edit in the user interface and asking - * for confirmation. - * - * @since 3.16.0 - */ - honorsChangeAnnotations?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `renameProvider` -* property type: `boolean | RenameOptions` where `RenameOptions` is defined as follows: - -`RenameOptions` may only be specified if the client states that it supports `prepareSupport` in its initial `initialize` request. - -
- -```typescript -export interface RenameOptions extends WorkDoneProgressOptions { - /** - * Renames should be checked and tested before being executed. - */ - prepareProvider?: boolean; -} -``` - -_Registration Options_: `RenameRegistrationOptions` defined as follows: - -
- -```typescript -export interface RenameRegistrationOptions extends - TextDocumentRegistrationOptions, RenameOptions { -} -``` - -_Request_: -* method: `textDocument/rename` -* params: `RenameParams` defined as follows - -
- -```typescript -interface RenameParams extends TextDocumentPositionParams, - WorkDoneProgressParams { - /** - * The new name of the symbol. If the given name is not valid the - * request must return a [ResponseError](#ResponseError) with an - * appropriate message set. - */ - newName: string; -} -``` - -_Response_: -* result: [`WorkspaceEdit`](#workspaceedit) \| `null` describing the modification to the workspace. `null` should be treated the same was as [`WorkspaceEdit`](#workspaceedit) with no changes (no change was required). -* error: code and message set in case when rename could not be performed for any reason. Examples include: there is nothing at given `position` to rename (like a space), given symbol does not support renaming by the server or the code is invalid (e.g. does not compile). - -#### Prepare Rename Request (:leftwards_arrow_with_hook:) - -> *Since version 3.12.0* - -The prepare rename request is sent from the client to the server to setup and test the validity of a rename operation at a given location. - -_Request_: -* method: `textDocument/prepareRename` -* params: `PrepareRenameParams` defined as follows: - -
- -```typescript -export interface PrepareRenameParams extends TextDocumentPositionParams { -} -``` - -_Response_: -* result: `Range | { range: Range, placeholder: string } | { defaultBehavior: boolean } | null` describing a [`Range`](#range) of the string to rename and optionally a placeholder text of the string content to be renamed. If `{ defaultBehavior: boolean }` is returned (since 3.16) the rename position is valid and the client should use its default behavior to compute the rename range. If `null` is returned then it is deemed that a 'textDocument/rename' request is not valid at the given position. -* error: code and message set in case the element can't be renamed. Clients should show the information in their user interface. - -#### Folding Range Request (:leftwards_arrow_with_hook:) - -> *Since version 3.10.0* - -The folding range request is sent from the client to the server to return all folding ranges found in a given text document. - -_Client Capability_: -* property name (optional): `textDocument.foldingRange` -* property type: `FoldingRangeClientCapabilities` defined as follows: - -
- -```typescript -export interface FoldingRangeClientCapabilities { - /** - * Whether implementation supports dynamic registration for folding range - * providers. If this is set to `true` the client supports the new - * `FoldingRangeRegistrationOptions` return value for the corresponding - * server capability as well. - */ - dynamicRegistration?: boolean; - /** - * The maximum number of folding ranges that the client prefers to receive - * per document. The value serves as a hint, servers are free to follow the - * limit. - */ - rangeLimit?: uinteger; - /** - * If set, the client signals that it only supports folding complete lines. - * If set, client will ignore specified `startCharacter` and `endCharacter` - * properties in a FoldingRange. - */ - lineFoldingOnly?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `foldingRangeProvider` -* property type: `boolean | FoldingRangeOptions | FoldingRangeRegistrationOptions` where `FoldingRangeOptions` is defined as follows: - -
- -```typescript -export interface FoldingRangeOptions extends WorkDoneProgressOptions { -} -``` - -_Registration Options_: `FoldingRangeRegistrationOptions` defined as follows: - -
- -```typescript -export interface FoldingRangeRegistrationOptions extends - TextDocumentRegistrationOptions, FoldingRangeOptions, - StaticRegistrationOptions { -} -``` - -_Request_: - -* method: `textDocument/foldingRange` -* params: `FoldingRangeParams` defined as follows - -
- -```typescript -export interface FoldingRangeParams extends WorkDoneProgressParams, - PartialResultParams { - /** - * The text document. - */ - textDocument: TextDocumentIdentifier; -} -``` - -_Response_: -* result: `FoldingRange[] | null` defined as follows: - -
- -```typescript -/** - * Enum of known range kinds - */ -export enum FoldingRangeKind { - /** - * Folding range for a comment - */ - Comment = 'comment', - /** - * Folding range for a imports or includes - */ - Imports = 'imports', - /** - * Folding range for a region (e.g. `#region`) - */ - Region = 'region' -} -``` - -
- -```typescript -/** - * Represents a folding range. To be valid, start and end line must be bigger - * than zero and smaller than the number of lines in the document. Clients - * are free to ignore invalid ranges. - */ -export interface FoldingRange { - - /** - * The zero-based start line of the range to fold. The folded area starts - * after the line's last character. To be valid, the end must be zero or - * larger and smaller than the number of lines in the document. - */ - startLine: uinteger; - - /** - * The zero-based character offset from where the folded range starts. If - * not defined, defaults to the length of the start line. - */ - startCharacter?: uinteger; - - /** - * The zero-based end line of the range to fold. The folded area ends with - * the line's last character. To be valid, the end must be zero or larger - * and smaller than the number of lines in the document. - */ - endLine: uinteger; - - /** - * The zero-based character offset before the folded range ends. If not - * defined, defaults to the length of the end line. - */ - endCharacter?: uinteger; - - /** - * Describes the kind of the folding range such as `comment` or `region`. - * The kind is used to categorize folding ranges and used by commands like - * 'Fold all comments'. See [FoldingRangeKind](#FoldingRangeKind) for an - * enumeration of standardized kinds. - */ - kind?: string; -} -``` - -* partial result: `FoldingRange[]` -* error: code and message set in case an exception happens during the 'textDocument/foldingRange' request - -#### Selection Range Request (:leftwards_arrow_with_hook:) - -> *Since version 3.15.0* - -The selection range request is sent from the client to the server to return suggested selection ranges at an array of given positions. A selection range is a range around the cursor position which the user might be interested in selecting. - -A selection range in the return array is for the position in the provided parameters at the same index. Therefore positions[i] must be contained in result[i].range. To allow for results where some positions have selection ranges and others do not, result[i].range is allowed to be the empty range at positions[i]. - -Typically, but not necessary, selection ranges correspond to the nodes of the syntax tree. - -_Client Capability_: -* property name (optional): `textDocument.selectionRange` -* property type: `SelectionRangeClientCapabilities` defined as follows: - -
- -```typescript -export interface SelectionRangeClientCapabilities { - /** - * Whether implementation supports dynamic registration for selection range - * providers. If this is set to `true` the client supports the new - * `SelectionRangeRegistrationOptions` return value for the corresponding - * server capability as well. - */ - dynamicRegistration?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `selectionRangeProvider` -* property type: `boolean | SelectionRangeOptions | SelectionRangeRegistrationOptions` where `SelectionRangeOptions` is defined as follows: - -
- -```typescript -export interface SelectionRangeOptions extends WorkDoneProgressOptions { -} -``` - -_Registration Options_: `SelectionRangeRegistrationOptions` defined as follows: - -
- -```typescript -export interface SelectionRangeRegistrationOptions extends - SelectionRangeOptions, TextDocumentRegistrationOptions, - StaticRegistrationOptions { -} -``` - -_Request_: - -* method: `textDocument/selectionRange` -* params: `SelectionRangeParams` defined as follows: - -
- -```typescript -export interface SelectionRangeParams extends WorkDoneProgressParams, - PartialResultParams { - /** - * The text document. - */ - textDocument: TextDocumentIdentifier; - - /** - * The positions inside the text document. - */ - positions: Position[]; -} -``` - -_Response_: - -* result: `SelectionRange[] | null` defined as follows: - -
- -```typescript -export interface SelectionRange { - /** - * The [range](#Range) of this selection range. - */ - range: Range; - /** - * The parent selection range containing this range. Therefore - * `parent.range` must contain `this.range`. - */ - parent?: SelectionRange; -} -``` - -* partial result: `SelectionRange[]` -* error: code and message set in case an exception happens during the 'textDocument/selectionRange' request - -#### Prepare Call Hierarchy Request (:leftwards_arrow_with_hook:) - -> *Since version 3.16.0* - -The call hierarchy request is sent from the client to the server to return a call hierarchy for the language element of given text document positions. The call hierarchy requests are executed in two steps: - - 1. first a call hierarchy item is resolved for the given text document position - 1. for a call hierarchy item the incoming or outgoing call hierarchy items are resolved. - -_Client Capability_: - -* property name (optional): `textDocument.callHierarchy` -* property type: `CallHierarchyClientCapabilities` defined as follows: - -
- -```typescript -interface CallHierarchyClientCapabilities { - /** - * Whether implementation supports dynamic registration. If this is set to - * `true` the client supports the new `(TextDocumentRegistrationOptions & - * StaticRegistrationOptions)` return value for the corresponding server - * capability as well. - */ - dynamicRegistration?: boolean; -} -``` - -_Server Capability_: - -* property name (optional): `callHierarchyProvider` -* property type: `boolean | CallHierarchyOptions | CallHierarchyRegistrationOptions` where `CallHierarchyOptions` is defined as follows: - -
- -```typescript -export interface CallHierarchyOptions extends WorkDoneProgressOptions { -} -``` - -_Registration Options_: `CallHierarchyRegistrationOptions` defined as follows: - -
- -```typescript -export interface CallHierarchyRegistrationOptions extends - TextDocumentRegistrationOptions, CallHierarchyOptions, - StaticRegistrationOptions { -} -``` - -_Request_: - -* method: `textDocument/prepareCallHierarchy` -* params: `CallHierarchyPrepareParams` defined as follows: - -
- -```typescript -export interface CallHierarchyPrepareParams extends TextDocumentPositionParams, - WorkDoneProgressParams { -} -``` - -_Response_: - -* result: `CallHierarchyItem[] | null` defined as follows: - -
- -```typescript -export interface CallHierarchyItem { - /** - * The name of this item. - */ - name: string; - - /** - * The kind of this item. - */ - kind: SymbolKind; - - /** - * Tags for this item. - */ - tags?: SymbolTag[]; - - /** - * More detail for this item, e.g. the signature of a function. - */ - detail?: string; - - /** - * The resource identifier of this item. - */ - uri: DocumentUri; - - /** - * The range enclosing this symbol not including leading/trailing whitespace - * but everything else, e.g. comments and code. - */ - range: Range; - - /** - * The range that should be selected and revealed when this symbol is being - * picked, e.g. the name of a function. Must be contained by the - * [`range`](#CallHierarchyItem.range). - */ - selectionRange: Range; - - /** - * A data entry field that is preserved between a call hierarchy prepare and - * incoming calls or outgoing calls requests. - */ - data?: unknown; -} -``` - -* error: code and message set in case an exception happens during the 'textDocument/prepareCallHierarchy' request - -#### Call Hierarchy Incoming Calls (:leftwards_arrow_with_hook:) - -> *Since version 3.16.0* - -The request is sent from the client to the server to resolve incoming calls for a given call hierarchy item. The request doesn't define its own client and server capabilities. It is only issued if a server registers for the [`textDocument/prepareCallHierarchy` request](#textDocument_prepareCallHierarchy). - -_Request_: - -* method: `callHierarchy/incomingCalls` -* params: `CallHierarchyIncomingCallsParams` defined as follows: - -
- -```typescript -export interface CallHierarchyIncomingCallsParams extends - WorkDoneProgressParams, PartialResultParams { - item: CallHierarchyItem; -} -``` - -_Response_: - -* result: `CallHierarchyIncomingCall[] | null` defined as follows: - -
- -```typescript -export interface CallHierarchyIncomingCall { - - /** - * The item that makes the call. - */ - from: CallHierarchyItem; - - /** - * The ranges at which the calls appear. This is relative to the caller - * denoted by [`this.from`](#CallHierarchyIncomingCall.from). - */ - fromRanges: Range[]; -} -``` - -* partial result: `CallHierarchyIncomingCall[]` -* error: code and message set in case an exception happens during the 'callHierarchy/incomingCalls' request - -#### Call Hierarchy Outgoing Calls (:leftwards_arrow_with_hook:) - -> *Since version 3.16.0* - -The request is sent from the client to the server to resolve outgoing calls for a given call hierarchy item. The request doesn't define its own client and server capabilities. It is only issued if a server registers for the [`textDocument/prepareCallHierarchy` request](#textDocument_prepareCallHierarchy). - -_Request_: - -* method: `callHierarchy/outgoingCalls` -* params: `CallHierarchyOutgoingCallsParams` defined as follows: - -
- -```typescript -export interface CallHierarchyOutgoingCallsParams extends - WorkDoneProgressParams, PartialResultParams { - item: CallHierarchyItem; -} -``` - -_Response_: - -* result: `CallHierarchyOutgoingCall[] | null` defined as follows: - -
- -```typescript -export interface CallHierarchyOutgoingCall { - - /** - * The item that is called. - */ - to: CallHierarchyItem; - - /** - * The range at which this item is called. This is the range relative to - * the caller, e.g the item passed to `callHierarchy/outgoingCalls` request. - */ - fromRanges: Range[]; -} -``` - -* partial result: `CallHierarchyOutgoingCall[]` -* error: code and message set in case an exception happens during the 'callHierarchy/outgoingCalls' request - -#### Semantic Tokens (:leftwards_arrow_with_hook:) - -> *Since version 3.16.0* - -The request is sent from the client to the server to resolve semantic tokens for a given file. Semantic tokens are used to add additional color information to a file that depends on language specific symbol information. A semantic token request usually produces a large result. The protocol therefore supports encoding tokens with numbers. In addition optional support for deltas is available. - -_General Concepts_ - -Tokens are represented using one token type combined with n token modifiers. A token type is something like `class` or `function` and token modifiers are like `static` or `async`. The protocol defines a set of token types and modifiers but clients are allowed to extend these and announce the values they support in the corresponding client capability. The predefined values are: - -
- -```typescript -export enum SemanticTokenTypes { - namespace = 'namespace', - /** - * Represents a generic type. Acts as a fallback for types which - * can't be mapped to a specific type like class or enum. - */ - type = 'type', - class = 'class', - enum = 'enum', - interface = 'interface', - struct = 'struct', - typeParameter = 'typeParameter', - parameter = 'parameter', - variable = 'variable', - property = 'property', - enumMember = 'enumMember', - event = 'event', - function = 'function', - method = 'method', - macro = 'macro', - keyword = 'keyword', - modifier = 'modifier', - comment = 'comment', - string = 'string', - number = 'number', - regexp = 'regexp', - operator = 'operator' -} -``` - -
- -```typescript -export enum SemanticTokenModifiers { - declaration = 'declaration', - definition = 'definition', - readonly = 'readonly', - static = 'static', - deprecated = 'deprecated', - abstract = 'abstract', - async = 'async', - modification = 'modification', - documentation = 'documentation', - defaultLibrary = 'defaultLibrary' -} -``` - -The protocol defines an additional token format capability to allow future extensions of the format. The only format that is currently specified is `relative` expressing that the tokens are described using relative positions (see Integer Encoding for Tokens below). - -
- -```typescript -export namespace TokenFormat { - export const Relative: 'relative' = 'relative'; -} - -export type TokenFormat = 'relative'; -``` - -_Integer Encoding for Tokens_ - -On the capability level types and modifiers are defined using strings. However the real encoding happens using numbers. The server therefore needs to let the client know which numbers it is using for which types and modifiers. They do so using a legend, which is defined as follows: - -
- -```typescript -export interface SemanticTokensLegend { - /** - * The token types a server uses. - */ - tokenTypes: string[]; - - /** - * The token modifiers a server uses. - */ - tokenModifiers: string[]; -} -``` - -Token types are looked up by index, so a `tokenType` value of `1` means `tokenTypes[1]`. Since a token type can have n modifiers, multiple token modifiers can be set by using bit flags, -so a `tokenModifier` value of `3` is first viewed as binary `0b00000011`, which means `[tokenModifiers[0], tokenModifiers[1]]` because bits 0 and 1 are set. - -There are different ways how the position of a token can be expressed in a file. Absolute positions or relative positions. The protocol for the token format `relative` uses relative positions, because most tokens remain stable relative to each other when edits are made in a file. This simplifies the computation of a delta if a server supports it. So each token is represented using 5 integers. A specific token `i` in the file consists of the following array indices: - -- at index `5*i` - `deltaLine`: token line number, relative to the previous token -- at index `5*i+1` - `deltaStart`: token start character, relative to the previous token (relative to 0 or the previous token's start if they are on the same line) -- at index `5*i+2` - `length`: the length of the token. -- at index `5*i+3` - `tokenType`: will be looked up in `SemanticTokensLegend.tokenTypes`. We currently ask that `tokenType` < 65536. -- at index `5*i+4` - `tokenModifiers`: each set bit will be looked up in `SemanticTokensLegend.tokenModifiers` - -Whether a token can span multiple lines is defined by the client capability `multilineTokenSupport`. If multiline tokens are not supported and a tokens length takes it past the end of the line, it should be treated as if the token ends at the end of the line and will not wrap onto the next line. - -The client capability `overlappingTokenSupport` defines whether tokens can overlap each other. - -Lets look at a concrete example which uses single line tokens without overlaps for encoding a file with 3 tokens in a number array. We start with absolute positions to demonstrate how they can easily be transformed into relative positions: - -```typescript -{ line: 2, startChar: 5, length: 3, tokenType: "property", - tokenModifiers: ["private", "static"] -}, -{ line: 2, startChar: 10, length: 4, tokenType: "type", tokenModifiers: [] }, -{ line: 5, startChar: 2, length: 7, tokenType: "class", tokenModifiers: [] } -``` - -First of all, a legend must be devised. This legend must be provided up-front on registration and capture all possible token types and modifiers. For the example we use this legend: - -```typescript -{ - tokenTypes: ['property', 'type', 'class'], - tokenModifiers: ['private', 'static'] -} -``` - -The first transformation step is to encode `tokenType` and `tokenModifiers` as integers using the legend. As said, token types are looked up by index, so a `tokenType` value of `1` means `tokenTypes[1]`. Multiple token modifiers can be set by using bit flags, so a `tokenModifier` value of `3` is first viewed as binary `0b00000011`, which means `[tokenModifiers[0], tokenModifiers[1]]` because bits 0 and 1 are set. Using this legend, the tokens now are: - -```typescript -{ line: 2, startChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 }, -{ line: 2, startChar: 10, length: 4, tokenType: 1, tokenModifiers: 0 }, -{ line: 5, startChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 } -``` - -The next step is to represent each token relative to the previous token in the file. In this case, the second token is on the same line as the first token, so the `startChar` of the second token is made relative to the `startChar` of the first token, so it will be `10 - 5`. The third token is on a different line than the second token, so the `startChar` of the third token will not be altered: - -```typescript -{ deltaLine: 2, deltaStartChar: 5, length: 3, tokenType: 0, tokenModifiers: 3 }, -{ deltaLine: 0, deltaStartChar: 5, length: 4, tokenType: 1, tokenModifiers: 0 }, -{ deltaLine: 3, deltaStartChar: 2, length: 7, tokenType: 2, tokenModifiers: 0 } -``` - -Finally, the last step is to inline each of the 5 fields for a token in a single array, which is a memory friendly representation: - -```typescript -// 1st token, 2nd token, 3rd token -[ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] -``` - -Now assume that the user types a new empty line at the beginning of the file which results in the following tokens in the file: - -```typescript -{ line: 3, startChar: 5, length: 3, tokenType: "property", - tokenModifiers: ["private", "static"] -}, -{ line: 3, startChar: 10, length: 4, tokenType: "type", tokenModifiers: [] }, -{ line: 6, startChar: 2, length: 7, tokenType: "class", tokenModifiers: [] } -``` - -Running the same transformations as above will result in the following number array: - -```typescript -// 1st token, 2nd token, 3rd token -[ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0] -``` - -The delta is now expressed on these number arrays without any form of interpretation what these numbers mean. This is comparable to the text document edits send from the server to the client to modify the content of a file. Those are character based and don't make any assumption about the meaning of the characters. So `[ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ]` can be transformed into `[ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0]` using the following edit description: `{ start: 0, deleteCount: 1, data: [3] }` which tells the client to simply replace the first number (e.g. `2`) in the array with `3`. - -Semantic token edits behave conceptually like [text edits](#textEditArray) on documents: if an edit description consists of n edits all n edits are based on the same state Sm of the number array. They will move the number array from state Sm to Sm+1. A client applying the edits must not assume that they are sorted. An easy algorithm to apply them to the number array is to sort the edits and apply them from the back to the front of the number array. - -_Client Capability_: - -The following client capabilities are defined for semantic token requests sent from the client to the server: - -* property name (optional): `textDocument.semanticTokens` -* property type: `SemanticTokensClientCapabilities` defined as follows: - -
- -```typescript -interface SemanticTokensClientCapabilities { - /** - * Whether implementation supports dynamic registration. If this is set to - * `true` the client supports the new `(TextDocumentRegistrationOptions & - * StaticRegistrationOptions)` return value for the corresponding server - * capability as well. - */ - dynamicRegistration?: boolean; - - /** - * Which requests the client supports and might send to the server - * depending on the server's capability. Please note that clients might not - * show semantic tokens or degrade some of the user experience if a range - * or full request is advertised by the client but not provided by the - * server. If for example the client capability `requests.full` and - * `request.range` are both set to true but the server only provides a - * range provider the client might not render a minimap correctly or might - * even decide to not show any semantic tokens at all. - */ - requests: { - /** - * The client will send the `textDocument/semanticTokens/range` request - * if the server provides a corresponding handler. - */ - range?: boolean | { - }; - - /** - * The client will send the `textDocument/semanticTokens/full` request - * if the server provides a corresponding handler. - */ - full?: boolean | { - /** - * The client will send the `textDocument/semanticTokens/full/delta` - * request if the server provides a corresponding handler. - */ - delta?: boolean; - }; - }; - - /** - * The token types that the client supports. - */ - tokenTypes: string[]; - - /** - * The token modifiers that the client supports. - */ - tokenModifiers: string[]; - - /** - * The formats the clients supports. - */ - formats: TokenFormat[]; - - /** - * Whether the client supports tokens that can overlap each other. - */ - overlappingTokenSupport?: boolean; - - /** - * Whether the client supports tokens that can span multiple lines. - */ - multilineTokenSupport?: boolean; - - /** - * Whether the client allows the server to actively cancel a - * semantic token request, e.g. supports returning - * ErrorCodes.ServerCancelled. If a server does the client - * needs to retrigger the request. - * - * @since 3.17.0 - */ - serverCancelSupport?: boolean; - - /** - * Whether the client uses semantic tokens to augment existing - * syntax tokens. If set to `true` client side created syntax - * tokens and semantic tokens are both used for colorization. If - * set to `false` the client only uses the returned semantic tokens - * for colorization. - * - * If the value is `undefined` then the client behavior is not - * specified. - * - * @since 3.17.0 - */ - augmentsSyntaxTokens?: boolean; -} -``` - -_Server Capability_: - -The following server capabilities are defined for semantic tokens: - -* property name (optional): `semanticTokensProvider` -* property type: `SemanticTokensOptions | SemanticTokensRegistrationOptions` where `SemanticTokensOptions` is defined as follows: - -
- -```typescript -export interface SemanticTokensOptions extends WorkDoneProgressOptions { - /** - * The legend used by the server - */ - legend: SemanticTokensLegend; - - /** - * Server supports providing semantic tokens for a specific range - * of a document. - */ - range?: boolean | { - }; - - /** - * Server supports providing semantic tokens for a full document. - */ - full?: boolean | { - /** - * The server supports deltas for full documents. - */ - delta?: boolean; - }; -} -``` - -_Registration Options_: `SemanticTokensRegistrationOptions` defined as follows: - -
- -```typescript -export interface SemanticTokensRegistrationOptions extends - TextDocumentRegistrationOptions, SemanticTokensOptions, - StaticRegistrationOptions { -} -``` - -Since the registration option handles range, full and delta requests the method used to register for semantic tokens requests is `textDocument/semanticTokens` and not one of the specific methods described below. - -**Requesting semantic tokens for a whole file** - -_Request_: - -
- -* method: `textDocument/semanticTokens/full` -* params: `SemanticTokensParams` defined as follows: - -
- -```typescript -export interface SemanticTokensParams extends WorkDoneProgressParams, - PartialResultParams { - /** - * The text document. - */ - textDocument: TextDocumentIdentifier; -} -``` - -_Response_: - -* result: `SemanticTokens | null` where `SemanticTokens` is defined as follows: - -
- -```typescript -export interface SemanticTokens { - /** - * An optional result id. If provided and clients support delta updating - * the client will include the result id in the next semantic token request. - * A server can then instead of computing all semantic tokens again simply - * send a delta. - */ - resultId?: string; - - /** - * The actual tokens. - */ - data: uinteger[]; -} -``` - -* partial result: `SemanticTokensPartialResult` defines as follows: - -
- -```typescript -export interface SemanticTokensPartialResult { - data: uinteger[]; -} -``` - -* error: code and message set in case an exception happens during the 'textDocument/semanticTokens/full' request - -**Requesting semantic token delta for a whole file** - -_Request_: - -
- -* method: `textDocument/semanticTokens/full/delta` -* params: `SemanticTokensDeltaParams` defined as follows: - -
- -```typescript -export interface SemanticTokensDeltaParams extends WorkDoneProgressParams, - PartialResultParams { - /** - * The text document. - */ - textDocument: TextDocumentIdentifier; - - /** - * The result id of a previous response. The result Id can either point to - * a full response or a delta response depending on what was received last. - */ - previousResultId: string; -} -``` - -_Response_: - -* result: `SemanticTokens | SemanticTokensDelta | null` where `SemanticTokensDelta` is defined as follows: - -
- -```typescript -export interface SemanticTokensDelta { - readonly resultId?: string; - /** - * The semantic token edits to transform a previous result into a new - * result. - */ - edits: SemanticTokensEdit[]; -} -``` - -
- -```typescript -export interface SemanticTokensEdit { - /** - * The start offset of the edit. - */ - start: uinteger; - - /** - * The count of elements to remove. - */ - deleteCount: uinteger; - - /** - * The elements to insert. - */ - data?: uinteger[]; -} -``` - -* partial result: `SemanticTokensDeltaPartialResult` defines as follows: - -
- -```typescript -export interface SemanticTokensDeltaPartialResult { - edits: SemanticTokensEdit[]; -} -``` - -* error: code and message set in case an exception happens during the 'textDocument/semanticTokens/full/delta' request - -**Requesting semantic tokens for a range** - -There are two uses cases where it can be beneficial to only compute semantic tokens for a visible range: - -- for faster rendering of the tokens in the user interface when a user opens a file. In this use cases servers should also implement the `textDocument/semanticTokens/full` request as well to allow for flicker free scrolling and semantic coloring of a minimap. -- if computing semantic tokens for a full document is too expensive servers can only provide a range call. In this case the client might not render a minimap correctly or might even decide to not show any semantic tokens at all. - -_Request_: - -
- -* method: `textDocument/semanticTokens/range` -* params: `SemanticTokensRangeParams` defined as follows: - -
- -```typescript -export interface SemanticTokensRangeParams extends WorkDoneProgressParams, - PartialResultParams { - /** - * The text document. - */ - textDocument: TextDocumentIdentifier; - - /** - * The range the semantic tokens are requested for. - */ - range: Range; -} -``` - -_Response_: - -* result: `SemanticTokens | null` -* partial result: `SemanticTokensPartialResult` -* error: code and message set in case an exception happens during the 'textDocument/semanticTokens/range' request - -**Requesting a refresh of all semantic tokens** - -The `workspace/semanticTokens/refresh` request is sent from the server to the client. Servers can use it to ask clients to refresh the editors for which this server provides semantic tokens. As a result the client should ask the server to recompute the semantic tokens for these editors. This is useful if a server detects a project wide configuration change which requires a re-calculation of all semantic tokens. Note that the client still has the freedom to delay the re-calculation of the semantic tokens if for example an editor is currently not visible. - -_Client Capability_: - -* property name (optional): `workspace.semanticTokens` -* property type: `SemanticTokensWorkspaceClientCapabilities` defined as follows: - -
- -```typescript -export interface SemanticTokensWorkspaceClientCapabilities { - /** - * Whether the client implementation supports a refresh request sent from - * the server to the client. - * - * Note that this event is global and will force the client to refresh all - * semantic tokens currently shown. It should be used with absolute care - * and is useful for situation where a server for example detect a project - * wide change that requires such a calculation. - */ - refreshSupport?: boolean; -} -``` - -_Request_: - -
- -* method: `workspace/semanticTokens/refresh` -* params: none - -_Response_: - -* result: void -* error: code and message set in case an exception happens during the 'workspace/semanticTokens/refresh' request - -#### Linked Editing Range(:leftwards_arrow_with_hook:) - -> *Since version 3.16.0* - -The linked editing request is sent from the client to the server to return for a given position in a document the range of the symbol at the position and all ranges that have the same content. Optionally a word pattern can be returned to describe valid contents. A rename to one of the ranges can be applied to all other ranges if the new content is valid. If no result-specific word pattern is provided, the word pattern from the client's language configuration is used. - -_Client Capabilities_: - -* property name (optional): `textDocument.linkedEditingRange` -* property type: `LinkedEditingRangeClientCapabilities` defined as follows: - -
- -```typescript -export interface LinkedEditingRangeClientCapabilities { - /** - * Whether implementation supports dynamic registration. - * If this is set to `true` the client supports the new - * `(TextDocumentRegistrationOptions & StaticRegistrationOptions)` - * return value for the corresponding server capability as well. - */ - dynamicRegistration?: boolean; -} -``` - -_Server Capability_: - -* property name (optional): `linkedEditingRangeProvider` -* property type: `boolean` \| `LinkedEditingRangeOptions` \| `LinkedEditingRangeRegistrationOptions` defined as follows: - -
- -```typescript -export interface LinkedEditingRangeOptions extends WorkDoneProgressOptions { -} -``` - -_Registration Options_: `LinkedEditingRangeRegistrationOptions` defined as follows: - -
- -```typescript -export interface LinkedEditingRangeRegistrationOptions extends - TextDocumentRegistrationOptions, LinkedEditingRangeOptions, - StaticRegistrationOptions { -} -``` - -_Request_: - -* method: `textDocument/linkedEditingRange` -* params: `LinkedEditingRangeParams` defined as follows: - -
- -```typescript -export interface LinkedEditingRangeParams extends TextDocumentPositionParams, - WorkDoneProgressParams { -} -``` - -_Response_: - -* result: `LinkedEditingRanges` \| `null` defined as follows: - -
- -```typescript -export interface LinkedEditingRanges { - /** - * A list of ranges that can be renamed together. The ranges must have - * identical length and contain identical text content. The ranges cannot overlap. - */ - ranges: Range[]; - - /** - * An optional word pattern (regular expression) that describes valid contents for - * the given ranges. If no pattern is provided, the client configuration's word - * pattern will be used. - */ - wordPattern?: string; -} -``` -* error: code and message set in case an exception happens during the 'textDocument/linkedEditingRange' request - -#### Monikers (:leftwards_arrow_with_hook:) - -> *Since version 3.16.0* - -Language Server Index Format (LSIF) introduced the concept of symbol monikers to help associate symbols across different indexes. This request adds capability for LSP server implementations to provide the same symbol moniker information given a text document position. Clients can utilize this method to get the moniker at the current location in a file user is editing and do further code navigation queries in other services that rely on LSIF indexes and link symbols together. - -The `textDocument/moniker` request is sent from the client to the server to get the symbol monikers for a given text document position. An array of Moniker types is returned as response to indicate possible monikers at the given location. If no monikers can be calculated, an empty array or `null` should be returned. - -_Client Capabilities_: - -* property name (optional): `textDocument.moniker` -* property type: `MonikerClientCapabilities` defined as follows: - -
- -```typescript -interface MonikerClientCapabilities { - /** - * Whether implementation supports dynamic registration. If this is set to - * `true` the client supports the new `(TextDocumentRegistrationOptions & - * StaticRegistrationOptions)` return value for the corresponding server - * capability as well. - */ - dynamicRegistration?: boolean; -} -``` - -_Server Capability_: - -* property name (optional): `monikerProvider` -* property type: `boolean | MonikerOptions | MonikerRegistrationOptions` is defined as follows: - -
- -```typescript -export interface MonikerOptions extends WorkDoneProgressOptions { -} -``` - -_Registration Options_: `MonikerRegistrationOptions` defined as follows: - -
- -```typescript -export interface MonikerRegistrationOptions extends - TextDocumentRegistrationOptions, MonikerOptions { -} -``` - -_Request_: - -* method: `textDocument/moniker` -* params: `MonikerParams` defined as follows: - -
- -```typescript -export interface MonikerParams extends TextDocumentPositionParams, - WorkDoneProgressParams, PartialResultParams { -} -``` - -_Response_: - -* result: `Moniker[] | null` -* partial result: `Moniker[]` -* error: code and message set in case an exception happens during the 'textDocument/moniker' request - -`Moniker` is defined as follows: - -
- -```typescript -/** - * Moniker uniqueness level to define scope of the moniker. - */ -export enum UniquenessLevel { - /** - * The moniker is only unique inside a document - */ - document = 'document', - - /** - * The moniker is unique inside a project for which a dump got created - */ - project = 'project', - - /** - * The moniker is unique inside the group to which a project belongs - */ - group = 'group', - - /** - * The moniker is unique inside the moniker scheme. - */ - scheme = 'scheme', - - /** - * The moniker is globally unique - */ - global = 'global' -} -``` - -
- -```typescript -/** - * The moniker kind. - */ -export enum MonikerKind { - /** - * The moniker represent a symbol that is imported into a project - */ - import = 'import', - - /** - * The moniker represents a symbol that is exported from a project - */ - export = 'export', - - /** - * The moniker represents a symbol that is local to a project (e.g. a local - * variable of a function, a class not visible outside the project, ...) - */ - local = 'local' -} -``` - -
- -```typescript -/** - * Moniker definition to match LSIF 0.5 moniker definition. - */ -export interface Moniker { - /** - * The scheme of the moniker. For example tsc or .Net - */ - scheme: string; - - /** - * The identifier of the moniker. The value is opaque in LSIF however - * schema owners are allowed to define the structure if they want. - */ - identifier: string; - - /** - * The scope in which the moniker is unique - */ - unique: UniquenessLevel; - - /** - * The moniker kind if known. - */ - kind?: MonikerKind; -} -``` - -##### Notes - -Server implementations of this method should ensure that the moniker calculation matches to those used in the corresponding LSIF implementation to ensure symbols can be associated correctly across IDE sessions and LSIF indexes. +{% include_relative language/implementation.md %} +{% include_relative language/references.md %} +{% include_relative language/documentHighlight.md %} +{% include_relative language/documentSymbol.md %} +{% include_relative language/codeAction.md %} +{% include_relative language/codeLens.md %} +{% include_relative language/documentLink.md %} +{% include_relative language/documentColor.md %} +{% include_relative language/colorPresentation.md %} +{% include_relative language/formatting.md %} +{% include_relative language/rangeFormatting.md %} +{% include_relative language/onTypeFormatting.md %} +{% include_relative language/rename.md %} +{% include_relative language/foldingRange.md %} +{% include_relative language/selectionRange.md %} +{% include_relative language/callHierarchy.md %} +{% include_relative language/semanticTokens.md %} +{% include_relative language/linkedEditingRange.md %} +{% include_relative language/moniker.md %} ### Implementation Considerations From 1c961d06e75247f085abd4ab81c2fb8b340ee8d3 Mon Sep 17 00:00:00 2001 From: Dirk Baeumer Date: Mon, 7 Mar 2022 18:13:34 +0100 Subject: [PATCH 2/2] More splitting work --- .../lsp/3.17/client/registerCapability.md | 73 + .../lsp/3.17/client/unregisterCapability.md | 59 + _specifications/lsp/3.17/general/exit.md | 8 + .../lsp/3.17/general/initialize.md | 768 +++ .../lsp/3.17/general/initialized.md | 12 + _specifications/lsp/3.17/general/logTrace.md | 27 + _specifications/lsp/3.17/general/setTrace.md | 16 + _specifications/lsp/3.17/general/shutdown.md | 13 + .../lsp/3.17/language/completion.md | 824 ++++ .../lsp/3.17/language/declaration.md | 67 + .../lsp/3.17/language/definition.md | 65 + _specifications/lsp/3.17/language/hover.md | 107 + .../lsp/3.17/language/publishDiagnostics.md | 92 + .../lsp/3.17/language/signatureHelp.md | 300 ++ .../lsp/3.17/language/typeDefinition.md | 70 + _specifications/lsp/3.17/specification.md | 4330 +---------------- _specifications/lsp/3.17/telemetry/event.md | 7 + .../lsp/3.17/textDocument/didChange.md | 93 + .../lsp/3.17/textDocument/didClose.md | 26 + .../lsp/3.17/textDocument/didOpen.md | 28 + .../lsp/3.17/textDocument/didSave.md | 61 + .../lsp/3.17/textDocument/willSave.md | 68 + .../3.17/textDocument/willSaveWaitUntil.md | 25 + _specifications/lsp/3.17/window/logMessage.md | 23 + .../lsp/3.17/window/showDocument.md | 88 + .../lsp/3.17/window/showMessage.md | 48 + .../lsp/3.17/window/showMessageRequest.md | 68 + .../lsp/3.17/window/workDoneProgressCancel.md | 16 + .../lsp/3.17/window/workDoneProgressCreate.md | 22 + .../lsp/3.17/workspace/applyEdit.md | 61 + .../lsp/3.17/workspace/configuration.md | 43 + .../3.17/workspace/didChangeConfiguration.md | 33 + .../3.17/workspace/didChangeWatchedFiles.md | 151 + .../workspace/didChangeWorkspaceFolders.md | 45 + .../lsp/3.17/workspace/didCreateFiles.md | 19 + .../lsp/3.17/workspace/didDeleteFiles.md | 19 + .../lsp/3.17/workspace/didRenameFiles.md | 19 + .../lsp/3.17/workspace/executeCommand.md | 72 + _specifications/lsp/3.17/workspace/symbol.md | 168 + .../lsp/3.17/workspace/willCreateFiles.md | 179 + .../lsp/3.17/workspace/willDeleteFiles.md | 60 + .../lsp/3.17/workspace/willRenameFiles.md | 66 + .../lsp/3.17/workspace/workspaceFolders.md | 62 + 43 files changed, 4203 insertions(+), 4198 deletions(-) create mode 100644 _specifications/lsp/3.17/client/registerCapability.md create mode 100644 _specifications/lsp/3.17/client/unregisterCapability.md create mode 100644 _specifications/lsp/3.17/general/exit.md create mode 100644 _specifications/lsp/3.17/general/initialize.md create mode 100644 _specifications/lsp/3.17/general/initialized.md create mode 100644 _specifications/lsp/3.17/general/logTrace.md create mode 100644 _specifications/lsp/3.17/general/setTrace.md create mode 100644 _specifications/lsp/3.17/general/shutdown.md create mode 100644 _specifications/lsp/3.17/language/completion.md create mode 100644 _specifications/lsp/3.17/language/declaration.md create mode 100644 _specifications/lsp/3.17/language/definition.md create mode 100644 _specifications/lsp/3.17/language/hover.md create mode 100644 _specifications/lsp/3.17/language/publishDiagnostics.md create mode 100644 _specifications/lsp/3.17/language/signatureHelp.md create mode 100644 _specifications/lsp/3.17/language/typeDefinition.md create mode 100644 _specifications/lsp/3.17/telemetry/event.md create mode 100644 _specifications/lsp/3.17/textDocument/didChange.md create mode 100644 _specifications/lsp/3.17/textDocument/didClose.md create mode 100644 _specifications/lsp/3.17/textDocument/didOpen.md create mode 100644 _specifications/lsp/3.17/textDocument/didSave.md create mode 100644 _specifications/lsp/3.17/textDocument/willSave.md create mode 100644 _specifications/lsp/3.17/textDocument/willSaveWaitUntil.md create mode 100644 _specifications/lsp/3.17/window/logMessage.md create mode 100644 _specifications/lsp/3.17/window/showDocument.md create mode 100644 _specifications/lsp/3.17/window/showMessage.md create mode 100644 _specifications/lsp/3.17/window/showMessageRequest.md create mode 100644 _specifications/lsp/3.17/window/workDoneProgressCancel.md create mode 100644 _specifications/lsp/3.17/window/workDoneProgressCreate.md create mode 100644 _specifications/lsp/3.17/workspace/applyEdit.md create mode 100644 _specifications/lsp/3.17/workspace/configuration.md create mode 100644 _specifications/lsp/3.17/workspace/didChangeConfiguration.md create mode 100644 _specifications/lsp/3.17/workspace/didChangeWatchedFiles.md create mode 100644 _specifications/lsp/3.17/workspace/didChangeWorkspaceFolders.md create mode 100644 _specifications/lsp/3.17/workspace/didCreateFiles.md create mode 100644 _specifications/lsp/3.17/workspace/didDeleteFiles.md create mode 100644 _specifications/lsp/3.17/workspace/didRenameFiles.md create mode 100644 _specifications/lsp/3.17/workspace/executeCommand.md create mode 100644 _specifications/lsp/3.17/workspace/symbol.md create mode 100644 _specifications/lsp/3.17/workspace/willCreateFiles.md create mode 100644 _specifications/lsp/3.17/workspace/willDeleteFiles.md create mode 100644 _specifications/lsp/3.17/workspace/willRenameFiles.md create mode 100644 _specifications/lsp/3.17/workspace/workspaceFolders.md diff --git a/_specifications/lsp/3.17/client/registerCapability.md b/_specifications/lsp/3.17/client/registerCapability.md new file mode 100644 index 000000000..d431a3d5a --- /dev/null +++ b/_specifications/lsp/3.17/client/registerCapability.md @@ -0,0 +1,73 @@ +#### Register Capability (:arrow_right_hook:) + +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 `dynamicRegistration` property on the specific client capabilities. A client can even provide dynamic registration for capability A but not for capability B (see `TextDocumentClientCapabilities` as an example). + +Server must not register the same capability both statically through the initialize result and dynamically for the same document selector. If a server wants to support both static and dynamic registration it needs to check the client capability in the initialize request and only register the capability statically if the client doesn't support dynamic registration for that capability. + +_Request_: +* method: 'client/registerCapability' +* params: `RegistrationParams` + +Where `RegistrationParams` are defined as follows: + +
+ +```typescript +/** + * General parameters to register for a capability. + */ +export interface Registration { + /** + * The id used to register the request. The id can be used to deregister + * the request again. + */ + id: string; + + /** + * The method / capability to register for. + */ + method: string; + + /** + * Options necessary for the registration. + */ + registerOptions?: LSPAny; +} +``` + +
+ +```typescript +export interface RegistrationParams { + registrations: Registration[]; +} +``` + +Since most of the registration options require to specify a document selector there is a base interface that can be used. See `TextDocumentRegistrationOptions`. + +An example JSON RPC message to register dynamically for the `textDocument/willSaveWaitUntil` feature on the client side is as follows (only details shown): + +```json +{ + "method": "client/registerCapability", + "params": { + "registrations": [ + { + "id": "79eee87c-c409-4664-8102-e03263673f6f", + "method": "textDocument/willSaveWaitUntil", + "registerOptions": { + "documentSelector": [ + { "language": "javascript" } + ] + } + } + ] + } +} +``` + +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. + +_Response_: +* result: void. +* error: code and message set in case an exception happens during the request. diff --git a/_specifications/lsp/3.17/client/unregisterCapability.md b/_specifications/lsp/3.17/client/unregisterCapability.md new file mode 100644 index 000000000..7e0576fcb --- /dev/null +++ b/_specifications/lsp/3.17/client/unregisterCapability.md @@ -0,0 +1,59 @@ +#### Unregister Capability (:arrow_right_hook:) + +The `client/unregisterCapability` request is sent from the server to the client to unregister a previously registered capability. + +_Request_: +* method: 'client/unregisterCapability' +* params: `UnregistrationParams` + +Where `UnregistrationParams` are defined as follows: + +
+ +```typescript +/** + * General parameters to unregister a capability. + */ +export interface Unregistration { + /** + * The id used to unregister the request or notification. Usually an id + * provided during the register request. + */ + id: string; + + /** + * The method / capability to unregister for. + */ + method: string; +} +``` + +
+ +```typescript +export interface UnregistrationParams { + // This should correctly be named `unregistrations`. However changing this + // is a breaking change and needs to wait until we deliver a 4.x version + // of the specification. + unregisterations: Unregistration[]; +} +``` + +An example JSON RPC message to unregister the above registered `textDocument/willSaveWaitUntil` feature looks like this: + +```json +{ + "method": "client/unregisterCapability", + "params": { + "unregisterations": [ + { + "id": "79eee87c-c409-4664-8102-e03263673f6f", + "method": "textDocument/willSaveWaitUntil" + } + ] + } +} +``` +_Response_: +* result: void. +* error: code and message set in case an exception happens during the request. diff --git a/_specifications/lsp/3.17/general/exit.md b/_specifications/lsp/3.17/general/exit.md new file mode 100644 index 000000000..e696e4a9a --- /dev/null +++ b/_specifications/lsp/3.17/general/exit.md @@ -0,0 +1,8 @@ +#### Exit Notification (:arrow_right:) + +A notification to ask the server to exit its process. +The server should exit with `success` code 0 if the shutdown request has been received before; otherwise with `error` code 1. + +_Notification_: +* method: 'exit' +* params: void diff --git a/_specifications/lsp/3.17/general/initialize.md b/_specifications/lsp/3.17/general/initialize.md new file mode 100644 index 000000000..6c9f73d5c --- /dev/null +++ b/_specifications/lsp/3.17/general/initialize.md @@ -0,0 +1,768 @@ +##### Initialize Request (:leftwards_arrow_with_hook:) + +The initialize request is sent as the first request from the client to the server. If the server receives a request or notification before the `initialize` request it should act as follows: + +* For a request the response should be an error with `code: -32002`. The message can be picked by the server. +* Notifications should be dropped, except for the exit notification. This will allow the exit of a server without an initialize request. + +Until the server has responded to the `initialize` request with an `InitializeResult`, the client must not send any additional requests or notifications to the server. In addition the server is not allowed to send any requests or notifications to the client until it has responded with an `InitializeResult`, with the exception that during the `initialize` request the server is allowed to send the notifications `window/showMessage`, `window/logMessage` and `telemetry/event` as well as the `window/showMessageRequest` request to the client. In case the client sets up a progress token in the initialize params (e.g. property `workDoneToken`) the server is also allowed to use that token (and only that token) using the `$/progress` notification sent from the server to the client. + +The `initialize` request may only be sent once. + +_Request_: +* method: 'initialize' +* params: `InitializeParams` defined as follows: + +
+ +```typescript +interface InitializeParams extends WorkDoneProgressParams { + /** + * The process Id of the parent process that started the server. Is null if + * the process has not been started by another process. If the parent + * process is not alive then the server should exit (see exit notification) + * its process. + */ + processId: integer | null; + + /** + * Information about the client + * + * @since 3.15.0 + */ + clientInfo?: { + /** + * The name of the client as defined by the client. + */ + name: string; + + /** + * The client's version as defined by the client. + */ + version?: string; + }; + + /** + * The locale the client is currently showing the user interface + * in. This must not necessarily be the locale of the operating + * system. + * + * Uses IETF language tags as the value's syntax + * (See https://en.wikipedia.org/wiki/IETF_language_tag) + * + * @since 3.16.0 + */ + locale?: string; + + /** + * The rootPath of the workspace. Is null + * if no folder is open. + * + * @deprecated in favour of `rootUri`. + */ + rootPath?: string | null; + + /** + * The rootUri of the workspace. Is null if no + * folder is open. If both `rootPath` and `rootUri` are set + * `rootUri` wins. + * + * @deprecated in favour of `workspaceFolders` + */ + rootUri: DocumentUri | null; + + /** + * User provided initialization options. + */ + initializationOptions?: LSPAny; + + /** + * The capabilities provided by the client (editor or tool) + */ + capabilities: ClientCapabilities; + + /** + * The initial trace setting. If omitted trace is disabled ('off'). + */ + trace?: TraceValue; + + /** + * The workspace folders configured in the client when the server starts. + * This property is only available if the client supports workspace folders. + * It can be `null` if the client supports workspace folders but none are + * configured. + * + * @since 3.6.0 + */ + workspaceFolders?: WorkspaceFolder[] | null; +} +``` +Where `ClientCapabilities` and `TextDocumentClientCapabilities` are defined as follows: + + +##### TextDocumentClientCapabilities + +`TextDocumentClientCapabilities` define capabilities the editor / tool provides on text documents. + +
+ +```typescript +/** + * Text document specific client capabilities. + */ +export interface TextDocumentClientCapabilities { + + synchronization?: TextDocumentSyncClientCapabilities; + + /** + * Capabilities specific to the `textDocument/completion` request. + */ + completion?: CompletionClientCapabilities; + + /** + * Capabilities specific to the `textDocument/hover` request. + */ + hover?: HoverClientCapabilities; + + /** + * Capabilities specific to the `textDocument/signatureHelp` request. + */ + signatureHelp?: SignatureHelpClientCapabilities; + + /** + * Capabilities specific to the `textDocument/declaration` request. + * + * @since 3.14.0 + */ + declaration?: DeclarationClientCapabilities; + + /** + * Capabilities specific to the `textDocument/definition` request. + */ + definition?: DefinitionClientCapabilities; + + /** + * Capabilities specific to the `textDocument/typeDefinition` request. + * + * @since 3.6.0 + */ + typeDefinition?: TypeDefinitionClientCapabilities; + + /** + * Capabilities specific to the `textDocument/implementation` request. + * + * @since 3.6.0 + */ + implementation?: ImplementationClientCapabilities; + + /** + * Capabilities specific to the `textDocument/references` request. + */ + references?: ReferenceClientCapabilities; + + /** + * Capabilities specific to the `textDocument/documentHighlight` request. + */ + documentHighlight?: DocumentHighlightClientCapabilities; + + /** + * Capabilities specific to the `textDocument/documentSymbol` request. + */ + documentSymbol?: DocumentSymbolClientCapabilities; + + /** + * Capabilities specific to the `textDocument/codeAction` request. + */ + codeAction?: CodeActionClientCapabilities; + + /** + * Capabilities specific to the `textDocument/codeLens` request. + */ + codeLens?: CodeLensClientCapabilities; + + /** + * Capabilities specific to the `textDocument/documentLink` request. + */ + documentLink?: DocumentLinkClientCapabilities; + + /** + * Capabilities specific to the `textDocument/documentColor` and the + * `textDocument/colorPresentation` request. + * + * @since 3.6.0 + */ + colorProvider?: DocumentColorClientCapabilities; + + /** + * Capabilities specific to the `textDocument/formatting` request. + */ + formatting?: DocumentFormattingClientCapabilities; + + /** + * Capabilities specific to the `textDocument/rangeFormatting` request. + */ + rangeFormatting?: DocumentRangeFormattingClientCapabilities; + + /** request. + * Capabilities specific to the `textDocument/onTypeFormatting` request. + */ + onTypeFormatting?: DocumentOnTypeFormattingClientCapabilities; + + /** + * Capabilities specific to the `textDocument/rename` request. + */ + rename?: RenameClientCapabilities; + + /** + * Capabilities specific to the `textDocument/publishDiagnostics` + * notification. + */ + publishDiagnostics?: PublishDiagnosticsClientCapabilities; + + /** + * Capabilities specific to the `textDocument/foldingRange` request. + * + * @since 3.10.0 + */ + foldingRange?: FoldingRangeClientCapabilities; + + /** + * Capabilities specific to the `textDocument/selectionRange` request. + * + * @since 3.15.0 + */ + selectionRange?: SelectionRangeClientCapabilities; + + /** + * Capabilities specific to the `textDocument/linkedEditingRange` request. + * + * @since 3.16.0 + */ + linkedEditingRange?: LinkedEditingRangeClientCapabilities; + + /** + * Capabilities specific to the various call hierarchy requests. + * + * @since 3.16.0 + */ + callHierarchy?: CallHierarchyClientCapabilities; + + /** + * Capabilities specific to the various semantic token requests. + * + * @since 3.16.0 + */ + semanticTokens?: SemanticTokensClientCapabilities; + + /** + * Capabilities specific to the `textDocument/moniker` request. + * + * @since 3.16.0 + */ + moniker?: MonikerClientCapabilities; +} +``` + +`ClientCapabilities` define capabilities for dynamic registration, workspace and text document features the client supports. The `experimental` can be used to pass experimental 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 missing property normally defines sub properties, all missing sub properties should be interpreted as an absence of the corresponding capability. + +Client capabilities got introduced with 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). + +
+ +```typescript +interface ClientCapabilities { + /** + * Workspace specific client capabilities. + */ + workspace?: { + /** + * The client supports applying batch edits + * to the workspace by supporting the request + * 'workspace/applyEdit' + */ + applyEdit?: boolean; + + /** + * Capabilities specific to `WorkspaceEdit`s + */ + workspaceEdit?: WorkspaceEditClientCapabilities; + + /** + * Capabilities specific to the `workspace/didChangeConfiguration` + * notification. + */ + didChangeConfiguration?: DidChangeConfigurationClientCapabilities; + + /** + * Capabilities specific to the `workspace/didChangeWatchedFiles` + * notification. + */ + didChangeWatchedFiles?: DidChangeWatchedFilesClientCapabilities; + + /** + * Capabilities specific to the `workspace/symbol` request. + */ + symbol?: WorkspaceSymbolClientCapabilities; + + /** + * Capabilities specific to the `workspace/executeCommand` request. + */ + executeCommand?: ExecuteCommandClientCapabilities; + + /** + * The client has support for workspace folders. + * + * @since 3.6.0 + */ + workspaceFolders?: boolean; + + /** + * The client supports `workspace/configuration` requests. + * + * @since 3.6.0 + */ + configuration?: boolean; + + /** + * Capabilities specific to the semantic token requests scoped to the + * workspace. + * + * @since 3.16.0 + */ + semanticTokens?: SemanticTokensWorkspaceClientCapabilities; + + /** + * Capabilities specific to the code lens requests scoped to the + * workspace. + * + * @since 3.16.0 + */ + codeLens?: CodeLensWorkspaceClientCapabilities; + + /** + * The client has support for file requests/notifications. + * + * @since 3.16.0 + */ + fileOperations?: { + /** + * Whether the client supports dynamic registration for file + * requests/notifications. + */ + dynamicRegistration?: boolean; + + /** + * The client has support for sending didCreateFiles notifications. + */ + didCreate?: boolean; + + /** + * The client has support for sending willCreateFiles requests. + */ + willCreate?: boolean; + + /** + * The client has support for sending didRenameFiles notifications. + */ + didRename?: boolean; + + /** + * The client has support for sending willRenameFiles requests. + */ + willRename?: boolean; + + /** + * The client has support for sending didDeleteFiles notifications. + */ + didDelete?: boolean; + + /** + * The client has support for sending willDeleteFiles requests. + */ + willDelete?: boolean; + }; + }; + + /** + * Text document specific client capabilities. + */ + textDocument?: TextDocumentClientCapabilities; + + /** + * Window specific client capabilities. + */ + window?: { + /** + * Whether client supports handling progress notifications. If set + * servers are allowed to report in `workDoneProgress` property in the + * request specific server capabilities. + * + * @since 3.15.0 + */ + workDoneProgress?: boolean; + + /** + * Capabilities specific to the showMessage request + * + * @since 3.16.0 + */ + showMessage?: ShowMessageRequestClientCapabilities; + + /** + * Client capabilities for the show document request. + * + * @since 3.16.0 + */ + showDocument?: ShowDocumentClientCapabilities; + }; + + /** + * General client capabilities. + * + * @since 3.16.0 + */ + general?: { + /** + * Client capability that signals how the client + * handles stale requests (e.g. a request + * for which the client will not process the response + * anymore since the information is outdated). + * + * @since 3.17.0 + */ + staleRequestSupport?: { + /** + * The client will actively cancel the request. + */ + cancel: boolean; + + /** + * The list of requests for which the client + * will retry the request if it receives a + * response with error code `ContentModified`` + */ + retryOnContentModified: string[]; + } + + /** + * Client capabilities specific to regular expressions. + * + * @since 3.16.0 + */ + regularExpressions?: RegularExpressionsClientCapabilities; + + /** + * Client capabilities specific to the client's markdown parser. + * + * @since 3.16.0 + */ + markdown?: MarkdownClientCapabilities; + }; + + /** + * Experimental client capabilities. + */ + experimental?: LSPAny; +} +``` + +_Response_: +* result: `InitializeResult` defined as follows: + +
+ +```typescript +interface InitializeResult { + /** + * The capabilities the language server provides. + */ + capabilities: ServerCapabilities; + + /** + * Information about the server. + * + * @since 3.15.0 + */ + serverInfo?: { + /** + * The name of the server as defined by the server. + */ + name: string; + + /** + * The server's version as defined by the server. + */ + version?: string; + }; +} +``` +* error.code: + +
+ +```typescript +/** + * Known error codes for an `InitializeError`; + */ +export namespace InitializeError { + /** + * If the protocol version provided by the client can't be handled by the + * server. + * + * @deprecated This initialize error got replaced by client capabilities. + * There is no version handshake in version 3.0x + */ + export const unknownProtocolVersion: 1 = 1; +} +``` + +* error.data: + +```typescript +interface InitializeError { + /** + * Indicates whether the client execute the following retry logic: + * (1) show the message provided by the ResponseError to the user + * (2) user selects retry or cancel + * (3) if user selected retry the initialize method is sent again. + */ + retry: boolean; +} +``` + +The server can signal the following capabilities: + +
+ +```typescript +interface ServerCapabilities { + /** + * Defines how text documents are synced. Is either a detailed structure + * defining each notification or for backwards compatibility the + * TextDocumentSyncKind number. If omitted it defaults to + * `TextDocumentSyncKind.None`. + */ + textDocumentSync?: TextDocumentSyncOptions | TextDocumentSyncKind; + + /** + * The server provides completion support. + */ + completionProvider?: CompletionOptions; + + /** + * The server provides hover support. + */ + hoverProvider?: boolean | HoverOptions; + + /** + * The server provides signature help support. + */ + signatureHelpProvider?: SignatureHelpOptions; + + /** + * The server provides go to declaration support. + * + * @since 3.14.0 + */ + declarationProvider?: boolean | DeclarationOptions + | DeclarationRegistrationOptions; + + /** + * The server provides goto definition support. + */ + definitionProvider?: boolean | DefinitionOptions; + + /** + * The server provides goto type definition support. + * + * @since 3.6.0 + */ + typeDefinitionProvider?: boolean | TypeDefinitionOptions + | TypeDefinitionRegistrationOptions; + + /** + * The server provides goto implementation support. + * + * @since 3.6.0 + */ + implementationProvider?: boolean | ImplementationOptions + | ImplementationRegistrationOptions; + + /** + * The server provides find references support. + */ + referencesProvider?: boolean | ReferenceOptions; + + /** + * The server provides document highlight support. + */ + documentHighlightProvider?: boolean | DocumentHighlightOptions; + + /** + * The server provides document symbol support. + */ + documentSymbolProvider?: boolean | DocumentSymbolOptions; + + /** + * The server provides code actions. The `CodeActionOptions` return type is + * only valid if the client signals code action literal support via the + * property `textDocument.codeAction.codeActionLiteralSupport`. + */ + codeActionProvider?: boolean | CodeActionOptions; + + /** + * The server provides code lens. + */ + codeLensProvider?: CodeLensOptions; + + /** + * The server provides document link support. + */ + documentLinkProvider?: DocumentLinkOptions; + + /** + * The server provides color provider support. + * + * @since 3.6.0 + */ + colorProvider?: boolean | DocumentColorOptions + | DocumentColorRegistrationOptions; + + /** + * The server provides document formatting. + */ + documentFormattingProvider?: boolean | DocumentFormattingOptions; + + /** + * The server provides document range formatting. + */ + documentRangeFormattingProvider?: boolean | DocumentRangeFormattingOptions; + + /** + * The server provides document formatting on typing. + */ + documentOnTypeFormattingProvider?: DocumentOnTypeFormattingOptions; + + /** + * The server provides rename support. RenameOptions may only be + * specified if the client states that it supports + * `prepareSupport` in its initial `initialize` request. + */ + renameProvider?: boolean | RenameOptions; + + /** + * The server provides folding provider support. + * + * @since 3.10.0 + */ + foldingRangeProvider?: boolean | FoldingRangeOptions + | FoldingRangeRegistrationOptions; + + /** + * The server provides execute command support. + */ + executeCommandProvider?: ExecuteCommandOptions; + + /** + * The server provides selection range support. + * + * @since 3.15.0 + */ + selectionRangeProvider?: boolean | SelectionRangeOptions + | SelectionRangeRegistrationOptions; + + /** + * The server provides linked editing range support. + * + * @since 3.16.0 + */ + linkedEditingRangeProvider?: boolean | LinkedEditingRangeOptions + | LinkedEditingRangeRegistrationOptions; + + /** + * The server provides call hierarchy support. + * + * @since 3.16.0 + */ + callHierarchyProvider?: boolean | CallHierarchyOptions + | CallHierarchyRegistrationOptions; + + /** + * The server provides semantic tokens support. + * + * @since 3.16.0 + */ + semanticTokensProvider?: SemanticTokensOptions + | SemanticTokensRegistrationOptions; + + /** + * Whether server provides moniker support. + * + * @since 3.16.0 + */ + monikerProvider?: boolean | MonikerOptions | MonikerRegistrationOptions; + + /** + * The server provides workspace symbol support. + */ + workspaceSymbolProvider?: boolean | WorkspaceSymbolOptions; + + /** + * Workspace specific server capabilities + */ + workspace?: { + /** + * The server supports workspace folder. + * + * @since 3.6.0 + */ + workspaceFolders?: WorkspaceFoldersServerCapabilities; + + /** + * The server is interested in file notifications/requests. + * + * @since 3.16.0 + */ + fileOperations?: { + /** + * The server is interested in receiving didCreateFiles + * notifications. + */ + didCreate?: FileOperationRegistrationOptions; + + /** + * The server is interested in receiving willCreateFiles requests. + */ + willCreate?: FileOperationRegistrationOptions; + + /** + * The server is interested in receiving didRenameFiles + * notifications. + */ + didRename?: FileOperationRegistrationOptions; + + /** + * The server is interested in receiving willRenameFiles requests. + */ + willRename?: FileOperationRegistrationOptions; + + /** + * The server is interested in receiving didDeleteFiles file + * notifications. + */ + didDelete?: FileOperationRegistrationOptions; + + /** + * The server is interested in receiving willDeleteFiles file + * requests. + */ + willDelete?: FileOperationRegistrationOptions; + }; + }; + + /** + * Experimental server capabilities. + */ + experimental?: LSPAny; +} +``` \ No newline at end of file diff --git a/_specifications/lsp/3.17/general/initialized.md b/_specifications/lsp/3.17/general/initialized.md new file mode 100644 index 000000000..f6da6e54e --- /dev/null +++ b/_specifications/lsp/3.17/general/initialized.md @@ -0,0 +1,12 @@ +#### Initialized Notification (:arrow_right:) + +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. The `initialized` notification may only be sent once. + +_Notification_: +* method: 'initialized' +* params: `InitializedParams` defined as follows: + +```typescript +interface InitializedParams { +} +``` diff --git a/_specifications/lsp/3.17/general/logTrace.md b/_specifications/lsp/3.17/general/logTrace.md new file mode 100644 index 000000000..6c04a7b76 --- /dev/null +++ b/_specifications/lsp/3.17/general/logTrace.md @@ -0,0 +1,27 @@ +#### LogTrace Notification (:arrow_left:) + +A notification to log the trace of the server's execution. +The amount and content of these notifications depends on the current `trace` configuration. +If `trace` is `'off'`, the server should not send any `logTrace` notification. +If `trace` is `'messages'`, the server should not add the `'verbose'` field in the `LogTraceParams`. + +`$/logTrace` should be used for systematic trace reporting. For single debugging messages, the server should send [`window/logMessage`](#window_logMessage) notifications. + + +_Notification_: +* method: '$/logTrace' +* params: `LogTraceParams` defined as follows: + +```typescript +interface LogTraceParams { + /** + * The message to be logged. + */ + message: string; + /** + * Additional information that can be computed if the `trace` configuration + * is set to `'verbose'` + */ + verbose?: string; +} +``` diff --git a/_specifications/lsp/3.17/general/setTrace.md b/_specifications/lsp/3.17/general/setTrace.md new file mode 100644 index 000000000..1c9b0f088 --- /dev/null +++ b/_specifications/lsp/3.17/general/setTrace.md @@ -0,0 +1,16 @@ +#### SetTrace Notification (:arrow_right:) + +A notification that should be used by the client to modify the trace setting of the server. + +_Notification_: +* method: '$/setTrace' +* params: `SetTraceParams` defined as follows: + +```typescript +interface SetTraceParams { + /** + * The new value that should be assigned to the trace setting. + */ + value: TraceValue; +} +``` diff --git a/_specifications/lsp/3.17/general/shutdown.md b/_specifications/lsp/3.17/general/shutdown.md new file mode 100644 index 000000000..4055ac8de --- /dev/null +++ b/_specifications/lsp/3.17/general/shutdown.md @@ -0,0 +1,13 @@ +#### Shutdown Request (:leftwards_arrow_with_hook:) + +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. Clients must not send any notifications other than `exit` or requests to a server to which they have sent a shutdown request. Clients should also wait with sending the `exit` notification until they have received a response from the `shutdown` request. + +If a server receives requests after a shutdown request those requests should error with `InvalidRequest`. + +_Request_: +* method: 'shutdown' +* params: void + +_Response_: +* result: null +* error: code and message set in case an exception happens during shutdown request. diff --git a/_specifications/lsp/3.17/language/completion.md b/_specifications/lsp/3.17/language/completion.md new file mode 100644 index 000000000..89ba83783 --- /dev/null +++ b/_specifications/lsp/3.17/language/completion.md @@ -0,0 +1,824 @@ +#### Completion Request (:leftwards_arrow_with_hook:) + +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/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 typical 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 parameter. The returned completion item should have the documentation property filled in. By default the request can only delay the computation of the `detail` and `documentation` properties. Since 3.16.0 the client +can signal that it can resolve more properties lazily. This is done using the `completionItem#resolveSupport` client capability which lists all properties that can be filled in during a 'completionItem/resolve' request. All other properties (usually `sortText`, `filterText`, `insertText` and `textEdit`) must be provided in the `textDocument/completion` response and must not be changed during resolve. + +The language server protocol uses the following model around completions: + +- to achieve consistency across languages and to honor different clients usually the client is responsible for filtering and sorting. This has also the advantage that client can experiment with different filter and sorting models. However servers can enforce different behavior by setting a `filterText` / `sortText` +- for speed clients should be able to filter an already received completion list if the user continues typing. Servers can opt out of this using a `CompletionList` and mark it as `isIncomplete`. + +A completion item provides additional means to influence filtering and sorting. They are expressed by either creating a `CompletionItem` with a `insertText` or with a `textEdit`. The two modes differ as follows: + +- **Completion item provides an insertText / label without a text edit**: in the model the client should filter against what the user has already typed using the word boundary rules of the language (e.g. resolving the word under the cursor position). The reason for this mode is that it makes it extremely easy for a server to implement a basic completion list and get it filtered on the client. + +- **Completion Item with text edits**: in this mode the server tells the client that it actually knows what it is doing. If you create a completion item with a text edit at the current cursor position no word guessing takes place and no filtering should happen. This mode can be combined with a sort text and filter text to customize two things. If the text edit is a replace edit then the range denotes the word used for filtering. If the replace changes the text it most likely makes sense to specify a filter text to be used. + +_Client Capability_: +* property name (optional): `textDocument.completion` +* property type: `CompletionClientCapabilities` defined as follows: + +
+ +```typescript +export interface CompletionClientCapabilities { + /** + * Whether completion supports dynamic registration. + */ + dynamicRegistration?: boolean; + + /** + * The client supports the following `CompletionItem` specific + * capabilities. + */ + completionItem?: { + /** + * Client supports snippets as insert text. + * + * A snippet can define tab stops and placeholders with `$1`, `$2` + * and `${3:foo}`. `$0` defines the final tab stop, it defaults to + * the end of the snippet. Placeholders with equal identifiers are + * linked, that is typing in one will update others too. + */ + snippetSupport?: boolean; + + /** + * Client supports commit characters on a completion item. + */ + commitCharactersSupport?: boolean; + + /** + * Client supports the follow content formats for the documentation + * property. The order describes the preferred format of the client. + */ + documentationFormat?: MarkupKind[]; + + /** + * Client supports the deprecated property on a completion item. + */ + deprecatedSupport?: boolean; + + /** + * Client supports the preselect property on a completion item. + */ + preselectSupport?: boolean; + + /** + * Client supports the tag property on a completion item. Clients + * supporting tags have to handle unknown tags gracefully. Clients + * especially need to preserve unknown tags when sending a completion + * item back to the server in a resolve call. + * + * @since 3.15.0 + */ + tagSupport?: { + /** + * The tags supported by the client. + */ + valueSet: CompletionItemTag[]; + }; + + /** + * Client supports insert replace edit to control different behavior if + * a completion item is inserted in the text or should replace text. + * + * @since 3.16.0 + */ + insertReplaceSupport?: boolean; + + /** + * Indicates which properties a client can resolve lazily on a + * completion item. Before version 3.16.0 only the predefined properties + * `documentation` and `detail` could be resolved lazily. + * + * @since 3.16.0 + */ + resolveSupport?: { + /** + * The properties that a client can resolve lazily. + */ + properties: string[]; + }; + + /** + * The client supports the `insertTextMode` property on + * a completion item to override the whitespace handling mode + * as defined by the client (see `insertTextMode`). + * + * @since 3.16.0 + */ + insertTextModeSupport?: { + valueSet: InsertTextMode[]; + }; + + /** + * The client has support for completion item label + * details (see also `CompletionItemLabelDetails`). + * + * @since 3.17.0 - proposed state + */ + labelDetailsSupport?: boolean; + }; + + completionItemKind?: { + /** + * The completion item kind values the client supports. When this + * property exists the client also guarantees that it will + * handle values outside its set gracefully and falls back + * to a default value when unknown. + * + * If this property is not present the client only supports + * the completion items kinds from `Text` to `Reference` as defined in + * the initial version of the protocol. + */ + valueSet?: CompletionItemKind[]; + }; + + /** + * The client supports to send additional context information for a + * `textDocument/completion` request. + */ + contextSupport?: boolean; + + /** + * The client's default when the completion item doesn't provide a + * `insertTextMode` property. + * + * @since 3.17.0 - proposed state + */ + insertTextMode?: InsertTextMode; + + /** + * The client supports the following `CompletionList` specific + * capabilities. + * + * @since 3.17.0 - proposed state + */ + completionList?: { + /** + * The client supports the the following itemDefaults on + * a completion list. + * + * The value lists the supported property names of the + * `CompletionList.itemDefaults` object. If omitted + * no properties are supported. + * + * @since 3.17.0 - proposed state + */ + itemDefaults?: string[]; + } +} +``` + +_Server Capability_: +* property name (optional): `completionProvider` +* property type: `CompletionOptions` defined as follows: + +
+ +```typescript +/** + * Completion options. + */ +export interface CompletionOptions extends WorkDoneProgressOptions { + /** + * Most tools trigger completion request automatically without explicitly + * requesting it using a keyboard shortcut (e.g. Ctrl+Space). Typically they + * do so when the user starts to type an identifier. For example if the user + * types `c` in a JavaScript file code complete will automatically pop up + * present `console` besides others as a completion item. Characters that + * make up identifiers don't need to be listed here. + * + * If code complete should automatically be trigger on characters not being + * valid inside an identifier (for example `.` in JavaScript) list them in + * `triggerCharacters`. + */ + triggerCharacters?: string[]; + + /** + * The list of all possible characters that commit a completion. This field + * can be used if clients don't support individual commit characters per + * completion item. See client capability + * `completion.completionItem.commitCharactersSupport`. + * + * If a server provides both `allCommitCharacters` and commit characters on + * an individual completion item the ones on the completion item win. + * + * @since 3.2.0 + */ + allCommitCharacters?: string[]; + + /** + * The server provides support to resolve additional + * information for a completion item. + */ + resolveProvider?: boolean; + + /** + * The server supports the following `CompletionItem` specific + * capabilities. + * + * @since 3.17.0 - proposed state + */ + completionItem?: { + /** + * The server has support for completion item label + * details (see also `CompletionItemLabelDetails`) when receiving + * a completion item in a resolve call. + * + * @since 3.17.0 - proposed state + */ + labelDetailsSupport?: boolean; + } +} +``` + +_Registration Options_: `CompletionRegistrationOptions` options defined as follows: + +
+ +```typescript +export interface CompletionRegistrationOptions + extends TextDocumentRegistrationOptions, CompletionOptions { +} +``` + +_Request_: +* method: `textDocument/completion` +* params: `CompletionParams` defined as follows: + +
+ +```typescript +export interface CompletionParams extends TextDocumentPositionParams, + WorkDoneProgressParams, PartialResultParams { + /** + * The completion context. This is only available if the client specifies + * to send this using the client capability + * `completion.contextSupport === true` + */ + context?: CompletionContext; +} +``` + +
+ +```typescript +/** + * How a completion was triggered + */ +export namespace CompletionTriggerKind { + /** + * Completion was triggered by typing an identifier (24x7 code + * complete), manual invocation (e.g Ctrl+Space) or via API. + */ + export const Invoked: 1 = 1; + + /** + * Completion was triggered by a trigger character specified by + * the `triggerCharacters` properties of the + * `CompletionRegistrationOptions`. + */ + export const TriggerCharacter: 2 = 2; + + /** + * Completion was re-triggered as the current completion list is incomplete. + */ + export const TriggerForIncompleteCompletions: 3 = 3; +} +export type CompletionTriggerKind = 1 | 2 | 3; +``` + +
+ +```typescript +/** + * Contains additional information about the context in which a completion + * request is triggered. + */ +export interface CompletionContext { + /** + * How the completion was triggered. + */ + triggerKind: CompletionTriggerKind; + + /** + * The trigger character (a single character) that has trigger code + * complete. Is undefined if + * `triggerKind !== CompletionTriggerKind.TriggerCharacter` + */ + triggerCharacter?: string; +} +``` + +_Response_: +* result: `CompletionItem[]` \| `CompletionList` \| `null`. If a `CompletionItem[]` is provided it is interpreted to be complete. So it is the same as `{ isIncomplete: false, items }` + +
+ +```typescript +/** + * Represents a collection of [completion items](#CompletionItem) to be + * presented in the editor. + */ +export interface CompletionList { + /** + * This list is not complete. Further typing should result in recomputing + * this list. + * + * Recomputed lists have all their items replaced (not appended) in the + * incomplete completion sessions. + */ + isIncomplete: boolean; + + /** + * In many cases the items of an actual completion result share the same + * value for properties like `commitCharacters` or the range of a text + * edit. A completion list can therefore define item defaults which will + * be used if a completion item itself doesn't specify the value. + * + * If a completion list specifies a default value and a completion item + * also specifies a corresponding value the one from the item is used. + * + * Servers are only allowed to return default values if the client + * signals support for this via the `completionList.itemDefaults` + * capability. + * + * @since 3.17.0 - proposed state + */ + itemDefaults?: { + /** + * A default commit character set. + * + * @since 3.17.0 - proposed state + */ + commitCharacters?: string[]; + + /** + * A default edit range + * + * @since 3.17.0 - proposed state + */ + editRange?: Range | { + insert: Range; + replace: Range; + }; + + /** + * A default insert text format + * + * @since 3.17.0 - proposed state + */ + insertTextFormat?: InsertTextFormat; + + /** + * A default insert text mode + * + * @since 3.17.0 - proposed state + */ + insertTextMode?: InsertTextMode; + } + + /** + * The completion items. + */ + items: CompletionItem[]; +} +``` + +
+ +```typescript +/** + * Defines whether the insert text in a completion item should be interpreted as + * plain text or a snippet. + */ +export namespace InsertTextFormat { + /** + * The primary text to be inserted is treated as a plain string. + */ + export const PlainText = 1; + + /** + * The primary text to be inserted is treated as a snippet. + * + * A snippet can define tab stops and placeholders with `$1`, `$2` + * and `${3:foo}`. `$0` defines the final tab stop, it defaults to + * the end of the snippet. Placeholders with equal identifiers are linked, + * that is typing in one will update others too. + */ + export const Snippet = 2; +} + +export type InsertTextFormat = 1 | 2; +``` + +
+ +```typescript +/** + * Completion item tags are extra annotations that tweak the rendering of a + * completion item. + * + * @since 3.15.0 + */ +export namespace CompletionItemTag { + /** + * Render a completion as obsolete, usually using a strike-out. + */ + export const Deprecated = 1; +} + +export type CompletionItemTag = 1; +``` + +
+ +```typescript +/** + * A special text edit to provide an insert and a replace operation. + * + * @since 3.16.0 + */ +export interface InsertReplaceEdit { + /** + * The string to be inserted. + */ + newText: string; + + /** + * The range if the insert is requested + */ + insert: Range; + + /** + * The range if the replace is requested. + */ + replace: Range; +} +``` + +
+ +```typescript +/** + * How whitespace and indentation is handled during completion + * item insertion. + * + * @since 3.16.0 + */ +export namespace InsertTextMode { + /** + * The insertion or replace strings is taken as it is. If the + * value is multi line the lines below the cursor will be + * inserted using the indentation defined in the string value. + * The client will not apply any kind of adjustments to the + * string. + */ + export const asIs: 1 = 1; + + /** + * The editor adjusts leading whitespace of new lines so that + * they match the indentation up to the cursor of the line for + * which the item is accepted. + * + * Consider a line like this: <2tabs><3tabs>foo. Accepting a + * multi line completion item is indented using 2 tabs and all + * following lines inserted will be indented using 2 tabs as well. + */ + export const adjustIndentation: 2 = 2; +} + +export type InsertTextMode = 1 | 2; +``` + +
+ +```typescript +/** + * Additional details for a completion item label. + * + * @since 3.17.0 - proposed state + */ +export interface CompletionItemLabelDetails { + + /** + * An optional string which is rendered less prominently directly after + * {@link CompletionItem.label label}, without any spacing. Should be + * used for function signatures or type annotations. + */ + detail?: string; + + /** + * An optional string which is rendered less prominently after + * {@link CompletionItemLabelDetails.detail}. Should be used for fully qualified + * names or file path. + */ + description?: string; +} +``` + +
+ +```typescript +export interface CompletionItem { + + /** + * The label of this completion item. + * + * The label property is also by default the text that + * is inserted when selecting this completion. + * + * If label details are provided the label itself should + * be an unqualified name of the completion item. + */ + label: string; + + /** + * Additional details for the label + * + * @since 3.17.0 - proposed state + */ + labelDetails?: CompletionItemLabelDetails; + + + /** + * The kind of this completion item. Based of the kind + * an icon is chosen by the editor. The standardized set + * of available values is defined in `CompletionItemKind`. + */ + kind?: CompletionItemKind; + + /** + * Tags for this completion item. + * + * @since 3.15.0 + */ + tags?: CompletionItemTag[]; + + /** + * A human-readable string with additional information + * about this item, like type or symbol information. + */ + detail?: string; + + /** + * A human-readable string that represents a doc-comment. + */ + documentation?: string | MarkupContent; + + /** + * Indicates if this item is deprecated. + * + * @deprecated Use `tags` instead if supported. + */ + deprecated?: boolean; + + /** + * Select this item when showing. + * + * *Note* that only one completion item can be selected and that the + * tool / client decides which item that is. The rule is that the *first* + * item of those that match best is selected. + */ + preselect?: boolean; + + /** + * A string that should be used when comparing this item + * with other items. When `falsy` the label is used + * as the sort text for this item. + */ + sortText?: string; + + /** + * A string that should be used when filtering a set of + * completion items. When `falsy` the label is used as the + * filter text for this item. + */ + filterText?: string; + + /** + * A string that should be inserted into a document when selecting + * this completion. When `falsy` the label is used as the insert text + * for this item. + * + * The `insertText` is subject to interpretation by the client side. + * Some tools might not take the string literally. For example + * VS Code when code complete is requested in this example + * `con` and a completion item with an `insertText` of + * `console` is provided it will only insert `sole`. Therefore it is + * recommended to use `textEdit` instead since it avoids additional client + * side interpretation. + */ + insertText?: string; + + /** + * The format of the insert text. The format applies to both the + * `insertText` property and the `newText` property of a provided + * `textEdit`. If omitted defaults to `InsertTextFormat.PlainText`. + * + * Please note that the insertTextFormat doesn't apply to + * `additionalTextEdits`. + */ + insertTextFormat?: InsertTextFormat; + + /** + * How whitespace and indentation is handled during completion + * item insertion. If not provided the client's default value depends on + * the `textDocument.completion.insertTextMode` client capability. + * + * @since 3.16.0 + * @since 3.17.0 - support for `textDocument.completion.insertTextMode` + */ + insertTextMode?: InsertTextMode; + + /** + * An edit which is applied to a document when selecting this completion. + * When an edit is provided the value of `insertText` is ignored. + * + * *Note:* The range of the edit must be a single line range and it must + * contain the position at which completion has been requested. + * + * Most editors support two different operations when accepting a completion + * item. One is to insert a completion text and the other is to replace an + * existing text with a completion text. Since this can usually not be + * predetermined by a server it can report both ranges. Clients need to + * signal support for `InsertReplaceEdit`s via the + * `textDocument.completion.completionItem.insertReplaceSupport` client + * capability property. + * + * *Note 1:* The text edit's range as well as both ranges from an insert + * replace edit must be a [single line] and they must contain the position + * at which completion has been requested. + * *Note 2:* If an `InsertReplaceEdit` is returned the edit's insert range + * must be a prefix of the edit's replace range, that means it must be + * contained and starting at the same position. + * + * @since 3.16.0 additional type `InsertReplaceEdit` + */ + textEdit?: TextEdit | InsertReplaceEdit; + + /** + * An optional array of additional text edits that are applied when + * selecting this completion. Edits must not overlap (including the same + * insert position) with the main edit nor with themselves. + * + * Additional text edits should be used to change text unrelated to the + * current cursor position (for example adding an import statement at the + * top of the file if the completion item will insert an unqualified type). + */ + additionalTextEdits?: TextEdit[]; + + /** + * An optional set of characters that when pressed while this completion is + * active will accept it first and then type that character. *Note* that all + * commit characters should have `length=1` and that superfluous characters + * will be ignored. + */ + commitCharacters?: string[]; + + /** + * An optional command that is executed *after* inserting this completion. + * *Note* that additional modifications to the current document should be + * described with the additionalTextEdits-property. + */ + command?: Command; + + /** + * A data entry field that is preserved on a completion item between + * a completion and a completion resolve request. + */ + data?: LSPAny; +} +``` + +
+ +```typescript +/** + * The kind of a completion entry. + */ +export namespace CompletionItemKind { + export const Text = 1; + export const Method = 2; + export const Function = 3; + export const Constructor = 4; + export const Field = 5; + export const Variable = 6; + export const Class = 7; + export const Interface = 8; + export const Module = 9; + export const Property = 10; + export const Unit = 11; + export const Value = 12; + export const Enum = 13; + export const Keyword = 14; + export const Snippet = 15; + export const Color = 16; + export const File = 17; + export const Reference = 18; + export const Folder = 19; + export const EnumMember = 20; + export const Constant = 21; + export const Struct = 22; + export const Event = 23; + export const Operator = 24; + export const TypeParameter = 25; +} +``` +* partial result: `CompletionItem[]` or `CompletionList` followed by `CompletionItem[]`. If the first provided result item is of type `CompletionList` subsequent partial results of `CompletionItem[]` add to the `items` property of the `CompletionList`. +* error: code and message set in case an exception happens during the completion request. + +Completion items support snippets (see `InsertTextFormat.Snippet`). The snippet format is as follows: + +##### Snippet Syntax + +The `body` of a snippet can use special constructs to control cursors and the text being inserted. The following are supported features and their syntaxes: + +##### Tab stops + +With tab stops, you can make the editor cursor move inside a snippet. Use `$1`, `$2` to specify cursor locations. The number is the order in which tab stops will be visited, whereas `$0` denotes the final cursor position. Multiple tab stops are linked and updated in sync. + +##### Placeholders + +Placeholders are tab stops with values, like `${1:foo}`. The placeholder text will be inserted and selected such that it can be easily changed. Placeholders can be nested, like `${1:another ${2:placeholder}}`. + +##### Choice + +Placeholders can have choices as values. The syntax is a comma separated enumeration of values, enclosed with the pipe-character, for example `${1|one,two,three|}`. When the snippet is inserted and the placeholder selected, choices will prompt the user to pick one of the values. + +##### Variables + +With `$name` or `${name:default}` you can insert the value of a variable. When a variable isn’t set, its *default* or the empty string is inserted. When a variable is unknown (that is, its name isn’t defined) the name of the variable is inserted and it is transformed into a placeholder. + +The following variables can be used: + +* `TM_SELECTED_TEXT` The currently selected text or the empty string +* `TM_CURRENT_LINE` The contents of the current line +* `TM_CURRENT_WORD` The contents of the word under cursor or the empty string +* `TM_LINE_INDEX` The zero-index based line number +* `TM_LINE_NUMBER` The one-index based line number +* `TM_FILENAME` The filename of the current document +* `TM_FILENAME_BASE` The filename of the current document without its extensions +* `TM_DIRECTORY` The directory of the current document +* `TM_FILEPATH` The full file path of the current document + +##### Variable Transforms + +Transformations allow you to modify the value of a variable before it is inserted. The definition of a transformation consists of three parts: + +1. A [regular expression](#regExp) that is matched against the value of a variable, or the empty string when the variable cannot be resolved. +2. A "format string" that allows to reference matching groups from the regular expression. The format string allows for conditional inserts and simple modifications. +3. Options that are passed to the regular expression. + +The following example inserts the name of the current file without its ending, so from `foo.txt` it makes `foo`. + +``` +${TM_FILENAME/(.*)\..+$/$1/} + | | | | + | | | |-> no options + | | | + | | |-> references the contents of the first + | | capture group + | | + | |-> regex to capture everything before + | the final `.suffix` + | + |-> resolves to the filename +``` + +##### Grammar + +Below is the EBNF ([extended Backus-Naur form](https://en.wikipedia.org/wiki/Extended_Backus-Naur_form)) for snippets. With `\` (backslash), you can escape `$`, `}` and `\`. Within choice elements, the backslash also escapes comma and pipe characters. + +``` +any ::= tabstop | placeholder | choice | variable | text +tabstop ::= '$' int | '${' int '}' +placeholder ::= '${' int ':' any '}' +choice ::= '${' int '|' text (',' text)* '|}' +variable ::= '$' var | '${' var }' + | '${' var ':' any '}' + | '${' var '/' regex '/' (format | text)+ '/' options '}' +format ::= '$' int | '${' int '}' + | '${' int ':' '/upcase' | '/downcase' | '/capitalize' '}' + | '${' int ':+' if '}' + | '${' int ':?' if ':' else '}' + | '${' int ':-' else '}' | '${' int ':' else '}' +regex ::= Regular Expression value (ctor-string) +options ::= Regular Expression option (ctor-options) +var ::= [_a-zA-Z] [_a-zA-Z0-9]* +int ::= [0-9]+ +text ::= .* +``` + +#### Completion Item Resolve Request (:leftwards_arrow_with_hook:) + +The request is sent from the client to the server to resolve additional information for a given completion item. + +_Request_: +* method: `completionItem/resolve` +* params: `CompletionItem` + +_Response_: +* result: `CompletionItem` +* error: code and message set in case an exception happens during the completion resolve request. diff --git a/_specifications/lsp/3.17/language/declaration.md b/_specifications/lsp/3.17/language/declaration.md new file mode 100644 index 000000000..8cef5fbe3 --- /dev/null +++ b/_specifications/lsp/3.17/language/declaration.md @@ -0,0 +1,67 @@ +#### Goto Declaration Request (:leftwards_arrow_with_hook:) + +> *Since version 3.14.0* + +The go to declaration request is sent from the client to the server to resolve the declaration location of a symbol at a given text document position. + +The result type [`LocationLink`](#locationLink)[] got introduced with version 3.14.0 and depends on the corresponding client capability `textDocument.declaration.linkSupport`. + +_Client Capability_: +* property name (optional): `textDocument.declaration` +* property type: `DeclarationClientCapabilities` defined as follows: + +
+ +```typescript +export interface DeclarationClientCapabilities { + /** + * Whether declaration supports dynamic registration. If this is set to + * `true` the client supports the new `DeclarationRegistrationOptions` + * return value for the corresponding server capability as well. + */ + dynamicRegistration?: boolean; + + /** + * The client supports additional metadata in the form of declaration links. + */ + linkSupport?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `declarationProvider` +* property type: `boolean | DeclarationOptions | DeclarationRegistrationOptions` where `DeclarationOptions` is defined as follows: + +
+ +```typescript +export interface DeclarationOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `DeclarationRegistrationOptions` defined as follows: + +
+ +```typescript +export interface DeclarationRegistrationOptions extends DeclarationOptions, + TextDocumentRegistrationOptions, StaticRegistrationOptions { +} +``` + +_Request_: +* method: `textDocument/declaration` +* params: `DeclarationParams` defined as follows: + +
+ +```typescript +export interface DeclarationParams extends TextDocumentPositionParams, + WorkDoneProgressParams, PartialResultParams { +} +``` + +_Response_: +* result: [`Location`](#location) \| [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] \|`null` +* partial result: [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] +* error: code and message set in case an exception happens during the declaration request. diff --git a/_specifications/lsp/3.17/language/definition.md b/_specifications/lsp/3.17/language/definition.md new file mode 100644 index 000000000..bf9693bf9 --- /dev/null +++ b/_specifications/lsp/3.17/language/definition.md @@ -0,0 +1,65 @@ +#### Goto Definition Request (:leftwards_arrow_with_hook:) + +The go to definition request is sent from the client to the server to resolve the definition location of a symbol at a given text document position. + +The result type [`LocationLink`](#locationLink)[] got introduced with version 3.14.0 and depends on the corresponding client capability `textDocument.definition.linkSupport`. + +_Client Capability_: +* property name (optional): `textDocument.definition` +* property type: `DefinitionClientCapabilities` defined as follows: + +
+ +```typescript +export interface DefinitionClientCapabilities { + /** + * Whether definition supports dynamic registration. + */ + dynamicRegistration?: boolean; + + /** + * The client supports additional metadata in the form of definition links. + * + * @since 3.14.0 + */ + linkSupport?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `definitionProvider` +* property type: `boolean | DefinitionOptions` where `DefinitionOptions` is defined as follows: + +
+ +```typescript +export interface DefinitionOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `DefinitionRegistrationOptions` defined as follows: + +
+ +```typescript +export interface DefinitionRegistrationOptions extends + TextDocumentRegistrationOptions, DefinitionOptions { +} +``` + +_Request_: +* method: `textDocument/definition` +* params: `DefinitionParams` defined as follows: + +
+ +```typescript +export interface DefinitionParams extends TextDocumentPositionParams, + WorkDoneProgressParams, PartialResultParams { +} +``` + +_Response_: +* result: [`Location`](#location) \| [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] \| `null` +* partial result: [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] +* error: code and message set in case an exception happens during the definition request. diff --git a/_specifications/lsp/3.17/language/hover.md b/_specifications/lsp/3.17/language/hover.md new file mode 100644 index 000000000..51634bdb1 --- /dev/null +++ b/_specifications/lsp/3.17/language/hover.md @@ -0,0 +1,107 @@ +#### Hover Request (:leftwards_arrow_with_hook:) + +The hover request is sent from the client to the server to request hover information at a given text document position. + +_Client Capability_: +* property name (optional): `textDocument.hover` +* property type: `HoverClientCapabilities` defined as follows: + +
+ +```typescript +export interface HoverClientCapabilities { + /** + * Whether hover supports dynamic registration. + */ + dynamicRegistration?: boolean; + + /** + * Client supports the follow content formats if the content + * property refers to a `literal of type MarkupContent`. + * The order describes the preferred format of the client. + */ + contentFormat?: MarkupKind[]; +} +``` + +_Server Capability_: +* property name (optional): `hoverProvider` +* property type: `boolean | HoverOptions` where `HoverOptions` is defined as follows: + +
+ +```typescript +export interface HoverOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `HoverRegistrationOptions` defined as follows: + +
+ +```typescript +export interface HoverRegistrationOptions + extends TextDocumentRegistrationOptions, HoverOptions { +} +``` + +_Request_: +* method: `textDocument/hover` +* params: `HoverParams` defined as follows: + +
+ +```typescript +export interface HoverParams extends TextDocumentPositionParams, + WorkDoneProgressParams { +} +``` + +_Response_: +* result: `Hover` \| `null` defined as follows: + +
+ +```typescript +/** + * The result of a hover request. + */ +export interface Hover { + /** + * The hover's content + */ + contents: MarkedString | MarkedString[] | MarkupContent; + + /** + * An optional range is a range inside a text document + * that is used to visualize a hover, e.g. by changing the background color. + */ + range?: Range; +} +``` + +Where `MarkedString` is defined as follows: + +
+ +```typescript +/** + * MarkedString can be used to render human readable text. It is either a + * markdown string or a code-block that provides a language and a code snippet. + * The language identifier is semantically equal to the optional language + * identifier in fenced code blocks in GitHub issues. + * + * The pair of a language and a value is an equivalent to markdown: + * ```${language} + * ${value} + * ``` + * + * Note that markdown strings will be sanitized - that means html will be + * escaped. + * + * @deprecated use MarkupContent instead. + */ +type MarkedString = string | { language: string; value: string }; +``` + +* error: code and message set in case an exception happens during the hover request. diff --git a/_specifications/lsp/3.17/language/publishDiagnostics.md b/_specifications/lsp/3.17/language/publishDiagnostics.md new file mode 100644 index 000000000..b491ee75c --- /dev/null +++ b/_specifications/lsp/3.17/language/publishDiagnostics.md @@ -0,0 +1,92 @@ +#### PublishDiagnostics Notification (:arrow_left:) + +Diagnostics notification are sent from the server to the client to signal results of validation runs. + +Diagnostics are "owned" by the server so it is the server's responsibility to clear them if necessary. The following rule is used for VS Code servers that generate diagnostics: + +* if a language is single file only (for example HTML) then diagnostics are cleared by the server when the file is closed. Please note that open / close events don't necessarily reflect what the user sees in the user interface. These events are ownership events. So with the current version of the specification it is possible that problems are not cleared although the file is not visible in the user interface since the client has not closed the file yet. +* if a language has a project system (for example C#) diagnostics are not cleared when a file closes. When a project is opened all diagnostics for all files are recomputed (or read from a cache). + +When a file changes it is the server's responsibility to re-compute diagnostics and push them to the client. If the computed set is empty it has to push the empty array to clear former diagnostics. Newly pushed diagnostics always replace previously pushed diagnostics. There is no merging that happens on the client side. + +See also the [Diagnostic](#diagnostic) section. + +_Client Capability_: +* property name (optional): `textDocument.publishDiagnostics` +* property type: `PublishDiagnosticsClientCapabilities` defined as follows: + +
+ +```typescript +export interface PublishDiagnosticsClientCapabilities { + /** + * Whether the clients accepts diagnostics with related information. + */ + relatedInformation?: boolean; + + /** + * Client supports the tag property to provide meta data about a diagnostic. + * Clients supporting tags have to handle unknown tags gracefully. + * + * @since 3.15.0 + */ + tagSupport?: { + /** + * The tags supported by the client. + */ + valueSet: DiagnosticTag[]; + }; + + /** + * Whether the client interprets the version property of the + * `textDocument/publishDiagnostics` notification's parameter. + * + * @since 3.15.0 + */ + versionSupport?: boolean; + + /** + * Client supports a codeDescription property + * + * @since 3.16.0 + */ + codeDescriptionSupport?: boolean; + + /** + * Whether code action supports the `data` property which is + * preserved between a `textDocument/publishDiagnostics` and + * `textDocument/codeAction` request. + * + * @since 3.16.0 + */ + dataSupport?: boolean; +} +``` + +_Notification_: +* method: `textDocument/publishDiagnostics` +* params: `PublishDiagnosticsParams` defined as follows: + +
+ +```typescript +interface PublishDiagnosticsParams { + /** + * The URI for which diagnostic information is reported. + */ + uri: DocumentUri; + + /** + * Optional the version number of the document the diagnostics are published + * for. + * + * @since 3.15.0 + */ + version?: integer; + + /** + * An array of diagnostic information items. + */ + diagnostics: Diagnostic[]; +} +``` diff --git a/_specifications/lsp/3.17/language/signatureHelp.md b/_specifications/lsp/3.17/language/signatureHelp.md new file mode 100644 index 000000000..e7c390548 --- /dev/null +++ b/_specifications/lsp/3.17/language/signatureHelp.md @@ -0,0 +1,300 @@ +#### Signature Help Request (:leftwards_arrow_with_hook:) + +The signature help request is sent from the client to the server to request signature information at a given cursor position. + +_Client Capability_: +* property name (optional): `textDocument.signatureHelp` +* property type: `SignatureHelpClientCapabilities` defined as follows: + +
+ +```typescript +export interface SignatureHelpClientCapabilities { + /** + * Whether signature help supports dynamic registration. + */ + dynamicRegistration?: boolean; + + /** + * The client supports the following `SignatureInformation` + * specific properties. + */ + signatureInformation?: { + /** + * Client supports the follow content formats for the documentation + * property. The order describes the preferred format of the client. + */ + documentationFormat?: MarkupKind[]; + + /** + * Client capabilities specific to parameter information. + */ + parameterInformation?: { + /** + * The client supports processing label offsets instead of a + * simple label string. + * + * @since 3.14.0 + */ + labelOffsetSupport?: boolean; + }; + + /** + * The client supports the `activeParameter` property on + * `SignatureInformation` literal. + * + * @since 3.16.0 + */ + activeParameterSupport?: boolean; + }; + + /** + * The client supports to send additional context information for a + * `textDocument/signatureHelp` request. A client that opts into + * contextSupport will also support the `retriggerCharacters` on + * `SignatureHelpOptions`. + * + * @since 3.15.0 + */ + contextSupport?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `signatureHelpProvider` +* property type: `SignatureHelpOptions` defined as follows: + +
+ +```typescript +export interface SignatureHelpOptions extends WorkDoneProgressOptions { + /** + * The characters that trigger signature help + * automatically. + */ + triggerCharacters?: string[]; + + /** + * List of characters that re-trigger signature help. + * + * These trigger characters are only active when signature help is already + * showing. All trigger characters are also counted as re-trigger + * characters. + * + * @since 3.15.0 + */ + retriggerCharacters?: string[]; +} +``` + +_Registration Options_: `SignatureHelpRegistrationOptions` defined as follows: + +
+ +```typescript +export interface SignatureHelpRegistrationOptions + extends TextDocumentRegistrationOptions, SignatureHelpOptions { +} +``` + +_Request_: +* method: `textDocument/signatureHelp` +* params: `SignatureHelpParams` defined as follows: + +
+ +```typescript +export interface SignatureHelpParams extends TextDocumentPositionParams, + WorkDoneProgressParams { + /** + * The signature help context. This is only available if the client + * specifies to send this using the client capability + * `textDocument.signatureHelp.contextSupport === true` + * + * @since 3.15.0 + */ + context?: SignatureHelpContext; +} +``` + +
+ +```typescript +/** + * How a signature help was triggered. + * + * @since 3.15.0 + */ +export namespace SignatureHelpTriggerKind { + /** + * Signature help was invoked manually by the user or by a command. + */ + export const Invoked: 1 = 1; + /** + * Signature help was triggered by a trigger character. + */ + export const TriggerCharacter: 2 = 2; + /** + * Signature help was triggered by the cursor moving or by the document + * content changing. + */ + export const ContentChange: 3 = 3; +} +export type SignatureHelpTriggerKind = 1 | 2 | 3; +``` + +
+ +```typescript +/** + * Additional information about the context in which a signature help request + * was triggered. + * + * @since 3.15.0 + */ +export interface SignatureHelpContext { + /** + * Action that caused signature help to be triggered. + */ + triggerKind: SignatureHelpTriggerKind; + + /** + * Character that caused signature help to be triggered. + * + * This is undefined when triggerKind !== + * SignatureHelpTriggerKind.TriggerCharacter + */ + triggerCharacter?: string; + + /** + * `true` if signature help was already showing when it was triggered. + * + * Retriggers occur when the signature help is already active and can be + * caused by actions such as typing a trigger character, a cursor move, or + * document content changes. + */ + isRetrigger: boolean; + + /** + * The currently active `SignatureHelp`. + * + * The `activeSignatureHelp` has its `SignatureHelp.activeSignature` field + * updated based on the user navigating through available signatures. + */ + activeSignatureHelp?: SignatureHelp; +} +``` + +_Response_: +* result: `SignatureHelp` \| `null` defined as follows: + +
+ +```typescript +/** + * Signature help represents the signature of something + * callable. There can be multiple signature but only one + * active and only one active parameter. + */ +export interface SignatureHelp { + /** + * One or more signatures. If no signatures are available the signature help + * request should return `null`. + */ + signatures: SignatureInformation[]; + + /** + * The active signature. If omitted or the value lies outside the + * range of `signatures` the value defaults to zero or is ignore if + * the `SignatureHelp` as no signatures. + * + * Whenever possible implementors should make an active decision about + * the active signature and shouldn't rely on a default value. + * + * In future version of the protocol this property might become + * mandatory to better express this. + */ + activeSignature?: uinteger; + + /** + * The active parameter of the active signature. If omitted or the value + * lies outside the range of `signatures[activeSignature].parameters` + * defaults to 0 if the active signature has parameters. If + * the active signature has no parameters it is ignored. + * In future version of the protocol this property might become + * mandatory to better express the active parameter if the + * active signature does have any. + */ + activeParameter?: uinteger; +} +``` + +
+ +```typescript +/** + * Represents the signature of something callable. A signature + * can have a label, like a function-name, a doc-comment, and + * a set of parameters. + */ +export interface SignatureInformation { + /** + * The label of this signature. Will be shown in + * the UI. + */ + label: string; + + /** + * The human-readable doc-comment of this signature. Will be shown + * in the UI but can be omitted. + */ + documentation?: string | MarkupContent; + + /** + * The parameters of this signature. + */ + parameters?: ParameterInformation[]; + + /** + * The index of the active parameter. + * + * If provided, this is used in place of `SignatureHelp.activeParameter`. + * + * @since 3.16.0 + */ + activeParameter?: uinteger; +} +``` + +
+ +```typescript +/** + * Represents a parameter of a callable-signature. A parameter can + * have a label and a doc-comment. + */ +export interface ParameterInformation { + + /** + * The label of this parameter information. + * + * Either a string or an inclusive start and exclusive end offsets within + * its containing signature label. (see SignatureInformation.label). The + * offsets are based on a UTF-16 string representation as `Position` and + * `Range` does. + * + * *Note*: a label of type string should be a substring of its containing + * signature label. Its intended use case is to highlight the parameter + * label part in the `SignatureInformation.label`. + */ + label: string | [uinteger, uinteger]; + + /** + * The human-readable doc-comment of this parameter. Will be shown + * in the UI but can be omitted. + */ + documentation?: string | MarkupContent; +} +``` + +* error: code and message set in case an exception happens during the signature help request. diff --git a/_specifications/lsp/3.17/language/typeDefinition.md b/_specifications/lsp/3.17/language/typeDefinition.md new file mode 100644 index 000000000..e6df8458d --- /dev/null +++ b/_specifications/lsp/3.17/language/typeDefinition.md @@ -0,0 +1,70 @@ +#### Goto Type Definition Request (:leftwards_arrow_with_hook:) + +> *Since version 3.6.0* + +The go to type definition request is sent from the client to the server to resolve the type definition location of a symbol at a given text document position. + +The result type [`LocationLink`](#locationLink)[] got introduced with version 3.14.0 and depends on the corresponding client capability `textDocument.typeDefinition.linkSupport`. + +_Client Capability_: +* property name (optional): `textDocument.typeDefinition` +* property type: `TypeDefinitionClientCapabilities` defined as follows: + +
+ +```typescript +export interface TypeDefinitionClientCapabilities { + /** + * Whether implementation supports dynamic registration. If this is set to + * `true` the client supports the new `TypeDefinitionRegistrationOptions` + * return value for the corresponding server capability as well. + */ + dynamicRegistration?: boolean; + + /** + * The client supports additional metadata in the form of definition links. + * + * @since 3.14.0 + */ + linkSupport?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `typeDefinitionProvider` +* property type: `boolean | TypeDefinitionOptions | TypeDefinitionRegistrationOptions` where `TypeDefinitionOptions` is defined as follows: + +
+ +```typescript +export interface TypeDefinitionOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `TypeDefinitionRegistrationOptions` defined as follows: + +
+ +```typescript +export interface TypeDefinitionRegistrationOptions extends + TextDocumentRegistrationOptions, TypeDefinitionOptions, + StaticRegistrationOptions { +} +``` + +_Request_: +* method: `textDocument/typeDefinition` +* params: `TypeDefinitionParams` defined as follows: + +
+ +```typescript +export interface TypeDefinitionParams extends TextDocumentPositionParams, + WorkDoneProgressParams, PartialResultParams { +} +``` + +_Response_: +* result: [`Location`](#location) \| [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] \| `null` +* partial result: [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] +* error: code and message set in case an exception happens during the definition request. diff --git a/_specifications/lsp/3.17/specification.md b/_specifications/lsp/3.17/specification.md index 0678e1b81..69409da49 100644 --- a/_specifications/lsp/3.17/specification.md +++ b/_specifications/lsp/3.17/specification.md @@ -1837,4281 +1837,215 @@ Responses to requests should be sent in roughly the same order as the requests a However, the server may decide to use a parallel execution strategy and may wish to return responses in a different order than the requests were received. The server may do so as long as this reordering doesn't affect the correctness of the responses. For example, reordering the result of `textDocument/completion` and `textDocument/signatureHelp` is allowed, as these each of these requests usually won't affect the output of the other. On the other hand, the server most likely should not reorder `textDocument/definition` and `textDocument/rename` requests, since the executing the latter may affect the result of the former. -#### Server lifetime +#### Server lifecycle + +The current protocol specification defines that the lifecycle 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-wise) and when to shutdown a server. + +{% include_relative general/initialize.md %} +{% include_relative general/initialized.md %} +{% include_relative general/shutdown.md %} +{% include_relative general/exit.md %} +{% include_relative general/logTrace.md %} +{% include_relative general/setTrace.md %} + +{% include_relative window/showMessage.md %} +{% include_relative window/showMessageRequest.md %} +{% include_relative window/showDocument.md %} +{% include_relative window/logMessage.md %} +{% include_relative window/workDoneProgressCreate.md %} +{% include_relative window/workDoneProgressCancel.md %} + +{% include_relative telemetry/event.md %} + +{% include_relative client/registerCapability.md %} +{% include_relative client/unregisterCapability.md %} + +{% include_relative workspace/workspaceFolders.md %} +{% include_relative workspace/didChangeWorkspaceFolders.md %} +{% include_relative workspace/didChangeConfiguration.md %} +{% include_relative workspace/configuration.md %} +{% include_relative workspace/didChangeWatchedFiles.md %} +{% include_relative workspace/symbol.md %} +{% include_relative workspace/executeCommand.md %} +{% include_relative workspace/applyEdit.md %} +{% include_relative workspace/willCreateFiles.md %} +{% include_relative workspace/didCreateFiles.md %} +{% include_relative workspace/willRenameFiles.md %} +{% include_relative workspace/didRenameFiles.md %} +{% include_relative workspace/willDeleteFiles.md %} +{% include_relative workspace/didDeleteFiles.md %} -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-wise) and when to shutdown a server. - -#### Initialize Request (:leftwards_arrow_with_hook:) - -The initialize request is sent as the first request from the client to the server. If the server receives a request or notification before the `initialize` request it should act as follows: - -* For a request the response should be an error with `code: -32002`. The message can be picked by the server. -* Notifications should be dropped, except for the exit notification. This will allow the exit of a server without an initialize request. - -Until the server has responded to the `initialize` request with an `InitializeResult`, the client must not send any additional requests or notifications to the server. In addition the server is not allowed to send any requests or notifications to the client until it has responded with an `InitializeResult`, with the exception that during the `initialize` request the server is allowed to send the notifications `window/showMessage`, `window/logMessage` and `telemetry/event` as well as the `window/showMessageRequest` request to the client. In case the client sets up a progress token in the initialize params (e.g. property `workDoneToken`) the server is also allowed to use that token (and only that token) using the `$/progress` notification sent from the server to the client. - -The `initialize` request may only be sent once. - -_Request_: -* method: 'initialize' -* params: `InitializeParams` defined as follows: - -
- -```typescript -interface InitializeParams extends WorkDoneProgressParams { - /** - * The process Id of the parent process that started the server. Is null if - * the process has not been started by another process. If the parent - * process is not alive then the server should exit (see exit notification) - * its process. - */ - processId: integer | null; - - /** - * Information about the client - * - * @since 3.15.0 - */ - clientInfo?: { - /** - * The name of the client as defined by the client. - */ - name: string; - - /** - * The client's version as defined by the client. - */ - version?: string; - }; - - /** - * The locale the client is currently showing the user interface - * in. This must not necessarily be the locale of the operating - * system. - * - * Uses IETF language tags as the value's syntax - * (See https://en.wikipedia.org/wiki/IETF_language_tag) - * - * @since 3.16.0 - */ - locale?: string; - - /** - * The rootPath of the workspace. Is null - * if no folder is open. - * - * @deprecated in favour of `rootUri`. - */ - rootPath?: string | null; - - /** - * The rootUri of the workspace. Is null if no - * folder is open. If both `rootPath` and `rootUri` are set - * `rootUri` wins. - * - * @deprecated in favour of `workspaceFolders` - */ - rootUri: DocumentUri | null; - - /** - * User provided initialization options. - */ - initializationOptions?: LSPAny; - - /** - * The capabilities provided by the client (editor or tool) - */ - capabilities: ClientCapabilities; - - /** - * The initial trace setting. If omitted trace is disabled ('off'). - */ - trace?: TraceValue; - - /** - * The workspace folders configured in the client when the server starts. - * This property is only available if the client supports workspace folders. - * It can be `null` if the client supports workspace folders but none are - * configured. - * - * @since 3.6.0 - */ - workspaceFolders?: WorkspaceFolder[] | null; -} -``` -Where `ClientCapabilities` and `TextDocumentClientCapabilities` are defined as follows: - - -##### TextDocumentClientCapabilities - -`TextDocumentClientCapabilities` define capabilities the editor / tool provides on text documents. - -
- -```typescript -/** - * Text document specific client capabilities. - */ -export interface TextDocumentClientCapabilities { - - synchronization?: TextDocumentSyncClientCapabilities; - - /** - * Capabilities specific to the `textDocument/completion` request. - */ - completion?: CompletionClientCapabilities; - - /** - * Capabilities specific to the `textDocument/hover` request. - */ - hover?: HoverClientCapabilities; - - /** - * Capabilities specific to the `textDocument/signatureHelp` request. - */ - signatureHelp?: SignatureHelpClientCapabilities; - - /** - * Capabilities specific to the `textDocument/declaration` request. - * - * @since 3.14.0 - */ - declaration?: DeclarationClientCapabilities; - - /** - * Capabilities specific to the `textDocument/definition` request. - */ - definition?: DefinitionClientCapabilities; - - /** - * Capabilities specific to the `textDocument/typeDefinition` request. - * - * @since 3.6.0 - */ - typeDefinition?: TypeDefinitionClientCapabilities; - - /** - * Capabilities specific to the `textDocument/implementation` request. - * - * @since 3.6.0 - */ - implementation?: ImplementationClientCapabilities; - - /** - * Capabilities specific to the `textDocument/references` request. - */ - references?: ReferenceClientCapabilities; - - /** - * Capabilities specific to the `textDocument/documentHighlight` request. - */ - documentHighlight?: DocumentHighlightClientCapabilities; - - /** - * Capabilities specific to the `textDocument/documentSymbol` request. - */ - documentSymbol?: DocumentSymbolClientCapabilities; - - /** - * Capabilities specific to the `textDocument/codeAction` request. - */ - codeAction?: CodeActionClientCapabilities; - - /** - * Capabilities specific to the `textDocument/codeLens` request. - */ - codeLens?: CodeLensClientCapabilities; - - /** - * Capabilities specific to the `textDocument/documentLink` request. - */ - documentLink?: DocumentLinkClientCapabilities; - - /** - * Capabilities specific to the `textDocument/documentColor` and the - * `textDocument/colorPresentation` request. - * - * @since 3.6.0 - */ - colorProvider?: DocumentColorClientCapabilities; - - /** - * Capabilities specific to the `textDocument/formatting` request. - */ - formatting?: DocumentFormattingClientCapabilities; - - /** - * Capabilities specific to the `textDocument/rangeFormatting` request. - */ - rangeFormatting?: DocumentRangeFormattingClientCapabilities; - - /** request. - * Capabilities specific to the `textDocument/onTypeFormatting` request. - */ - onTypeFormatting?: DocumentOnTypeFormattingClientCapabilities; - - /** - * Capabilities specific to the `textDocument/rename` request. - */ - rename?: RenameClientCapabilities; - - /** - * Capabilities specific to the `textDocument/publishDiagnostics` - * notification. - */ - publishDiagnostics?: PublishDiagnosticsClientCapabilities; - - /** - * Capabilities specific to the `textDocument/foldingRange` request. - * - * @since 3.10.0 - */ - foldingRange?: FoldingRangeClientCapabilities; - - /** - * Capabilities specific to the `textDocument/selectionRange` request. - * - * @since 3.15.0 - */ - selectionRange?: SelectionRangeClientCapabilities; - - /** - * Capabilities specific to the `textDocument/linkedEditingRange` request. - * - * @since 3.16.0 - */ - linkedEditingRange?: LinkedEditingRangeClientCapabilities; - - /** - * Capabilities specific to the various call hierarchy requests. - * - * @since 3.16.0 - */ - callHierarchy?: CallHierarchyClientCapabilities; - - /** - * Capabilities specific to the various semantic token requests. - * - * @since 3.16.0 - */ - semanticTokens?: SemanticTokensClientCapabilities; - - /** - * Capabilities specific to the `textDocument/moniker` request. - * - * @since 3.16.0 - */ - moniker?: MonikerClientCapabilities; -} -``` - -`ClientCapabilities` define capabilities for dynamic registration, workspace and text document features the client supports. The `experimental` can be used to pass experimental 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 missing property normally defines sub properties, all missing sub properties should be interpreted as an absence of the corresponding capability. - -Client capabilities got introduced with 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). - -
- -```typescript -interface ClientCapabilities { - /** - * Workspace specific client capabilities. - */ - workspace?: { - /** - * The client supports applying batch edits - * to the workspace by supporting the request - * 'workspace/applyEdit' - */ - applyEdit?: boolean; - - /** - * Capabilities specific to `WorkspaceEdit`s - */ - workspaceEdit?: WorkspaceEditClientCapabilities; - - /** - * Capabilities specific to the `workspace/didChangeConfiguration` - * notification. - */ - didChangeConfiguration?: DidChangeConfigurationClientCapabilities; - - /** - * Capabilities specific to the `workspace/didChangeWatchedFiles` - * notification. - */ - didChangeWatchedFiles?: DidChangeWatchedFilesClientCapabilities; - - /** - * Capabilities specific to the `workspace/symbol` request. - */ - symbol?: WorkspaceSymbolClientCapabilities; - - /** - * Capabilities specific to the `workspace/executeCommand` request. - */ - executeCommand?: ExecuteCommandClientCapabilities; - - /** - * The client has support for workspace folders. - * - * @since 3.6.0 - */ - workspaceFolders?: boolean; - - /** - * The client supports `workspace/configuration` requests. - * - * @since 3.6.0 - */ - configuration?: boolean; - - /** - * Capabilities specific to the semantic token requests scoped to the - * workspace. - * - * @since 3.16.0 - */ - semanticTokens?: SemanticTokensWorkspaceClientCapabilities; - - /** - * Capabilities specific to the code lens requests scoped to the - * workspace. - * - * @since 3.16.0 - */ - codeLens?: CodeLensWorkspaceClientCapabilities; - - /** - * The client has support for file requests/notifications. - * - * @since 3.16.0 - */ - fileOperations?: { - /** - * Whether the client supports dynamic registration for file - * requests/notifications. - */ - dynamicRegistration?: boolean; - - /** - * The client has support for sending didCreateFiles notifications. - */ - didCreate?: boolean; - - /** - * The client has support for sending willCreateFiles requests. - */ - willCreate?: boolean; - - /** - * The client has support for sending didRenameFiles notifications. - */ - didRename?: boolean; - - /** - * The client has support for sending willRenameFiles requests. - */ - willRename?: boolean; - - /** - * The client has support for sending didDeleteFiles notifications. - */ - didDelete?: boolean; - - /** - * The client has support for sending willDeleteFiles requests. - */ - willDelete?: boolean; - }; - }; - - /** - * Text document specific client capabilities. - */ - textDocument?: TextDocumentClientCapabilities; - - /** - * Window specific client capabilities. - */ - window?: { - /** - * Whether client supports handling progress notifications. If set - * servers are allowed to report in `workDoneProgress` property in the - * request specific server capabilities. - * - * @since 3.15.0 - */ - workDoneProgress?: boolean; - - /** - * Capabilities specific to the showMessage request - * - * @since 3.16.0 - */ - showMessage?: ShowMessageRequestClientCapabilities; - - /** - * Client capabilities for the show document request. - * - * @since 3.16.0 - */ - showDocument?: ShowDocumentClientCapabilities; - }; - - /** - * General client capabilities. - * - * @since 3.16.0 - */ - general?: { - /** - * Client capability that signals how the client - * handles stale requests (e.g. a request - * for which the client will not process the response - * anymore since the information is outdated). - * - * @since 3.17.0 - */ - staleRequestSupport?: { - /** - * The client will actively cancel the request. - */ - cancel: boolean; - - /** - * The list of requests for which the client - * will retry the request if it receives a - * response with error code `ContentModified`` - */ - retryOnContentModified: string[]; - } - - /** - * Client capabilities specific to regular expressions. - * - * @since 3.16.0 - */ - regularExpressions?: RegularExpressionsClientCapabilities; - - /** - * Client capabilities specific to the client's markdown parser. - * - * @since 3.16.0 - */ - markdown?: MarkdownClientCapabilities; - }; - - /** - * Experimental client capabilities. - */ - experimental?: LSPAny; -} -``` - -_Response_: -* result: `InitializeResult` defined as follows: - -
- -```typescript -interface InitializeResult { - /** - * The capabilities the language server provides. - */ - capabilities: ServerCapabilities; - - /** - * Information about the server. - * - * @since 3.15.0 - */ - serverInfo?: { - /** - * The name of the server as defined by the server. - */ - name: string; - - /** - * The server's version as defined by the server. - */ - version?: string; - }; -} -``` -* error.code: - -
- -```typescript -/** - * Known error codes for an `InitializeError`; - */ -export namespace InitializeError { - /** - * If the protocol version provided by the client can't be handled by the - * server. - * - * @deprecated This initialize error got replaced by client capabilities. - * There is no version handshake in version 3.0x - */ - export const unknownProtocolVersion: 1 = 1; -} -``` - -* error.data: - -```typescript -interface InitializeError { - /** - * Indicates whether the client execute the following retry logic: - * (1) show the message provided by the ResponseError to the user - * (2) user selects retry or cancel - * (3) if user selected retry the initialize method is sent again. - */ - retry: boolean; -} -``` - -The server can signal the following capabilities: - -
- -```typescript -interface ServerCapabilities { - /** - * Defines how text documents are synced. Is either a detailed structure - * defining each notification or for backwards compatibility the - * TextDocumentSyncKind number. If omitted it defaults to - * `TextDocumentSyncKind.None`. - */ - textDocumentSync?: TextDocumentSyncOptions | TextDocumentSyncKind; - - /** - * The server provides completion support. - */ - completionProvider?: CompletionOptions; - - /** - * The server provides hover support. - */ - hoverProvider?: boolean | HoverOptions; - - /** - * The server provides signature help support. - */ - signatureHelpProvider?: SignatureHelpOptions; - - /** - * The server provides go to declaration support. - * - * @since 3.14.0 - */ - declarationProvider?: boolean | DeclarationOptions - | DeclarationRegistrationOptions; - - /** - * The server provides goto definition support. - */ - definitionProvider?: boolean | DefinitionOptions; - - /** - * The server provides goto type definition support. - * - * @since 3.6.0 - */ - typeDefinitionProvider?: boolean | TypeDefinitionOptions - | TypeDefinitionRegistrationOptions; - - /** - * The server provides goto implementation support. - * - * @since 3.6.0 - */ - implementationProvider?: boolean | ImplementationOptions - | ImplementationRegistrationOptions; - - /** - * The server provides find references support. - */ - referencesProvider?: boolean | ReferenceOptions; - - /** - * The server provides document highlight support. - */ - documentHighlightProvider?: boolean | DocumentHighlightOptions; - - /** - * The server provides document symbol support. - */ - documentSymbolProvider?: boolean | DocumentSymbolOptions; - - /** - * The server provides code actions. The `CodeActionOptions` return type is - * only valid if the client signals code action literal support via the - * property `textDocument.codeAction.codeActionLiteralSupport`. - */ - codeActionProvider?: boolean | CodeActionOptions; - - /** - * The server provides code lens. - */ - codeLensProvider?: CodeLensOptions; - - /** - * The server provides document link support. - */ - documentLinkProvider?: DocumentLinkOptions; - - /** - * The server provides color provider support. - * - * @since 3.6.0 - */ - colorProvider?: boolean | DocumentColorOptions - | DocumentColorRegistrationOptions; - - /** - * The server provides document formatting. - */ - documentFormattingProvider?: boolean | DocumentFormattingOptions; - - /** - * The server provides document range formatting. - */ - documentRangeFormattingProvider?: boolean | DocumentRangeFormattingOptions; - - /** - * The server provides document formatting on typing. - */ - documentOnTypeFormattingProvider?: DocumentOnTypeFormattingOptions; - - /** - * The server provides rename support. RenameOptions may only be - * specified if the client states that it supports - * `prepareSupport` in its initial `initialize` request. - */ - renameProvider?: boolean | RenameOptions; - - /** - * The server provides folding provider support. - * - * @since 3.10.0 - */ - foldingRangeProvider?: boolean | FoldingRangeOptions - | FoldingRangeRegistrationOptions; - - /** - * The server provides execute command support. - */ - executeCommandProvider?: ExecuteCommandOptions; - - /** - * The server provides selection range support. - * - * @since 3.15.0 - */ - selectionRangeProvider?: boolean | SelectionRangeOptions - | SelectionRangeRegistrationOptions; - - /** - * The server provides linked editing range support. - * - * @since 3.16.0 - */ - linkedEditingRangeProvider?: boolean | LinkedEditingRangeOptions - | LinkedEditingRangeRegistrationOptions; - - /** - * The server provides call hierarchy support. - * - * @since 3.16.0 - */ - callHierarchyProvider?: boolean | CallHierarchyOptions - | CallHierarchyRegistrationOptions; - - /** - * The server provides semantic tokens support. - * - * @since 3.16.0 - */ - semanticTokensProvider?: SemanticTokensOptions - | SemanticTokensRegistrationOptions; - - /** - * Whether server provides moniker support. - * - * @since 3.16.0 - */ - monikerProvider?: boolean | MonikerOptions | MonikerRegistrationOptions; - - /** - * The server provides workspace symbol support. - */ - workspaceSymbolProvider?: boolean | WorkspaceSymbolOptions; - - /** - * Workspace specific server capabilities - */ - workspace?: { - /** - * The server supports workspace folder. - * - * @since 3.6.0 - */ - workspaceFolders?: WorkspaceFoldersServerCapabilities; - - /** - * The server is interested in file notifications/requests. - * - * @since 3.16.0 - */ - fileOperations?: { - /** - * The server is interested in receiving didCreateFiles - * notifications. - */ - didCreate?: FileOperationRegistrationOptions; - - /** - * The server is interested in receiving willCreateFiles requests. - */ - willCreate?: FileOperationRegistrationOptions; - - /** - * The server is interested in receiving didRenameFiles - * notifications. - */ - didRename?: FileOperationRegistrationOptions; - - /** - * The server is interested in receiving willRenameFiles requests. - */ - willRename?: FileOperationRegistrationOptions; - - /** - * The server is interested in receiving didDeleteFiles file - * notifications. - */ - didDelete?: FileOperationRegistrationOptions; - - /** - * The server is interested in receiving willDeleteFiles file - * requests. - */ - willDelete?: FileOperationRegistrationOptions; - }; - }; - - /** - * Experimental server capabilities. - */ - experimental?: LSPAny; -} -``` - -#### Initialized Notification (:arrow_right:) - -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. The `initialized` notification may only be sent once. - -_Notification_: -* method: 'initialized' -* params: `InitializedParams` defined as follows: - -```typescript -interface InitializedParams { -} -``` - -#### Shutdown Request (:leftwards_arrow_with_hook:) - -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. Clients must not send any notifications other than `exit` or requests to a server to which they have sent a shutdown request. Clients should also wait with sending the `exit` notification until they have received a response from the `shutdown` request. - -If a server receives requests after a shutdown request those requests should error with `InvalidRequest`. - -_Request_: -* method: 'shutdown' -* params: void - -_Response_: -* result: null -* error: code and message set in case an exception happens during shutdown request. - -#### Exit Notification (:arrow_right:) - -A notification to ask the server to exit its process. -The server should exit with `success` code 0 if the shutdown request has been received before; otherwise with `error` code 1. - -_Notification_: -* method: 'exit' -* params: void - -#### LogTrace Notification (:arrow_left:) - -A notification to log the trace of the server's execution. -The amount and content of these notifications depends on the current `trace` configuration. -If `trace` is `'off'`, the server should not send any `logTrace` notification. -If `trace` is `'messages'`, the server should not add the `'verbose'` field in the `LogTraceParams`. - -`$/logTrace` should be used for systematic trace reporting. For single debugging messages, the server should send [`window/logMessage`](#window_logMessage) notifications. - - -_Notification_: -* method: '$/logTrace' -* params: `LogTraceParams` defined as follows: - -```typescript -interface LogTraceParams { - /** - * The message to be logged. - */ - message: string; - /** - * Additional information that can be computed if the `trace` configuration - * is set to `'verbose'` - */ - verbose?: string; -} -``` - -#### SetTrace Notification (:arrow_right:) - -A notification that should be used by the client to modify the trace setting of the server. - -_Notification_: -* method: '$/setTrace' -* params: `SetTraceParams` defined as follows: - -```typescript -interface SetTraceParams { - /** - * The new value that should be assigned to the trace setting. - */ - value: TraceValue; -} -``` - -#### ShowMessage Notification (:arrow_left:) - -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. - -_Notification_: -* method: 'window/showMessage' -* params: `ShowMessageParams` defined as follows: - -```typescript -interface ShowMessageParams { - /** - * The message type. See {@link MessageType}. - */ - type: MessageType; - - /** - * The actual message. - */ - message: string; -} -``` - -Where the type is defined as follows: - -
- -```typescript -export namespace MessageType { - /** - * An error message. - */ - export const Error = 1; - /** - * A warning message. - */ - export const Warning = 2; - /** - * An information message. - */ - export const Info = 3; - /** - * A log message. - */ - export const Log = 4; -} - -export type MessageType = 1 | 2 | 3 | 4; -``` - -#### ShowMessage Request (:arrow_right_hook:) - -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. - -_Client Capability_: -* property path (optional): `window.showMessage` -* property type: `ShowMessageRequestClientCapabilities` defined as follows: - -```typescript -/** - * Show message request client capabilities - */ -export interface ShowMessageRequestClientCapabilities { - /** - * Capabilities specific to the `MessageActionItem` type. - */ - messageActionItem?: { - /** - * Whether the client supports additional attributes which - * are preserved and sent back to the server in the - * request's response. - */ - additionalPropertiesSupport?: boolean; - }; -} -``` - -_Request_: -* method: 'window/showMessageRequest' -* params: `ShowMessageRequestParams` defined as follows: - -_Response_: -* result: the selected `MessageActionItem` \| `null` if none got selected. -* error: code and message set in case an exception happens during showing a message. - -
- -```typescript -interface ShowMessageRequestParams { - /** - * The message type. See {@link MessageType} - */ - type: MessageType; - - /** - * The actual message - */ - message: string; - - /** - * The message action items to present. - */ - actions?: MessageActionItem[]; -} -``` - -Where the `MessageActionItem` is defined as follows: - -
- -```typescript -interface MessageActionItem { - /** - * A short title like 'Retry', 'Open Log' etc. - */ - title: string; -} -``` - -#### Show Document Request (:arrow_right_hook:) - -> New in version 3.16.0 - -The show document request is sent from a server to a client to ask the client to display a particular document in the user interface. - -_Client Capability_: -* property path (optional): `window.showDocument` -* property type: `ShowDocumentClientCapabilities` defined as follows: - -```typescript -/** - * Client capabilities for the show document request. - * - * @since 3.16.0 - */ -export interface ShowDocumentClientCapabilities { - /** - * The client has support for the show document - * request. - */ - support: boolean; -} -``` - -_Request_: -* method: 'window/showDocument' -* params: `ShowDocumentParams` defined as follows: - -
- -```typescript -/** - * Params to show a document. - * - * @since 3.16.0 - */ -export interface ShowDocumentParams { - /** - * The document uri to show. - */ - uri: URI; - - /** - * Indicates to show the resource in an external program. - * To show for example `https://code.visualstudio.com/` - * in the default WEB browser set `external` to `true`. - */ - external?: boolean; - - /** - * An optional property to indicate whether the editor - * showing the document should take focus or not. - * Clients might ignore this property if an external - * program is started. - */ - takeFocus?: boolean; - - /** - * An optional selection range if the document is a text - * document. Clients might ignore the property if an - * external program is started or the file is not a text - * file. - */ - selection?: Range; -} -``` - -_Response_: - -* result: `ShowDocumentResult` defined as follows: - -
- -```typescript -/** - * The result of an show document request. - * - * @since 3.16.0 - */ -export interface ShowDocumentResult { - /** - * A boolean indicating if the show was successful. - */ - success: boolean; -} -``` -* error: code and message set in case an exception happens during showing a document. - -#### LogMessage Notification (:arrow_left:) - -The log message notification is sent from the server to the client to ask the client to log a particular message. - -_Notification_: -* method: 'window/logMessage' -* params: `LogMessageParams` defined as follows: - -
- -```typescript -interface LogMessageParams { - /** - * The message type. See {@link MessageType} - */ - type: MessageType; - - /** - * The actual message - */ - message: string; -} -``` - -#### Creating Work Done Progress (:arrow_right_hook:) - -The `window/workDoneProgress/create` request is sent from the server to the client to ask the client to create a work done progress. - -_Request_: - -* method: 'window/workDoneProgress/create' -* params: `WorkDoneProgressCreateParams` defined as follows: - -```typescript -export interface WorkDoneProgressCreateParams { - /** - * The token to be used to report progress. - */ - token: ProgressToken; -} -``` - -_Response_: - -* result: void -* error: code and message set in case an exception happens during the 'window/workDoneProgress/create' request. In case an error occurs a server must not send any progress notification using the token provided in the `WorkDoneProgressCreateParams`. - -#### Canceling a Work Done Progress (:arrow_right:) - -The `window/workDoneProgress/cancel` notification is sent from the client to the server to cancel a progress initiated on the server side using the `window/workDoneProgress/create`. The progress need not be marked as `cancellable` to be cancelled and a client may cancel a progress for any number of reasons: in case of error, reloading a workspace etc. - -_Notification_: - -* method: 'window/workDoneProgress/cancel' -* params: `WorkDoneProgressCancelParams` defined as follows: - -```typescript -export interface WorkDoneProgressCancelParams { - /** - * The token to be used to report progress. - */ - token: ProgressToken; -} -``` - -#### Telemetry Notification (:arrow_left:) - -The telemetry notification is sent from the server to the client to ask the client to log a telemetry event. The protocol doesn't specify the payload since no interpretation of the data happens in the protocol. Most clients even don't handle the event directly but forward them to the extensions owing the corresponding server issuing the event. - -_Notification_: -* method: 'telemetry/event' -* params: 'object' \| 'number' \| 'boolean' \| 'string'; - -#### Register Capability (:arrow_right_hook:) - -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 `dynamicRegistration` property on the specific client capabilities. A client can even provide dynamic registration for capability A but not for capability B (see `TextDocumentClientCapabilities` as an example). - -Server must not register the same capability both statically through the initialize result and dynamically for the same document selector. If a server wants to support both static and dynamic registration it needs to check the client capability in the initialize request and only register the capability statically if the client doesn't support dynamic registration for that capability. - -_Request_: -* method: 'client/registerCapability' -* params: `RegistrationParams` - -Where `RegistrationParams` are defined as follows: - -
- -```typescript -/** - * General parameters to register for a capability. - */ -export interface Registration { - /** - * The id used to register the request. The id can be used to deregister - * the request again. - */ - id: string; - - /** - * The method / capability to register for. - */ - method: string; - - /** - * Options necessary for the registration. - */ - registerOptions?: LSPAny; -} -``` - -
- -```typescript -export interface RegistrationParams { - registrations: Registration[]; -} -``` - -Since most of the registration options require to specify a document selector there is a base interface that can be used. See `TextDocumentRegistrationOptions`. - -An example JSON RPC message to register dynamically for the `textDocument/willSaveWaitUntil` feature on the client side is as follows (only details shown): - -```json -{ - "method": "client/registerCapability", - "params": { - "registrations": [ - { - "id": "79eee87c-c409-4664-8102-e03263673f6f", - "method": "textDocument/willSaveWaitUntil", - "registerOptions": { - "documentSelector": [ - { "language": "javascript" } - ] - } - } - ] - } -} -``` - -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. - -_Response_: -* result: void. -* error: code and message set in case an exception happens during the request. - -#### Unregister Capability (:arrow_right_hook:) - -The `client/unregisterCapability` request is sent from the server to the client to unregister a previously registered capability. - -_Request_: -* method: 'client/unregisterCapability' -* params: `UnregistrationParams` - -Where `UnregistrationParams` are defined as follows: - -
- -```typescript -/** - * General parameters to unregister a capability. - */ -export interface Unregistration { - /** - * The id used to unregister the request or notification. Usually an id - * provided during the register request. - */ - id: string; - - /** - * The method / capability to unregister for. - */ - method: string; -} -``` - -
- -```typescript -export interface UnregistrationParams { - // This should correctly be named `unregistrations`. However changing this - // is a breaking change and needs to wait until we deliver a 4.x version - // of the specification. - unregisterations: Unregistration[]; -} -``` - -An example JSON RPC message to unregister the above registered `textDocument/willSaveWaitUntil` feature looks like this: - -```json -{ - "method": "client/unregisterCapability", - "params": { - "unregisterations": [ - { - "id": "79eee87c-c409-4664-8102-e03263673f6f", - "method": "textDocument/willSaveWaitUntil" - } - ] - } -} -``` -_Response_: -* result: void. -* error: code and message set in case an exception happens during the request. - -##### Workspace folders request (:arrow_right_hook:) - -> *Since version 3.6.0* - -Many tools support more than one root folder per workspace. Examples for this are VS Code's multi-root support, Atom's project folder support or Sublime's project support. If a client workspace consists of multiple roots then a server typically needs to know about this. The protocol up to now assumes one root folder which is announced to the server by the `rootUri` property of the `InitializeParams`. If the client supports workspace folders and announces them via the corresponding `workspaceFolders` client capability, the `InitializeParams` contain an additional property `workspaceFolders` with the configured workspace folders when the server starts. - -The `workspace/workspaceFolders` request is sent from the server to the client to fetch the current open list of workspace folders. Returns `null` in the response if only a single file is open in the tool. Returns an empty array if a workspace is open but no folders are configured. - -_Client Capability_: -* property path (optional): `workspace.workspaceFolders` -* property type: `boolean` - -_Server Capability_: -* property path (optional): `workspace.workspaceFolders` -* property type: `WorkspaceFoldersServerCapabilities` defined as follows: - -
- -```typescript -export interface WorkspaceFoldersServerCapabilities { - /** - * The server has support for workspace folders - */ - supported?: boolean; - - /** - * Whether the server wants to receive workspace folder - * change notifications. - * - * If a string is provided, the string is treated as an ID - * under which the notification is registered on the client - * side. The ID can be used to unregister for these events - * using the `client/unregisterCapability` request. - */ - changeNotifications?: string | boolean; -} -``` - -_Request_: -* method: `workspace/workspaceFolders` -* params: none - -_Response_: -* result: `WorkspaceFolder[] | null` defined as follows: - -
- -```typescript -export interface WorkspaceFolder { - /** - * The associated URI for this workspace folder. - */ - uri: DocumentUri; - - /** - * The name of the workspace folder. Used to refer to this - * workspace folder in the user interface. - */ - name: string; -} -``` -* error: code and message set in case an exception happens during the 'workspace/workspaceFolders' request - -##### DidChangeWorkspaceFolders Notification (:arrow_right:) - -> *Since version 3.6.0* - -The `workspace/didChangeWorkspaceFolders` notification is sent from the client to the server to inform the server about workspace folder configuration changes. The notification is sent by default if both _client capability_ `workspace.workspaceFolders` and the _server capability_ `workspace.workspaceFolders.supported` are true; or if the server has registered itself to receive this notification. To register for the `workspace/didChangeWorkspaceFolders` send a `client/registerCapability` request from the server to the client. The registration parameter must have a `registrations` item of the following form, where `id` is a unique id used to unregister the capability (the example uses a UUID): -```ts -{ - id: "28c6150c-bd7b-11e7-abc4-cec278b6b50a", - method: "workspace/didChangeWorkspaceFolders" -} -``` - -_Notification_: -* method: 'workspace/didChangeWorkspaceFolders' -* params: `DidChangeWorkspaceFoldersParams` defined as follows: - -
- -```typescript -export interface DidChangeWorkspaceFoldersParams { - /** - * The actual workspace folder change event. - */ - event: WorkspaceFoldersChangeEvent; -} -``` - -
- -```typescript -/** - * The workspace folder change event. - */ -export interface WorkspaceFoldersChangeEvent { - /** - * The array of added workspace folders - */ - added: WorkspaceFolder[]; - - /** - * The array of the removed workspace folders - */ - removed: WorkspaceFolder[]; -} -``` - -#### DidChangeConfiguration Notification (:arrow_right:) - -A notification sent from the client to the server to signal the change of configuration settings. - -_Client Capability_: -* property path (optional): `workspace.didChangeConfiguration` -* property type: `DidChangeConfigurationClientCapabilities` defined as follows: - -
- -```typescript -export interface DidChangeConfigurationClientCapabilities { - /** - * Did change configuration notification supports dynamic registration. - */ - dynamicRegistration?: boolean; -} -``` - -_Notification_: -* method: 'workspace/didChangeConfiguration', -* params: `DidChangeConfigurationParams` defined as follows: - -
- -```typescript -interface DidChangeConfigurationParams { - /** - * The actual changed settings - */ - settings: LSPAny; -} -``` - -#### Configuration Request (:arrow_right_hook:) - -> *Since version 3.6.0* - -The `workspace/configuration` request is sent from the server to the client to fetch configuration settings from the client. The request can fetch several configuration settings in one roundtrip. The order of the returned configuration settings correspond to the order of the passed `ConfigurationItems` (e.g. the first item in the response is the result for the first configuration item in the params). - -A `ConfigurationItem` consists of the configuration section to ask for and an additional scope URI. The configuration section asked for is defined by the server and doesn't necessarily need to correspond to the configuration store used by the client. So a server might ask for a configuration `cpp.formatterOptions` but the client stores the configuration in an XML store layout differently. It is up to the client to do the necessary conversion. If a scope URI is provided the client should return the setting scoped to the provided resource. If the client for example uses [EditorConfig](http://editorconfig.org/) to manage its settings the configuration should be returned for the passed resource URI. If the client can't provide a configuration setting for a given scope then `null` needs to be present in the returned array. - -_Client Capability_: -* property path (optional): `workspace.configuration` -* property type: `boolean` - -_Request_: -* method: 'workspace/configuration' -* params: `ConfigurationParams` defined as follows - -
- -```typescript -export interface ConfigurationParams { - items: ConfigurationItem[]; -} -``` - -
- -```typescript -export interface ConfigurationItem { - /** - * The scope to get the configuration section for. - */ - scopeUri?: DocumentUri; - - /** - * The configuration section asked for. - */ - section?: string; -} -``` - -_Response_: -* result: LSPAny[] -* error: code and message set in case an exception happens during the 'workspace/configuration' request - -#### DidChangeWatchedFiles Notification (:arrow_right:) - -The watched files notification is sent from the client to the server when the client detects changes to files and folders watched by the language client (note although the name suggest that only file events are sent it is about file system events which include folders as well). It is recommended that servers register for these file system events using the registration mechanism. In former implementations clients pushed file events without the server actively asking for it. - -Servers are allowed to run their own file system watching mechanism and not rely on clients to provide file system events. However this is not recommended due to the following reasons: - -- to our experience getting file system watching on disk right is challenging, especially if it needs to be supported across multiple OSes. -- file system watching is not for free especially if the implementation uses some sort of polling and keeps a file system tree in memory to compare time stamps (as for example some node modules do) -- a client usually starts more than one server. If every server runs its own file system watching it can become a CPU or memory problem. -- in general there are more server than client implementations. So this problem is better solved on the client side. - -_Client Capability_: -* property path (optional): `workspace.didChangeWatchedFiles` -* property type: `DidChangeWatchedFilesClientCapabilities` defined as follows: - -
- -```typescript -export interface DidChangeWatchedFilesClientCapabilities { - /** - * Did change watched files notification supports dynamic registration. - * Please note that the current protocol doesn't support static - * configuration for file changes from the server side. - */ - dynamicRegistration?: boolean; -} -``` - -_Registration Options_: `DidChangeWatchedFilesRegistrationOptions` defined as follows: - -
- -```typescript -/** - * Describe options to be used when registering for file system change events. - */ -export interface DidChangeWatchedFilesRegistrationOptions { - /** - * The watchers to register. - */ - watchers: FileSystemWatcher[]; -} -``` - -
- -```typescript -export interface FileSystemWatcher { - /** - * The glob pattern to watch. - * - * Glob patterns can have the following syntax: - * - `*` to match one or more characters in a path segment - * - `?` to match on one character in a path segment - * - `**` to match any number of path segments, including none - * - `{}` to group sub patterns into an OR expression. (e.g. `**​/*.{ts,js}` - * matches all TypeScript and JavaScript files) - * - `[]` to declare a range of characters to match in a path segment - * (e.g., `example.[0-9]` to match on `example.0`, `example.1`, …) - * - `[!...]` to negate a range of characters to match in a path segment - * (e.g., `example.[!0-9]` to match on `example.a`, `example.b`, but not - * `example.0`) - */ - globPattern: string; - - /** - * The kind of events of interest. If omitted it defaults - * to WatchKind.Create | WatchKind.Change | WatchKind.Delete - * which is 7. - */ - kind?: uinteger; -} -``` - -
- -```typescript -export namespace WatchKind { - /** - * Interested in create events. - */ - export const Create = 1; - - /** - * Interested in change events - */ - export const Change = 2; - - /** - * Interested in delete events - */ - export const Delete = 4; -} -``` - -_Notification_: -* method: 'workspace/didChangeWatchedFiles' -* params: `DidChangeWatchedFilesParams` defined as follows: - -
- -```typescript -interface DidChangeWatchedFilesParams { - /** - * The actual file events. - */ - changes: FileEvent[]; -} -``` - -Where FileEvents are described as follows: - -
- -```typescript -/** - * An event describing a file change. - */ -interface FileEvent { - /** - * The file's URI. - */ - uri: DocumentUri; - /** - * The change type. - */ - type: uinteger; -} -``` - -
- -```typescript -/** - * The file event type. - */ -export namespace FileChangeType { - /** - * The file got created. - */ - export const Created = 1; - /** - * The file got changed. - */ - export const Changed = 2; - /** - * The file got deleted. - */ - export const Deleted = 3; -} -``` - -#### Workspace Symbols Request (:leftwards_arrow_with_hook:) - -The workspace symbol request is sent from the client to the server to list project-wide symbols matching the query string. Since 3.17.0 servers can also provider a handler for `workspaceSymbol/resolve` requests. This allows servers to return workspace symbols without a range for a `workspace/symbol` request. Clients then need to resolve the range when necessary using the `workspaceSymbol/resolve` request. Servers can only use this new model if clients advertise support for it via the `workspace.symbol.resolveSupport` capability. - -_Client Capability_: -* property path (optional): `workspace.symbol` -* property type: `WorkspaceSymbolClientCapabilities` defined as follows: - -```typescript -interface WorkspaceSymbolClientCapabilities { - /** - * Symbol request supports dynamic registration. - */ - dynamicRegistration?: boolean; - - /** - * Specific capabilities for the `SymbolKind` in the `workspace/symbol` - * request. - */ - symbolKind?: { - /** - * The symbol kind values the client supports. When this - * property exists the client also guarantees that it will - * handle values outside its set gracefully and falls back - * to a default value when unknown. - * - * If this property is not present the client only supports - * the symbol kinds from `File` to `Array` as defined in - * the initial version of the protocol. - */ - valueSet?: SymbolKind[]; - }; - - /** - * The client supports tags on `SymbolInformation` and `WorkspaceSymbol`. - * Clients supporting tags have to handle unknown tags gracefully. - * - * @since 3.16.0 - */ - tagSupport?: { - /** - * The tags supported by the client. - */ - valueSet: SymbolTag[]; - }; - - /** - * The client support partial workspace symbols. The client will send the - * request `workspaceSymbol/resolve` to the server to resolve additional - * properties. - * - * @since 3.17.0 - proposedState - */ - resolveSupport?: { - /** - * The properties that a client can resolve lazily. Usually - * `location.range` - */ - properties: string[]; - }; -} -``` - -_Server Capability_: -* property path (optional): `workspaceSymbolProvider` -* property type: `boolean | WorkspaceSymbolOptions` where `WorkspaceSymbolOptions` is defined as follows: - -
- -```typescript -export interface WorkspaceSymbolOptions extends WorkDoneProgressOptions { - /** - * The server provides support to resolve additional - * information for a workspace symbol. - * - * @since 3.17.0 - proposed state - */ - resolveProvider?: boolean; -} -``` - -_Registration Options_: `WorkspaceSymbolRegistrationOptions` defined as follows: - -
- -```typescript -export interface WorkspaceSymbolRegistrationOptions - extends WorkspaceSymbolOptions { -} -``` - -_Request_: -* method: 'workspace/symbol' -* params: `WorkspaceSymbolParams` defined as follows: - -
- -```typescript -/** - * The parameters of a Workspace Symbol Request. - */ -interface WorkspaceSymbolParams extends WorkDoneProgressParams, - PartialResultParams { - /** - * A query string to filter symbols by. Clients may send an empty - * string here to request all symbols. - */ - query: string; -} -``` - -_Response_: -* result: `SymbolInformation[]` \| `WorkspaceSymbol[]` \| `null`. See above for the definition of `SymbolInformation`. `WorkspaceSymbol` is defined as follows: - -
- -```typescript -/** - * A special workspace symbol that supports locations without a range - * - * @since 3.17.0 - proposed state - */ -export interface WorkspaceSymbol { - /** - * The name of this symbol. - */ - name: string; - - /** - * The kind of this symbol. - */ - kind: SymbolKind; - - /** - * Tags for this completion item. - */ - tags?: SymbolTag[]; - - /** - * The location of this symbol. - * - * See also `SymbolInformation.location`. - */ - location: Location | { uri: DocumentUri }; - - /** - * The name of the symbol containing this symbol. This information is for - * user interface purposes (e.g. to render a qualifier in the user interface - * if necessary). It can't be used to re-infer a hierarchy for the document - * symbols. - */ - containerName?: string; -} -``` -* partial result: `SymbolInformation[]` \| `WorkspaceSymbol[]` as defined above. -* error: code and message set in case an exception happens during the workspace symbol request. - -#### Workspace Symbol Resolve Request (:leftwards_arrow_with_hook:) - -The request is sent from the client to the server to resolve additional information for a given workspace symbol. - -_Request_: -* method: 'workspaceSymbol/resolve' -* params: `WorkspaceSymbol` - -_Response_: -* result: `WorkspaceSymbol` -* error: code and message set in case an exception happens during the workspace symbol resolve request. - - -#### Execute a command (:leftwards_arrow_with_hook:) - -The `workspace/executeCommand` request is sent from the client to the server to trigger command execution on the server. In most cases the server creates a `WorkspaceEdit` structure and applies the changes to the workspace using the request `workspace/applyEdit` which is sent from the server to the client. - -_Client Capability_: -* property path (optional): `workspace.executeCommand` -* property type: `ExecuteCommandClientCapabilities` defined as follows: - -
- -```typescript -export interface ExecuteCommandClientCapabilities { - /** - * Execute command supports dynamic registration. - */ - dynamicRegistration?: boolean; -} -``` - -_Server Capability_: -* property path (optional): `executeCommandProvider` -* property type: `ExecuteCommandOptions` defined as follows: - -
- -```typescript -export interface ExecuteCommandOptions extends WorkDoneProgressOptions { - /** - * The commands to be executed on the server - */ - commands: string[]; -} -``` - -_Registration Options_: `ExecuteCommandRegistrationOptions` defined as follows: - -
- -```typescript -/** - * Execute command registration options. - */ -export interface ExecuteCommandRegistrationOptions - extends ExecuteCommandOptions { -} -``` - -_Request_: -* method: 'workspace/executeCommand' -* params: `ExecuteCommandParams` defined as follows: - -
- -```typescript -export interface ExecuteCommandParams extends WorkDoneProgressParams { - - /** - * The identifier of the actual command handler. - */ - command: string; - /** - * Arguments that the command should be invoked with. - */ - arguments?: LSPAny[]; -} -``` - -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`. - -_Response_: -* result: `LSPAny` \| `null` -* error: code and message set in case an exception happens during the request. - -#### Applies a WorkspaceEdit (:arrow_right_hook:) - -The `workspace/applyEdit` request is sent from the server to the client to modify resource on the client side. - -_Client Capability_: -* property path (optional): `workspace.applyEdit` -* property type: `boolean` - -See also the [WorkspaceEditClientCapabilities](#workspaceEditClientCapabilities) for the supported capabilities of a workspace edit. - -_Request_: -* method: 'workspace/applyEdit' -* params: `ApplyWorkspaceEditParams` defined as follows: - -
- -```typescript -export interface ApplyWorkspaceEditParams { - /** - * An optional label of the workspace edit. This label is - * presented in the user interface for example on an undo - * stack to undo the workspace edit. - */ - label?: string; - - /** - * The edits to apply. - */ - edit: WorkspaceEdit; -} -``` - -_Response_: -* result: `ApplyWorkspaceEditResult` defined as follows: - -
- -```typescript -export interface ApplyWorkspaceEditResult { - /** - * Indicates whether the edit was applied or not. - */ - applied: boolean; - - /** - * An optional textual description for why the edit was not applied. - * This may be used by the server for diagnostic logging or to provide - * a suitable error for a request that triggered the edit. - */ - failureReason?: string; - - /** - * Depending on the client's failure handling strategy `failedChange` - * might contain the index of the change that failed. This property is - * only available if the client signals a `failureHandling` strategy - * in its client capabilities. - */ - failedChange?: uinteger; -} -``` -* error: code and message set in case an exception happens during the request. - -#### WillCreateFiles Request (:leftwards_arrow_with_hook:) - -The will create files request is sent from the client to the server before files are actually created as long as the creation is triggered from within the client either by a user action or by applying a workspace edit. The request can return a WorkspaceEdit which will be applied to workspace before the files are created. Please note that clients might drop results if computing the edit took too long or if a server constantly fails on this request. This is done to keep creates fast and reliable. - -_Client Capability_: -* property name (optional): `workspace.fileOperations.willCreate` -* property type: `boolean` - -The capability indicates that the client supports sending `workspace/willCreateFiles` requests. - -_Server Capability_: -* property name (optional): `workspace.fileOperations.willCreate` -* property type: `FileOperationRegistrationOptions` where `FileOperationRegistrationOptions` is defined as follows: - -
- -```typescript -/** - * The options to register for file operations. - * - * @since 3.16.0 - */ -interface FileOperationRegistrationOptions { - /** - * The actual filters. - */ - filters: FileOperationFilter[]; -} -``` - -
- -```typescript -/** - * A pattern kind describing if a glob pattern matches a file a folder or - * both. - * - * @since 3.16.0 - */ -export namespace FileOperationPatternKind { - /** - * The pattern matches a file only. - */ - export const file: 'file' = 'file'; - - /** - * The pattern matches a folder only. - */ - export const folder: 'folder' = 'folder'; -} - -export type FileOperationPatternKind = 'file' | 'folder'; -``` - -
- -```typescript -/** - * Matching options for the file operation pattern. - * - * @since 3.16.0 - */ -export interface FileOperationPatternOptions { - - /** - * The pattern should be matched ignoring casing. - */ - ignoreCase?: boolean; -} -``` - -
- -```typescript -/** - * A pattern to describe in which file operation requests or notifications - * the server is interested in. - * - * @since 3.16.0 - */ -interface FileOperationPattern { - /** - * The glob pattern to match. Glob patterns can have the following syntax: - * - `*` to match one or more characters in a path segment - * - `?` to match on one character in a path segment - * - `**` to match any number of path segments, including none - * - `{}` to group sub patterns into an OR expression. (e.g. `**​/*.{ts,js}` - * matches all TypeScript and JavaScript files) - * - `[]` to declare a range of characters to match in a path segment - * (e.g., `example.[0-9]` to match on `example.0`, `example.1`, …) - * - `[!...]` to negate a range of characters to match in a path segment - * (e.g., `example.[!0-9]` to match on `example.a`, `example.b`, but - * not `example.0`) - */ - glob: string; - - /** - * Whether to match files or folders with this pattern. - * - * Matches both if undefined. - */ - matches?: FileOperationPatternKind; - - /** - * Additional options used during matching. - */ - options?: FileOperationPatternOptions; -} -``` - -
- -```typescript -/** - * A filter to describe in which file operation requests or notifications - * the server is interested in. - * - * @since 3.16.0 - */ -export interface FileOperationFilter { - - /** - * A Uri like `file` or `untitled`. - */ - scheme?: string; - - /** - * The actual file operation pattern. - */ - pattern: FileOperationPattern; -} -``` - -The capability indicates that the server is interested in receiving `workspace/willCreateFiles` requests. - -_Registration Options_: none - -_Request_: -* method: 'workspace/willCreateFiles' -* params: `CreateFilesParams` defined as follows: - -
- -```typescript -/** - * The parameters sent in notifications/requests for user-initiated creation - * of files. - * - * @since 3.16.0 - */ -export interface CreateFilesParams { - - /** - * An array of all files/folders created in this operation. - */ - files: FileCreate[]; -} -``` - -
- -```typescript -/** - * Represents information on a file/folder create. - * - * @since 3.16.0 - */ -export interface FileCreate { - - /** - * A file:// URI for the location of the file/folder being created. - */ - uri: string; -} -``` - -_Response_: -* result:`WorkspaceEdit` \| `null` -* error: code and message set in case an exception happens during the `willCreateFiles` request. - -#### DidCreateFiles Notification (:arrow_right:) - -The did create files notification is sent from the client to the server when files were created from within the client. - -_Client Capability_: -* property name (optional): `workspace.fileOperations.didCreate` -* property type: `boolean` - -The capability indicates that the client supports sending `workspace/didCreateFiles` notifications. - -_Server Capability_: -* property name (optional): `workspace.fileOperations.didCreate` -* property type: `FileOperationRegistrationOptions` - -The capability indicates that the server is interested in receiving `workspace/didCreateFiles` notifications. - -_Notification_: -* method: 'workspace/didCreateFiles' -* params: `CreateFilesParams` - -#### WillRenameFiles Request (:leftwards_arrow_with_hook:) - -The will rename files request is sent from the client to the server before files are actually renamed as long as the rename is triggered from within the client either by a user action or by applying a workspace edit. The request can return a WorkspaceEdit which will be applied to workspace before the files are renamed. Please note that clients might drop results if computing the edit took too long or if a server constantly fails on this request. This is done to keep renames fast and reliable. - -_Client Capability_: -* property name (optional): `workspace.fileOperations.willRename` -* property type: `boolean` - -The capability indicates that the client supports sending `workspace/willRenameFiles` requests. - -_Server Capability_: -* property name (optional): `workspace.fileOperations.willRename` -* property type: `FileOperationRegistrationOptions` - -The capability indicates that the server is interested in receiving `workspace/willRenameFiles` requests. - -_Registration Options_: none - -_Request_: -* method: 'workspace/willRenameFiles' -* params: `RenameFilesParams` defined as follows: - -
- -```typescript -/** - * The parameters sent in notifications/requests for user-initiated renames - * of files. - * - * @since 3.16.0 - */ -export interface RenameFilesParams { - - /** - * An array of all files/folders renamed in this operation. When a folder - * is renamed, only the folder will be included, and not its children. - */ - files: FileRename[]; -} -``` - -
- -```typescript -/** - * Represents information on a file/folder rename. - * - * @since 3.16.0 - */ -export interface FileRename { - - /** - * A file:// URI for the original location of the file/folder being renamed. - */ - oldUri: string; - - /** - * A file:// URI for the new location of the file/folder being renamed. - */ - newUri: string; -} -``` - -_Response_: -* result:`WorkspaceEdit` \| `null` -* error: code and message set in case an exception happens during the `workspace/willRenameFiles` request. - -#### DidRenameFiles Notification (:arrow_right:) - -The did rename files notification is sent from the client to the server when files were renamed from within the client. - -_Client Capability_: -* property name (optional): `workspace.fileOperations.didRename` -* property type: `boolean` - -The capability indicates that the client supports sending `workspace/didRenameFiles` notifications. - -_Server Capability_: -* property name (optional): `workspace.fileOperations.didRename` -* property type: `FileOperationRegistrationOptions` - -The capability indicates that the server is interested in receiving `workspace/didRenameFiles` notifications. - -_Notification_: -* method: 'workspace/didRenameFiles' -* params: `RenameFilesParams` - -#### WillDeleteFiles Request (:leftwards_arrow_with_hook:) - -The will delete files request is sent from the client to the server before files are actually deleted as long as the deletion is triggered from within the client either by a user action or by applying a workspace edit. The request can return a WorkspaceEdit which will be applied to workspace before the files are deleted. Please note that clients might drop results if computing the edit took too long or if a server constantly fails on this request. This is done to keep deletes fast and reliable. - -_Client Capability_: -* property name (optional): `workspace.fileOperations.willDelete` -* property type: `boolean` - -The capability indicates that the client supports sending `workspace/willDeleteFiles` requests. - -_Server Capability_: -* property name (optional): `workspace.fileOperations.willDelete` -* property type: `FileOperationRegistrationOptions` - -The capability indicates that the server is interested in receiving `workspace/willDeleteFiles` requests. - -_Registration Options_: none - -_Request_: -* method: `workspace/willDeleteFiles` -* params: `DeleteFilesParams` defined as follows: - -
- -```typescript -/** - * The parameters sent in notifications/requests for user-initiated deletes - * of files. - * - * @since 3.16.0 - */ -export interface DeleteFilesParams { - - /** - * An array of all files/folders deleted in this operation. - */ - files: FileDelete[]; -} -``` - -
- -```typescript -/** - * Represents information on a file/folder delete. - * - * @since 3.16.0 - */ -export interface FileDelete { - - /** - * A file:// URI for the location of the file/folder being deleted. - */ - uri: string; -} -``` - -_Response_: -* result:`WorkspaceEdit` \| `null` -* error: code and message set in case an exception happens during the `workspace/willDeleteFiles` request. - -#### DidDeleteFiles Notification (:arrow_right:) - -The did delete files notification is sent from the client to the server when files were deleted from within the client. - -_Client Capability_: -* property name (optional): `workspace.fileOperations.didDelete` -* property type: `boolean` - -The capability indicates that the client supports sending `workspace/didDeleteFiles` notifications. - -_Server Capability_: -* property name (optional): `workspace.fileOperations.didDelete` -* property type: `FileOperationRegistrationOptions` - -The capability indicates that the server is interested in receiving `workspace/didDeleteFiles` notifications. - -_Notification_: -* method: 'workspace/didDeleteFiles' -* params: `DeleteFilesParams` - -#### Text Document Synchronization - -Client support for `textDocument/didOpen`, `textDocument/didChange` and `textDocument/didClose` notifications is mandatory in the protocol and clients can not opt out supporting them. This includes both full and incremental synchronization in the `textDocument/didChange` notification. In addition a server must either implement all three of them or none. Their capabilities are therefore controlled via a combined client and server capability. Opting out of text document synchronization makes only sense if the documents shown by the client are read only. Otherwise the server might receive request for documents, for which the content is managed in the client (e.g. they might have changed). - -_Client Capability_: -* property path (optional): `textDocument.synchronization.dynamicRegistration` -* property type: `boolean` - -Controls whether text document synchronization supports dynamic registration. - -_Server Capability_: -* property path (optional): `textDocumentSync` -* property type: `TextDocumentSyncKind | TextDocumentSyncOptions`. The below definition of the `TextDocumentSyncOptions` only covers the properties specific to the open, change and close notifications. A complete definition covering all properties can be found [here](#textDocument_didClose): - -
- -```typescript -/** - * Defines how the host (editor) should sync document changes to the language - * server. - */ -export namespace TextDocumentSyncKind { - /** - * Documents should not be synced at all. - */ - export const None = 0; - - /** - * Documents are synced by always sending the full content - * of the document. - */ - export const Full = 1; - - /** - * Documents are synced by sending the full content on open. - * After that only incremental updates to the document are - * send. - */ - export const Incremental = 2; -} -``` - -
- -```typescript -export interface TextDocumentSyncOptions { - /** - * Open and close notifications are sent to the server. If omitted open - * close notification should not be sent. - */ - openClose?: boolean; - - /** - * Change notifications are sent to the server. See - * TextDocumentSyncKind.None, TextDocumentSyncKind.Full and - * TextDocumentSyncKind.Incremental. If omitted it defaults to - * TextDocumentSyncKind.None. - */ - change?: TextDocumentSyncKind; -} -``` - -#### DidOpenTextDocument Notification (:arrow_right:) - -The document open notification is sent from the client to the server to signal newly opened text documents. The document's content is now managed by the client and the server must not try to read the document's content using the document's Uri. Open in this sense means it is managed by the client. It doesn't necessarily mean that its content is presented in an editor. An open notification must not be sent more than once without a corresponding close notification send before. This means open and close notification must be balanced and the max open count for a particular textDocument is one. Note that a server's ability to fulfill requests is independent of whether a text document is open or closed. - -The `DidOpenTextDocumentParams` contain the language id the document is associated with. If the language id of a document changes, the client needs to send a `textDocument/didClose` to the server followed by a `textDocument/didOpen` with the new language id if the server handles the new language id as well. - -_Client Capability_: -See general synchronization [client capabilities](#textDocument_synchronization_cc). - -_Server Capability_: -See general synchronization [server capabilities](#textDocument_synchronization_sc). - -_Registration Options_: [`TextDocumentRegistrationOptions`](#textDocumentRegistrationOptions) - -_Notification_: -* method: 'textDocument/didOpen' -* params: `DidOpenTextDocumentParams` defined as follows: - -
- -```typescript -interface DidOpenTextDocumentParams { - /** - * The document that was opened. - */ - textDocument: TextDocumentItem; -} -``` - -#### DidChangeTextDocument Notification (:arrow_right:) - -The document change notification is sent from the client to the server to signal changes to a text document. Before a client can change a text document it must claim ownership of its content using the `textDocument/didOpen` notification. In 2.0 the shape of the params has changed to include proper version numbers. - -_Client Capability_: -See general synchronization [client capabilities](#textDocument_synchronization_cc). - -_Server Capability_: -See general synchronization [server capabilities](#textDocument_synchronization_sc). - -_Registration Options_: `TextDocumentChangeRegistrationOptions` defined as follows: - -
- -```typescript -/** - * Describe options to be used when registering for text document change events. - */ -export interface TextDocumentChangeRegistrationOptions - extends TextDocumentRegistrationOptions { - /** - * How documents are synced to the server. See TextDocumentSyncKind.Full - * and TextDocumentSyncKind.Incremental. - */ - syncKind: TextDocumentSyncKind; -} -``` - -_Notification_: -* method: `textDocument/didChange` -* params: `DidChangeTextDocumentParams` defined as follows: - -
- -```typescript -interface DidChangeTextDocumentParams { - /** - * The document that did change. The version number points - * to the version after all provided content changes have - * been applied. - */ - textDocument: VersionedTextDocumentIdentifier; - - /** - * The actual content changes. The content changes describe single state - * changes to the document. So if there are two content changes c1 (at - * array index 0) and c2 (at array index 1) for a document in state S then - * c1 moves the document from S to S' and c2 from S' to S''. So c1 is - * computed on the state S and c2 is computed on the state S'. - * - * To mirror the content of a document using change events use the following - * approach: - * - start with the same initial content - * - apply the 'textDocument/didChange' notifications in the order you - * receive them. - * - apply the `TextDocumentContentChangeEvent`s in a single notification - * in the order you receive them. - */ - contentChanges: TextDocumentContentChangeEvent[]; -} -``` - -
- -```typescript -/** - * An event describing a change to a text document. If range and rangeLength are - * omitted the new text is considered to be the full content of the document. - */ -export type TextDocumentContentChangeEvent = { - /** - * The range of the document that changed. - */ - range: Range; - - /** - * The optional length of the range that got replaced. - * - * @deprecated use range instead. - */ - rangeLength?: uinteger; - - /** - * The new text for the provided range. - */ - text: string; -} | { - /** - * The new text of the whole document. - */ - text: string; -}; -``` - -#### WillSaveTextDocument Notification (:arrow_right:) - -The document will save notification is sent from the client to the server before the document is actually saved. If a server has registered for open / close events clients should ensure that the document is open before a `willSave` notification is sent since clients can't change the content of a file without ownership transferal. - -_Client Capability_: -* property name (optional): `textDocument.synchronization.willSave` -* property type: `boolean` - -The capability indicates that the client supports `textDocument/willSave` notifications. - -_Server Capability_: -* property name (optional): `textDocumentSync.willSave` -* property type: `boolean` - -The capability indicates that the server is interested in `textDocument/willSave` notifications. - -_Registration Options_: `TextDocumentRegistrationOptions` - -_Notification_: -* method: 'textDocument/willSave' -* params: `WillSaveTextDocumentParams` defined as follows: - -
- -```typescript -/** - * The parameters send in a will save text document notification. - */ -export interface WillSaveTextDocumentParams { - /** - * The document that will be saved. - */ - textDocument: TextDocumentIdentifier; - - /** - * The 'TextDocumentSaveReason'. - */ - reason: TextDocumentSaveReason; -} -``` - -
- -```typescript -/** - * Represents reasons why a text document is saved. - */ -export namespace TextDocumentSaveReason { - - /** - * Manually triggered, e.g. by the user pressing save, by starting - * debugging, or by an API call. - */ - export const Manual = 1; - - /** - * Automatic after a delay. - */ - export const AfterDelay = 2; - - /** - * When the editor lost focus. - */ - export const FocusOut = 3; -} - -export type TextDocumentSaveReason = 1 | 2 | 3; -``` - -#### WillSaveWaitUntilTextDocument Request (:leftwards_arrow_with_hook:) - -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. If a server has registered for open / close events clients should ensure that the document is open before a `willSaveWaitUntil` notification is sent since clients can't change the content of a file without ownership transferal. - -_Client Capability_: -* property name (optional): `textDocument.synchronization.willSaveWaitUntil` -* property type: `boolean` - -The capability indicates that the client supports `textDocument/willSaveWaitUntil` requests. - -_Server Capability_: -* property name (optional): `textDocumentSync.willSaveWaitUntil` -* property type: `boolean` - -The capability indicates that the server is interested in `textDocument/willSaveWaitUntil` requests. - -_Registration Options_: `TextDocumentRegistrationOptions` - -_Request_: -* method: `textDocument/willSaveWaitUntil` -* params: `WillSaveTextDocumentParams` - -_Response_: -* result:[`TextEdit[]`](#textEdit) \| `null` -* error: code and message set in case an exception happens during the `textDocument/willSaveWaitUntil` request. - -#### DidSaveTextDocument Notification (:arrow_right:) - -The document save notification is sent from the client to the server when the document was saved in the client. - -_Client Capability_: -* property name (optional): `textDocument.synchronization.didSave` -* property type: `boolean` - -The capability indicates that the client supports `textDocument/didSave` notifications. - -_Server Capability_: -* property name (optional): `textDocumentSync.save` -* property type: `boolean | SaveOptions` where `SaveOptions` is defined as follows: - -
- -```typescript -export interface SaveOptions { - /** - * The client is supposed to include the content on save. - */ - includeText?: boolean; -} -``` - -The capability indicates that the server is interested in `textDocument/didSave` notifications. - -_Registration Options_: `TextDocumentSaveRegistrationOptions` defined as follows: - -
- -```typescript -export interface TextDocumentSaveRegistrationOptions - extends TextDocumentRegistrationOptions { - /** - * The client is supposed to include the content on save. - */ - includeText?: boolean; -} -``` - -_Notification_: -* method: `textDocument/didSave` -* params: `DidSaveTextDocumentParams` defined as follows: - -
- -```typescript -interface DidSaveTextDocumentParams { - /** - * The document that was saved. - */ - textDocument: TextDocumentIdentifier; - - /** - * Optional the content when saved. Depends on the includeText value - * when the save notification was requested. - */ - text?: string; -} -``` - -#### DidCloseTextDocument Notification (:arrow_right:) - -The document close notification is sent from the client to the server when the document got closed in the client. The document's master now exists where the document's Uri points to (e.g. if the document's Uri is a file Uri the master now exists on disk). As with the open notification the close notification is about managing the document's content. Receiving a close notification doesn't mean that the document was open in an editor before. A close notification requires a previous open notification to be sent. Note that a server's ability to fulfill requests is independent of whether a text document is open or closed. - -_Client Capability_: -See general synchronization [client capabilities](#textDocument_synchronization_cc). - -_Server Capability_: -See general synchronization [server capabilities](#textDocument_synchronization_sc). - -_Registration Options_: `TextDocumentRegistrationOptions` - -_Notification_: -* method: `textDocument/didClose` -* params: `DidCloseTextDocumentParams` defined as follows: - -
- -```typescript -interface DidCloseTextDocumentParams { - /** - * The document that was closed. - */ - textDocument: TextDocumentIdentifier; -} -``` - -The final structure of the `TextDocumentSyncClientCapabilities` and the `TextDocumentSyncOptions` server options look like this - -
- -```typescript -export interface TextDocumentSyncClientCapabilities { - /** - * Whether text document synchronization supports dynamic registration. - */ - dynamicRegistration?: boolean; - - /** - * The client supports sending will save notifications. - */ - willSave?: boolean; - - /** - * The client supports sending a will save request and - * waits for a response providing text edits which will - * be applied to the document before it is saved. - */ - willSaveWaitUntil?: boolean; - - /** - * The client supports did save notifications. - */ - didSave?: boolean; -} -``` - -
- -```typescript -/** - * Defines how the host (editor) should sync document changes to the language - * server. - */ -export namespace TextDocumentSyncKind { - /** - * Documents should not be synced at all. - */ - export const None = 0; - - /** - * Documents are synced by always sending the full content - * of the document. - */ - export const Full = 1; - - /** - * Documents are synced by sending the full content on open. - * After that only incremental updates to the document are - * send. - */ - export const Incremental = 2; -} - -export type TextDocumentSyncKind = 0 | 1 | 2; -``` - -
- -```typescript -export interface TextDocumentSyncOptions { - /** - * Open and close notifications are sent to the server. If omitted open - * close notification should not be sent. - */ - openClose?: boolean; - /** - * Change notifications are sent to the server. See - * TextDocumentSyncKind.None, TextDocumentSyncKind.Full and - * TextDocumentSyncKind.Incremental. If omitted it defaults to - * TextDocumentSyncKind.None. - */ - change?: TextDocumentSyncKind; - /** - * If present will save notifications are sent to the server. If omitted - * the notification should not be sent. - */ - willSave?: boolean; - /** - * If present will save wait until requests are sent to the server. If - * omitted the request should not be sent. - */ - willSaveWaitUntil?: boolean; - /** - * If present save notifications are sent to the server. If omitted the - * notification should not be sent. - */ - save?: boolean | SaveOptions; -} -``` - -#### PublishDiagnostics Notification (:arrow_left:) - -Diagnostics notification are sent from the server to the client to signal results of validation runs. - -Diagnostics are "owned" by the server so it is the server's responsibility to clear them if necessary. The following rule is used for VS Code servers that generate diagnostics: - -* if a language is single file only (for example HTML) then diagnostics are cleared by the server when the file is closed. Please note that open / close events don't necessarily reflect what the user sees in the user interface. These events are ownership events. So with the current version of the specification it is possible that problems are not cleared although the file is not visible in the user interface since the client has not closed the file yet. -* if a language has a project system (for example C#) diagnostics are not cleared when a file closes. When a project is opened all diagnostics for all files are recomputed (or read from a cache). - -When a file changes it is the server's responsibility to re-compute diagnostics and push them to the client. If the computed set is empty it has to push the empty array to clear former diagnostics. Newly pushed diagnostics always replace previously pushed diagnostics. There is no merging that happens on the client side. - -See also the [Diagnostic](#diagnostic) section. - -_Client Capability_: -* property name (optional): `textDocument.publishDiagnostics` -* property type: `PublishDiagnosticsClientCapabilities` defined as follows: - -
- -```typescript -export interface PublishDiagnosticsClientCapabilities { - /** - * Whether the clients accepts diagnostics with related information. - */ - relatedInformation?: boolean; - - /** - * Client supports the tag property to provide meta data about a diagnostic. - * Clients supporting tags have to handle unknown tags gracefully. - * - * @since 3.15.0 - */ - tagSupport?: { - /** - * The tags supported by the client. - */ - valueSet: DiagnosticTag[]; - }; - - /** - * Whether the client interprets the version property of the - * `textDocument/publishDiagnostics` notification's parameter. - * - * @since 3.15.0 - */ - versionSupport?: boolean; - - /** - * Client supports a codeDescription property - * - * @since 3.16.0 - */ - codeDescriptionSupport?: boolean; - - /** - * Whether code action supports the `data` property which is - * preserved between a `textDocument/publishDiagnostics` and - * `textDocument/codeAction` request. - * - * @since 3.16.0 - */ - dataSupport?: boolean; -} -``` - -_Notification_: -* method: `textDocument/publishDiagnostics` -* params: `PublishDiagnosticsParams` defined as follows: - -
- -```typescript -interface PublishDiagnosticsParams { - /** - * The URI for which diagnostic information is reported. - */ - uri: DocumentUri; - - /** - * Optional the version number of the document the diagnostics are published - * for. - * - * @since 3.15.0 - */ - version?: integer; - - /** - * An array of diagnostic information items. - */ - diagnostics: Diagnostic[]; -} -``` - -#### Completion Request (:leftwards_arrow_with_hook:) - -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/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 typical 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 parameter. The returned completion item should have the documentation property filled in. By default the request can only delay the computation of the `detail` and `documentation` properties. Since 3.16.0 the client -can signal that it can resolve more properties lazily. This is done using the `completionItem#resolveSupport` client capability which lists all properties that can be filled in during a 'completionItem/resolve' request. All other properties (usually `sortText`, `filterText`, `insertText` and `textEdit`) must be provided in the `textDocument/completion` response and must not be changed during resolve. - -The language server protocol uses the following model around completions: - -- to achieve consistency across languages and to honor different clients usually the client is responsible for filtering and sorting. This has also the advantage that client can experiment with different filter and sorting models. However servers can enforce different behavior by setting a `filterText` / `sortText` -- for speed clients should be able to filter an already received completion list if the user continues typing. Servers can opt out of this using a `CompletionList` and mark it as `isIncomplete`. - -A completion item provides additional means to influence filtering and sorting. They are expressed by either creating a `CompletionItem` with a `insertText` or with a `textEdit`. The two modes differ as follows: - -- **Completion item provides an insertText / label without a text edit**: in the model the client should filter against what the user has already typed using the word boundary rules of the language (e.g. resolving the word under the cursor position). The reason for this mode is that it makes it extremely easy for a server to implement a basic completion list and get it filtered on the client. - -- **Completion Item with text edits**: in this mode the server tells the client that it actually knows what it is doing. If you create a completion item with a text edit at the current cursor position no word guessing takes place and no filtering should happen. This mode can be combined with a sort text and filter text to customize two things. If the text edit is a replace edit then the range denotes the word used for filtering. If the replace changes the text it most likely makes sense to specify a filter text to be used. - -_Client Capability_: -* property name (optional): `textDocument.completion` -* property type: `CompletionClientCapabilities` defined as follows: - -
- -```typescript -export interface CompletionClientCapabilities { - /** - * Whether completion supports dynamic registration. - */ - dynamicRegistration?: boolean; - - /** - * The client supports the following `CompletionItem` specific - * capabilities. - */ - completionItem?: { - /** - * Client supports snippets as insert text. - * - * A snippet can define tab stops and placeholders with `$1`, `$2` - * and `${3:foo}`. `$0` defines the final tab stop, it defaults to - * the end of the snippet. Placeholders with equal identifiers are - * linked, that is typing in one will update others too. - */ - snippetSupport?: boolean; - - /** - * Client supports commit characters on a completion item. - */ - commitCharactersSupport?: boolean; - - /** - * Client supports the follow content formats for the documentation - * property. The order describes the preferred format of the client. - */ - documentationFormat?: MarkupKind[]; - - /** - * Client supports the deprecated property on a completion item. - */ - deprecatedSupport?: boolean; - - /** - * Client supports the preselect property on a completion item. - */ - preselectSupport?: boolean; - - /** - * Client supports the tag property on a completion item. Clients - * supporting tags have to handle unknown tags gracefully. Clients - * especially need to preserve unknown tags when sending a completion - * item back to the server in a resolve call. - * - * @since 3.15.0 - */ - tagSupport?: { - /** - * The tags supported by the client. - */ - valueSet: CompletionItemTag[]; - }; - - /** - * Client supports insert replace edit to control different behavior if - * a completion item is inserted in the text or should replace text. - * - * @since 3.16.0 - */ - insertReplaceSupport?: boolean; - - /** - * Indicates which properties a client can resolve lazily on a - * completion item. Before version 3.16.0 only the predefined properties - * `documentation` and `detail` could be resolved lazily. - * - * @since 3.16.0 - */ - resolveSupport?: { - /** - * The properties that a client can resolve lazily. - */ - properties: string[]; - }; - - /** - * The client supports the `insertTextMode` property on - * a completion item to override the whitespace handling mode - * as defined by the client (see `insertTextMode`). - * - * @since 3.16.0 - */ - insertTextModeSupport?: { - valueSet: InsertTextMode[]; - }; - - /** - * The client has support for completion item label - * details (see also `CompletionItemLabelDetails`). - * - * @since 3.17.0 - proposed state - */ - labelDetailsSupport?: boolean; - }; - - completionItemKind?: { - /** - * The completion item kind values the client supports. When this - * property exists the client also guarantees that it will - * handle values outside its set gracefully and falls back - * to a default value when unknown. - * - * If this property is not present the client only supports - * the completion items kinds from `Text` to `Reference` as defined in - * the initial version of the protocol. - */ - valueSet?: CompletionItemKind[]; - }; - - /** - * The client supports to send additional context information for a - * `textDocument/completion` request. - */ - contextSupport?: boolean; - - /** - * The client's default when the completion item doesn't provide a - * `insertTextMode` property. - * - * @since 3.17.0 - proposed state - */ - insertTextMode?: InsertTextMode; - - /** - * The client supports the following `CompletionList` specific - * capabilities. - * - * @since 3.17.0 - proposed state - */ - completionList?: { - /** - * The client supports the the following itemDefaults on - * a completion list. - * - * The value lists the supported property names of the - * `CompletionList.itemDefaults` object. If omitted - * no properties are supported. - * - * @since 3.17.0 - proposed state - */ - itemDefaults?: string[]; - } -} -``` - -_Server Capability_: -* property name (optional): `completionProvider` -* property type: `CompletionOptions` defined as follows: - -
- -```typescript -/** - * Completion options. - */ -export interface CompletionOptions extends WorkDoneProgressOptions { - /** - * Most tools trigger completion request automatically without explicitly - * requesting it using a keyboard shortcut (e.g. Ctrl+Space). Typically they - * do so when the user starts to type an identifier. For example if the user - * types `c` in a JavaScript file code complete will automatically pop up - * present `console` besides others as a completion item. Characters that - * make up identifiers don't need to be listed here. - * - * If code complete should automatically be trigger on characters not being - * valid inside an identifier (for example `.` in JavaScript) list them in - * `triggerCharacters`. - */ - triggerCharacters?: string[]; - - /** - * The list of all possible characters that commit a completion. This field - * can be used if clients don't support individual commit characters per - * completion item. See client capability - * `completion.completionItem.commitCharactersSupport`. - * - * If a server provides both `allCommitCharacters` and commit characters on - * an individual completion item the ones on the completion item win. - * - * @since 3.2.0 - */ - allCommitCharacters?: string[]; - - /** - * The server provides support to resolve additional - * information for a completion item. - */ - resolveProvider?: boolean; - - /** - * The server supports the following `CompletionItem` specific - * capabilities. - * - * @since 3.17.0 - proposed state - */ - completionItem?: { - /** - * The server has support for completion item label - * details (see also `CompletionItemLabelDetails`) when receiving - * a completion item in a resolve call. - * - * @since 3.17.0 - proposed state - */ - labelDetailsSupport?: boolean; - } -} -``` - -_Registration Options_: `CompletionRegistrationOptions` options defined as follows: - -
- -```typescript -export interface CompletionRegistrationOptions - extends TextDocumentRegistrationOptions, CompletionOptions { -} -``` - -_Request_: -* method: `textDocument/completion` -* params: `CompletionParams` defined as follows: - -
- -```typescript -export interface CompletionParams extends TextDocumentPositionParams, - WorkDoneProgressParams, PartialResultParams { - /** - * The completion context. This is only available if the client specifies - * to send this using the client capability - * `completion.contextSupport === true` - */ - context?: CompletionContext; -} -``` - -
- -```typescript -/** - * How a completion was triggered - */ -export namespace CompletionTriggerKind { - /** - * Completion was triggered by typing an identifier (24x7 code - * complete), manual invocation (e.g Ctrl+Space) or via API. - */ - export const Invoked: 1 = 1; - - /** - * Completion was triggered by a trigger character specified by - * the `triggerCharacters` properties of the - * `CompletionRegistrationOptions`. - */ - export const TriggerCharacter: 2 = 2; - - /** - * Completion was re-triggered as the current completion list is incomplete. - */ - export const TriggerForIncompleteCompletions: 3 = 3; -} -export type CompletionTriggerKind = 1 | 2 | 3; -``` - -
- -```typescript -/** - * Contains additional information about the context in which a completion - * request is triggered. - */ -export interface CompletionContext { - /** - * How the completion was triggered. - */ - triggerKind: CompletionTriggerKind; - - /** - * The trigger character (a single character) that has trigger code - * complete. Is undefined if - * `triggerKind !== CompletionTriggerKind.TriggerCharacter` - */ - triggerCharacter?: string; -} -``` - -_Response_: -* result: `CompletionItem[]` \| `CompletionList` \| `null`. If a `CompletionItem[]` is provided it is interpreted to be complete. So it is the same as `{ isIncomplete: false, items }` - -
- -```typescript -/** - * Represents a collection of [completion items](#CompletionItem) to be - * presented in the editor. - */ -export interface CompletionList { - /** - * This list is not complete. Further typing should result in recomputing - * this list. - * - * Recomputed lists have all their items replaced (not appended) in the - * incomplete completion sessions. - */ - isIncomplete: boolean; - - /** - * In many cases the items of an actual completion result share the same - * value for properties like `commitCharacters` or the range of a text - * edit. A completion list can therefore define item defaults which will - * be used if a completion item itself doesn't specify the value. - * - * If a completion list specifies a default value and a completion item - * also specifies a corresponding value the one from the item is used. - * - * Servers are only allowed to return default values if the client - * signals support for this via the `completionList.itemDefaults` - * capability. - * - * @since 3.17.0 - proposed state - */ - itemDefaults?: { - /** - * A default commit character set. - * - * @since 3.17.0 - proposed state - */ - commitCharacters?: string[]; - - /** - * A default edit range - * - * @since 3.17.0 - proposed state - */ - editRange?: Range | { - insert: Range; - replace: Range; - }; - - /** - * A default insert text format - * - * @since 3.17.0 - proposed state - */ - insertTextFormat?: InsertTextFormat; - - /** - * A default insert text mode - * - * @since 3.17.0 - proposed state - */ - insertTextMode?: InsertTextMode; - } - - /** - * The completion items. - */ - items: CompletionItem[]; -} -``` - -
- -```typescript -/** - * Defines whether the insert text in a completion item should be interpreted as - * plain text or a snippet. - */ -export namespace InsertTextFormat { - /** - * The primary text to be inserted is treated as a plain string. - */ - export const PlainText = 1; - - /** - * The primary text to be inserted is treated as a snippet. - * - * A snippet can define tab stops and placeholders with `$1`, `$2` - * and `${3:foo}`. `$0` defines the final tab stop, it defaults to - * the end of the snippet. Placeholders with equal identifiers are linked, - * that is typing in one will update others too. - */ - export const Snippet = 2; -} - -export type InsertTextFormat = 1 | 2; -``` - -
- -```typescript -/** - * Completion item tags are extra annotations that tweak the rendering of a - * completion item. - * - * @since 3.15.0 - */ -export namespace CompletionItemTag { - /** - * Render a completion as obsolete, usually using a strike-out. - */ - export const Deprecated = 1; -} - -export type CompletionItemTag = 1; -``` - -
- -```typescript -/** - * A special text edit to provide an insert and a replace operation. - * - * @since 3.16.0 - */ -export interface InsertReplaceEdit { - /** - * The string to be inserted. - */ - newText: string; - - /** - * The range if the insert is requested - */ - insert: Range; - - /** - * The range if the replace is requested. - */ - replace: Range; -} -``` - -
- -```typescript -/** - * How whitespace and indentation is handled during completion - * item insertion. - * - * @since 3.16.0 - */ -export namespace InsertTextMode { - /** - * The insertion or replace strings is taken as it is. If the - * value is multi line the lines below the cursor will be - * inserted using the indentation defined in the string value. - * The client will not apply any kind of adjustments to the - * string. - */ - export const asIs: 1 = 1; - - /** - * The editor adjusts leading whitespace of new lines so that - * they match the indentation up to the cursor of the line for - * which the item is accepted. - * - * Consider a line like this: <2tabs><3tabs>foo. Accepting a - * multi line completion item is indented using 2 tabs and all - * following lines inserted will be indented using 2 tabs as well. - */ - export const adjustIndentation: 2 = 2; -} - -export type InsertTextMode = 1 | 2; -``` - -
- -```typescript -/** - * Additional details for a completion item label. - * - * @since 3.17.0 - proposed state - */ -export interface CompletionItemLabelDetails { - - /** - * An optional string which is rendered less prominently directly after - * {@link CompletionItem.label label}, without any spacing. Should be - * used for function signatures or type annotations. - */ - detail?: string; - - /** - * An optional string which is rendered less prominently after - * {@link CompletionItemLabelDetails.detail}. Should be used for fully qualified - * names or file path. - */ - description?: string; -} -``` - -
- -```typescript -export interface CompletionItem { - - /** - * The label of this completion item. - * - * The label property is also by default the text that - * is inserted when selecting this completion. - * - * If label details are provided the label itself should - * be an unqualified name of the completion item. - */ - label: string; - - /** - * Additional details for the label - * - * @since 3.17.0 - proposed state - */ - labelDetails?: CompletionItemLabelDetails; - - - /** - * The kind of this completion item. Based of the kind - * an icon is chosen by the editor. The standardized set - * of available values is defined in `CompletionItemKind`. - */ - kind?: CompletionItemKind; - - /** - * Tags for this completion item. - * - * @since 3.15.0 - */ - tags?: CompletionItemTag[]; - - /** - * A human-readable string with additional information - * about this item, like type or symbol information. - */ - detail?: string; - - /** - * A human-readable string that represents a doc-comment. - */ - documentation?: string | MarkupContent; - - /** - * Indicates if this item is deprecated. - * - * @deprecated Use `tags` instead if supported. - */ - deprecated?: boolean; - - /** - * Select this item when showing. - * - * *Note* that only one completion item can be selected and that the - * tool / client decides which item that is. The rule is that the *first* - * item of those that match best is selected. - */ - preselect?: boolean; - - /** - * A string that should be used when comparing this item - * with other items. When `falsy` the label is used - * as the sort text for this item. - */ - sortText?: string; - - /** - * A string that should be used when filtering a set of - * completion items. When `falsy` the label is used as the - * filter text for this item. - */ - filterText?: string; - - /** - * A string that should be inserted into a document when selecting - * this completion. When `falsy` the label is used as the insert text - * for this item. - * - * The `insertText` is subject to interpretation by the client side. - * Some tools might not take the string literally. For example - * VS Code when code complete is requested in this example - * `con` and a completion item with an `insertText` of - * `console` is provided it will only insert `sole`. Therefore it is - * recommended to use `textEdit` instead since it avoids additional client - * side interpretation. - */ - insertText?: string; - - /** - * The format of the insert text. The format applies to both the - * `insertText` property and the `newText` property of a provided - * `textEdit`. If omitted defaults to `InsertTextFormat.PlainText`. - * - * Please note that the insertTextFormat doesn't apply to - * `additionalTextEdits`. - */ - insertTextFormat?: InsertTextFormat; - - /** - * How whitespace and indentation is handled during completion - * item insertion. If not provided the client's default value depends on - * the `textDocument.completion.insertTextMode` client capability. - * - * @since 3.16.0 - * @since 3.17.0 - support for `textDocument.completion.insertTextMode` - */ - insertTextMode?: InsertTextMode; - - /** - * An edit which is applied to a document when selecting this completion. - * When an edit is provided the value of `insertText` is ignored. - * - * *Note:* The range of the edit must be a single line range and it must - * contain the position at which completion has been requested. - * - * Most editors support two different operations when accepting a completion - * item. One is to insert a completion text and the other is to replace an - * existing text with a completion text. Since this can usually not be - * predetermined by a server it can report both ranges. Clients need to - * signal support for `InsertReplaceEdit`s via the - * `textDocument.completion.completionItem.insertReplaceSupport` client - * capability property. - * - * *Note 1:* The text edit's range as well as both ranges from an insert - * replace edit must be a [single line] and they must contain the position - * at which completion has been requested. - * *Note 2:* If an `InsertReplaceEdit` is returned the edit's insert range - * must be a prefix of the edit's replace range, that means it must be - * contained and starting at the same position. - * - * @since 3.16.0 additional type `InsertReplaceEdit` - */ - textEdit?: TextEdit | InsertReplaceEdit; - - /** - * An optional array of additional text edits that are applied when - * selecting this completion. Edits must not overlap (including the same - * insert position) with the main edit nor with themselves. - * - * Additional text edits should be used to change text unrelated to the - * current cursor position (for example adding an import statement at the - * top of the file if the completion item will insert an unqualified type). - */ - additionalTextEdits?: TextEdit[]; - - /** - * An optional set of characters that when pressed while this completion is - * active will accept it first and then type that character. *Note* that all - * commit characters should have `length=1` and that superfluous characters - * will be ignored. - */ - commitCharacters?: string[]; - - /** - * An optional command that is executed *after* inserting this completion. - * *Note* that additional modifications to the current document should be - * described with the additionalTextEdits-property. - */ - command?: Command; - - /** - * A data entry field that is preserved on a completion item between - * a completion and a completion resolve request. - */ - data?: LSPAny; -} -``` - -
- -```typescript -/** - * The kind of a completion entry. - */ -export namespace CompletionItemKind { - export const Text = 1; - export const Method = 2; - export const Function = 3; - export const Constructor = 4; - export const Field = 5; - export const Variable = 6; - export const Class = 7; - export const Interface = 8; - export const Module = 9; - export const Property = 10; - export const Unit = 11; - export const Value = 12; - export const Enum = 13; - export const Keyword = 14; - export const Snippet = 15; - export const Color = 16; - export const File = 17; - export const Reference = 18; - export const Folder = 19; - export const EnumMember = 20; - export const Constant = 21; - export const Struct = 22; - export const Event = 23; - export const Operator = 24; - export const TypeParameter = 25; -} -``` -* partial result: `CompletionItem[]` or `CompletionList` followed by `CompletionItem[]`. If the first provided result item is of type `CompletionList` subsequent partial results of `CompletionItem[]` add to the `items` property of the `CompletionList`. -* error: code and message set in case an exception happens during the completion request. - -Completion items support snippets (see `InsertTextFormat.Snippet`). The snippet format is as follows: - -##### Snippet Syntax - -The `body` of a snippet can use special constructs to control cursors and the text being inserted. The following are supported features and their syntaxes: - -##### Tab stops - -With tab stops, you can make the editor cursor move inside a snippet. Use `$1`, `$2` to specify cursor locations. The number is the order in which tab stops will be visited, whereas `$0` denotes the final cursor position. Multiple tab stops are linked and updated in sync. - -##### Placeholders - -Placeholders are tab stops with values, like `${1:foo}`. The placeholder text will be inserted and selected such that it can be easily changed. Placeholders can be nested, like `${1:another ${2:placeholder}}`. - -##### Choice - -Placeholders can have choices as values. The syntax is a comma separated enumeration of values, enclosed with the pipe-character, for example `${1|one,two,three|}`. When the snippet is inserted and the placeholder selected, choices will prompt the user to pick one of the values. - -##### Variables - -With `$name` or `${name:default}` you can insert the value of a variable. When a variable isn’t set, its *default* or the empty string is inserted. When a variable is unknown (that is, its name isn’t defined) the name of the variable is inserted and it is transformed into a placeholder. - -The following variables can be used: - -* `TM_SELECTED_TEXT` The currently selected text or the empty string -* `TM_CURRENT_LINE` The contents of the current line -* `TM_CURRENT_WORD` The contents of the word under cursor or the empty string -* `TM_LINE_INDEX` The zero-index based line number -* `TM_LINE_NUMBER` The one-index based line number -* `TM_FILENAME` The filename of the current document -* `TM_FILENAME_BASE` The filename of the current document without its extensions -* `TM_DIRECTORY` The directory of the current document -* `TM_FILEPATH` The full file path of the current document - -##### Variable Transforms - -Transformations allow you to modify the value of a variable before it is inserted. The definition of a transformation consists of three parts: - -1. A [regular expression](#regExp) that is matched against the value of a variable, or the empty string when the variable cannot be resolved. -2. A "format string" that allows to reference matching groups from the regular expression. The format string allows for conditional inserts and simple modifications. -3. Options that are passed to the regular expression. - -The following example inserts the name of the current file without its ending, so from `foo.txt` it makes `foo`. - -``` -${TM_FILENAME/(.*)\..+$/$1/} - | | | | - | | | |-> no options - | | | - | | |-> references the contents of the first - | | capture group - | | - | |-> regex to capture everything before - | the final `.suffix` - | - |-> resolves to the filename -``` - -##### Grammar - -Below is the EBNF ([extended Backus-Naur form](https://en.wikipedia.org/wiki/Extended_Backus-Naur_form)) for snippets. With `\` (backslash), you can escape `$`, `}` and `\`. Within choice elements, the backslash also escapes comma and pipe characters. - -``` -any ::= tabstop | placeholder | choice | variable | text -tabstop ::= '$' int | '${' int '}' -placeholder ::= '${' int ':' any '}' -choice ::= '${' int '|' text (',' text)* '|}' -variable ::= '$' var | '${' var }' - | '${' var ':' any '}' - | '${' var '/' regex '/' (format | text)+ '/' options '}' -format ::= '$' int | '${' int '}' - | '${' int ':' '/upcase' | '/downcase' | '/capitalize' '}' - | '${' int ':+' if '}' - | '${' int ':?' if ':' else '}' - | '${' int ':-' else '}' | '${' int ':' else '}' -regex ::= Regular Expression value (ctor-string) -options ::= Regular Expression option (ctor-options) -var ::= [_a-zA-Z] [_a-zA-Z0-9]* -int ::= [0-9]+ -text ::= .* -``` - -#### Completion Item Resolve Request (:leftwards_arrow_with_hook:) - -The request is sent from the client to the server to resolve additional information for a given completion item. - -_Request_: -* method: `completionItem/resolve` -* params: `CompletionItem` - -_Response_: -* result: `CompletionItem` -* error: code and message set in case an exception happens during the completion resolve request. - -#### Hover Request (:leftwards_arrow_with_hook:) - -The hover request is sent from the client to the server to request hover information at a given text document position. - -_Client Capability_: -* property name (optional): `textDocument.hover` -* property type: `HoverClientCapabilities` defined as follows: - -
- -```typescript -export interface HoverClientCapabilities { - /** - * Whether hover supports dynamic registration. - */ - dynamicRegistration?: boolean; - - /** - * Client supports the follow content formats if the content - * property refers to a `literal of type MarkupContent`. - * The order describes the preferred format of the client. - */ - contentFormat?: MarkupKind[]; -} -``` - -_Server Capability_: -* property name (optional): `hoverProvider` -* property type: `boolean | HoverOptions` where `HoverOptions` is defined as follows: - -
- -```typescript -export interface HoverOptions extends WorkDoneProgressOptions { -} -``` - -_Registration Options_: `HoverRegistrationOptions` defined as follows: - -
- -```typescript -export interface HoverRegistrationOptions - extends TextDocumentRegistrationOptions, HoverOptions { -} -``` - -_Request_: -* method: `textDocument/hover` -* params: `HoverParams` defined as follows: - -
- -```typescript -export interface HoverParams extends TextDocumentPositionParams, - WorkDoneProgressParams { -} -``` - -_Response_: -* result: `Hover` \| `null` defined as follows: - -
- -```typescript -/** - * The result of a hover request. - */ -export interface Hover { - /** - * The hover's content - */ - contents: MarkedString | MarkedString[] | MarkupContent; - - /** - * An optional range is a range inside a text document - * that is used to visualize a hover, e.g. by changing the background color. - */ - range?: Range; -} -``` - -Where `MarkedString` is defined as follows: - -
- -```typescript -/** - * MarkedString can be used to render human readable text. It is either a - * markdown string or a code-block that provides a language and a code snippet. - * The language identifier is semantically equal to the optional language - * identifier in fenced code blocks in GitHub issues. - * - * The pair of a language and a value is an equivalent to markdown: - * ```${language} - * ${value} - * ``` - * - * Note that markdown strings will be sanitized - that means html will be - * escaped. - * - * @deprecated use MarkupContent instead. - */ -type MarkedString = string | { language: string; value: string }; -``` - -* error: code and message set in case an exception happens during the hover request. - -#### Signature Help Request (:leftwards_arrow_with_hook:) - -The signature help request is sent from the client to the server to request signature information at a given cursor position. - -_Client Capability_: -* property name (optional): `textDocument.signatureHelp` -* property type: `SignatureHelpClientCapabilities` defined as follows: - -
- -```typescript -export interface SignatureHelpClientCapabilities { - /** - * Whether signature help supports dynamic registration. - */ - dynamicRegistration?: boolean; - - /** - * The client supports the following `SignatureInformation` - * specific properties. - */ - signatureInformation?: { - /** - * Client supports the follow content formats for the documentation - * property. The order describes the preferred format of the client. - */ - documentationFormat?: MarkupKind[]; - - /** - * Client capabilities specific to parameter information. - */ - parameterInformation?: { - /** - * The client supports processing label offsets instead of a - * simple label string. - * - * @since 3.14.0 - */ - labelOffsetSupport?: boolean; - }; - - /** - * The client supports the `activeParameter` property on - * `SignatureInformation` literal. - * - * @since 3.16.0 - */ - activeParameterSupport?: boolean; - }; - - /** - * The client supports to send additional context information for a - * `textDocument/signatureHelp` request. A client that opts into - * contextSupport will also support the `retriggerCharacters` on - * `SignatureHelpOptions`. - * - * @since 3.15.0 - */ - contextSupport?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `signatureHelpProvider` -* property type: `SignatureHelpOptions` defined as follows: - -
- -```typescript -export interface SignatureHelpOptions extends WorkDoneProgressOptions { - /** - * The characters that trigger signature help - * automatically. - */ - triggerCharacters?: string[]; - - /** - * List of characters that re-trigger signature help. - * - * These trigger characters are only active when signature help is already - * showing. All trigger characters are also counted as re-trigger - * characters. - * - * @since 3.15.0 - */ - retriggerCharacters?: string[]; -} -``` - -_Registration Options_: `SignatureHelpRegistrationOptions` defined as follows: - -
- -```typescript -export interface SignatureHelpRegistrationOptions - extends TextDocumentRegistrationOptions, SignatureHelpOptions { -} -``` - -_Request_: -* method: `textDocument/signatureHelp` -* params: `SignatureHelpParams` defined as follows: +#### Text Document Synchronization -
+Client support for `textDocument/didOpen`, `textDocument/didChange` and `textDocument/didClose` notifications is mandatory in the protocol and clients can not opt out supporting them. This includes both full and incremental synchronization in the `textDocument/didChange` notification. In addition a server must either implement all three of them or none. Their capabilities are therefore controlled via a combined client and server capability. Opting out of text document synchronization makes only sense if the documents shown by the client are read only. Otherwise the server might receive request for documents, for which the content is managed in the client (e.g. they might have changed). -```typescript -export interface SignatureHelpParams extends TextDocumentPositionParams, - WorkDoneProgressParams { - /** - * The signature help context. This is only available if the client - * specifies to send this using the client capability - * `textDocument.signatureHelp.contextSupport === true` - * - * @since 3.15.0 - */ - context?: SignatureHelpContext; -} -``` +_Client Capability_: +* property path (optional): `textDocument.synchronization.dynamicRegistration` +* property type: `boolean` -
+Controls whether text document synchronization supports dynamic registration. -```typescript -/** - * How a signature help was triggered. - * - * @since 3.15.0 - */ -export namespace SignatureHelpTriggerKind { - /** - * Signature help was invoked manually by the user or by a command. - */ - export const Invoked: 1 = 1; - /** - * Signature help was triggered by a trigger character. - */ - export const TriggerCharacter: 2 = 2; - /** - * Signature help was triggered by the cursor moving or by the document - * content changing. - */ - export const ContentChange: 3 = 3; -} -export type SignatureHelpTriggerKind = 1 | 2 | 3; -``` +_Server Capability_: +* property path (optional): `textDocumentSync` +* property type: `TextDocumentSyncKind | TextDocumentSyncOptions`. The below definition of the `TextDocumentSyncOptions` only covers the properties specific to the open, change and close notifications. A complete definition covering all properties can be found [here](#textDocument_didClose): -
+
```typescript /** - * Additional information about the context in which a signature help request - * was triggered. - * - * @since 3.15.0 + * Defines how the host (editor) should sync document changes to the language + * server. */ -export interface SignatureHelpContext { - /** - * Action that caused signature help to be triggered. - */ - triggerKind: SignatureHelpTriggerKind; - +export namespace TextDocumentSyncKind { /** - * Character that caused signature help to be triggered. - * - * This is undefined when triggerKind !== - * SignatureHelpTriggerKind.TriggerCharacter + * Documents should not be synced at all. */ - triggerCharacter?: string; + export const None = 0; /** - * `true` if signature help was already showing when it was triggered. - * - * Retriggers occur when the signature help is already active and can be - * caused by actions such as typing a trigger character, a cursor move, or - * document content changes. + * Documents are synced by always sending the full content + * of the document. */ - isRetrigger: boolean; + export const Full = 1; /** - * The currently active `SignatureHelp`. - * - * The `activeSignatureHelp` has its `SignatureHelp.activeSignature` field - * updated based on the user navigating through available signatures. + * Documents are synced by sending the full content on open. + * After that only incremental updates to the document are + * send. */ - activeSignatureHelp?: SignatureHelp; + export const Incremental = 2; } ``` -_Response_: -* result: `SignatureHelp` \| `null` defined as follows: - -
+
```typescript -/** - * Signature help represents the signature of something - * callable. There can be multiple signature but only one - * active and only one active parameter. - */ -export interface SignatureHelp { - /** - * One or more signatures. If no signatures are available the signature help - * request should return `null`. - */ - signatures: SignatureInformation[]; - +export interface TextDocumentSyncOptions { /** - * The active signature. If omitted or the value lies outside the - * range of `signatures` the value defaults to zero or is ignore if - * the `SignatureHelp` as no signatures. - * - * Whenever possible implementors should make an active decision about - * the active signature and shouldn't rely on a default value. - * - * In future version of the protocol this property might become - * mandatory to better express this. + * Open and close notifications are sent to the server. If omitted open + * close notification should not be sent. */ - activeSignature?: uinteger; + openClose?: boolean; /** - * The active parameter of the active signature. If omitted or the value - * lies outside the range of `signatures[activeSignature].parameters` - * defaults to 0 if the active signature has parameters. If - * the active signature has no parameters it is ignored. - * In future version of the protocol this property might become - * mandatory to better express the active parameter if the - * active signature does have any. + * Change notifications are sent to the server. See + * TextDocumentSyncKind.None, TextDocumentSyncKind.Full and + * TextDocumentSyncKind.Incremental. If omitted it defaults to + * TextDocumentSyncKind.None. */ - activeParameter?: uinteger; + change?: TextDocumentSyncKind; } ``` -
+{% include_relative textDocument/didOpen.md %} +{% include_relative textDocument/didChange.md %} +{% include_relative textDocument/willSave.md %} +{% include_relative textDocument/willSaveWaitUntil.md %} +{% include_relative textDocument/didSave.md %} +{% include_relative textDocument/didClose.md %} + +The final structure of the `TextDocumentSyncClientCapabilities` and the `TextDocumentSyncOptions` server options look like this + +
```typescript -/** - * Represents the signature of something callable. A signature - * can have a label, like a function-name, a doc-comment, and - * a set of parameters. - */ -export interface SignatureInformation { +export interface TextDocumentSyncClientCapabilities { /** - * The label of this signature. Will be shown in - * the UI. + * Whether text document synchronization supports dynamic registration. */ - label: string; + dynamicRegistration?: boolean; /** - * The human-readable doc-comment of this signature. Will be shown - * in the UI but can be omitted. + * The client supports sending will save notifications. */ - documentation?: string | MarkupContent; + willSave?: boolean; /** - * The parameters of this signature. + * The client supports sending a will save request and + * waits for a response providing text edits which will + * be applied to the document before it is saved. */ - parameters?: ParameterInformation[]; + willSaveWaitUntil?: boolean; /** - * The index of the active parameter. - * - * If provided, this is used in place of `SignatureHelp.activeParameter`. - * - * @since 3.16.0 + * The client supports did save notifications. */ - activeParameter?: uinteger; + didSave?: boolean; } ``` -
+
```typescript /** - * Represents a parameter of a callable-signature. A parameter can - * have a label and a doc-comment. + * Defines how the host (editor) should sync document changes to the language + * server. */ -export interface ParameterInformation { - - /** - * The label of this parameter information. - * - * Either a string or an inclusive start and exclusive end offsets within - * its containing signature label. (see SignatureInformation.label). The - * offsets are based on a UTF-16 string representation as `Position` and - * `Range` does. - * - * *Note*: a label of type string should be a substring of its containing - * signature label. Its intended use case is to highlight the parameter - * label part in the `SignatureInformation.label`. - */ - label: string | [uinteger, uinteger]; - +export namespace TextDocumentSyncKind { /** - * The human-readable doc-comment of this parameter. Will be shown - * in the UI but can be omitted. + * Documents should not be synced at all. */ - documentation?: string | MarkupContent; -} -``` - -* error: code and message set in case an exception happens during the signature help request. - -#### Goto Declaration Request (:leftwards_arrow_with_hook:) - -> *Since version 3.14.0* - -The go to declaration request is sent from the client to the server to resolve the declaration location of a symbol at a given text document position. - -The result type [`LocationLink`](#locationLink)[] got introduced with version 3.14.0 and depends on the corresponding client capability `textDocument.declaration.linkSupport`. - -_Client Capability_: -* property name (optional): `textDocument.declaration` -* property type: `DeclarationClientCapabilities` defined as follows: - -
+ export const None = 0; -```typescript -export interface DeclarationClientCapabilities { /** - * Whether declaration supports dynamic registration. If this is set to - * `true` the client supports the new `DeclarationRegistrationOptions` - * return value for the corresponding server capability as well. + * Documents are synced by always sending the full content + * of the document. */ - dynamicRegistration?: boolean; + export const Full = 1; /** - * The client supports additional metadata in the form of declaration links. + * Documents are synced by sending the full content on open. + * After that only incremental updates to the document are + * send. */ - linkSupport?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `declarationProvider` -* property type: `boolean | DeclarationOptions | DeclarationRegistrationOptions` where `DeclarationOptions` is defined as follows: - -
- -```typescript -export interface DeclarationOptions extends WorkDoneProgressOptions { -} -``` - -_Registration Options_: `DeclarationRegistrationOptions` defined as follows: - -
- -```typescript -export interface DeclarationRegistrationOptions extends DeclarationOptions, - TextDocumentRegistrationOptions, StaticRegistrationOptions { + export const Incremental = 2; } -``` - -_Request_: -* method: `textDocument/declaration` -* params: `DeclarationParams` defined as follows: - -
-```typescript -export interface DeclarationParams extends TextDocumentPositionParams, - WorkDoneProgressParams, PartialResultParams { -} +export type TextDocumentSyncKind = 0 | 1 | 2; ``` -_Response_: -* result: [`Location`](#location) \| [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] \|`null` -* partial result: [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] -* error: code and message set in case an exception happens during the declaration request. - -#### Goto Definition Request (:leftwards_arrow_with_hook:) - -The go to definition request is sent from the client to the server to resolve the definition location of a symbol at a given text document position. - -The result type [`LocationLink`](#locationLink)[] got introduced with version 3.14.0 and depends on the corresponding client capability `textDocument.definition.linkSupport`. - -_Client Capability_: -* property name (optional): `textDocument.definition` -* property type: `DefinitionClientCapabilities` defined as follows: - -
+
```typescript -export interface DefinitionClientCapabilities { +export interface TextDocumentSyncOptions { /** - * Whether definition supports dynamic registration. + * Open and close notifications are sent to the server. If omitted open + * close notification should not be sent. */ - dynamicRegistration?: boolean; - + openClose?: boolean; /** - * The client supports additional metadata in the form of definition links. - * - * @since 3.14.0 + * Change notifications are sent to the server. See + * TextDocumentSyncKind.None, TextDocumentSyncKind.Full and + * TextDocumentSyncKind.Incremental. If omitted it defaults to + * TextDocumentSyncKind.None. */ - linkSupport?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `definitionProvider` -* property type: `boolean | DefinitionOptions` where `DefinitionOptions` is defined as follows: - -
- -```typescript -export interface DefinitionOptions extends WorkDoneProgressOptions { -} -``` - -_Registration Options_: `DefinitionRegistrationOptions` defined as follows: - -
- -```typescript -export interface DefinitionRegistrationOptions extends - TextDocumentRegistrationOptions, DefinitionOptions { -} -``` - -_Request_: -* method: `textDocument/definition` -* params: `DefinitionParams` defined as follows: - -
- -```typescript -export interface DefinitionParams extends TextDocumentPositionParams, - WorkDoneProgressParams, PartialResultParams { -} -``` - -_Response_: -* result: [`Location`](#location) \| [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] \| `null` -* partial result: [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] -* error: code and message set in case an exception happens during the definition request. - -#### Goto Type Definition Request (:leftwards_arrow_with_hook:) - -> *Since version 3.6.0* - -The go to type definition request is sent from the client to the server to resolve the type definition location of a symbol at a given text document position. - -The result type [`LocationLink`](#locationLink)[] got introduced with version 3.14.0 and depends on the corresponding client capability `textDocument.typeDefinition.linkSupport`. - -_Client Capability_: -* property name (optional): `textDocument.typeDefinition` -* property type: `TypeDefinitionClientCapabilities` defined as follows: - -
- -```typescript -export interface TypeDefinitionClientCapabilities { + change?: TextDocumentSyncKind; /** - * Whether implementation supports dynamic registration. If this is set to - * `true` the client supports the new `TypeDefinitionRegistrationOptions` - * return value for the corresponding server capability as well. + * If present will save notifications are sent to the server. If omitted + * the notification should not be sent. */ - dynamicRegistration?: boolean; - + willSave?: boolean; /** - * The client supports additional metadata in the form of definition links. - * - * @since 3.14.0 + * If present will save wait until requests are sent to the server. If + * omitted the request should not be sent. */ - linkSupport?: boolean; -} -``` - -_Server Capability_: -* property name (optional): `typeDefinitionProvider` -* property type: `boolean | TypeDefinitionOptions | TypeDefinitionRegistrationOptions` where `TypeDefinitionOptions` is defined as follows: - -
- -```typescript -export interface TypeDefinitionOptions extends WorkDoneProgressOptions { -} -``` - -_Registration Options_: `TypeDefinitionRegistrationOptions` defined as follows: - -
- -```typescript -export interface TypeDefinitionRegistrationOptions extends - TextDocumentRegistrationOptions, TypeDefinitionOptions, - StaticRegistrationOptions { -} -``` - -_Request_: -* method: `textDocument/typeDefinition` -* params: `TypeDefinitionParams` defined as follows: - -
- -```typescript -export interface TypeDefinitionParams extends TextDocumentPositionParams, - WorkDoneProgressParams, PartialResultParams { + willSaveWaitUntil?: boolean; + /** + * If present save notifications are sent to the server. If omitted the + * notification should not be sent. + */ + save?: boolean | SaveOptions; } ``` -_Response_: -* result: [`Location`](#location) \| [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] \| `null` -* partial result: [`Location`](#location)[] \| [`LocationLink`](#locationLink)[] -* error: code and message set in case an exception happens during the definition request. +{% include_relative language/publishDiagnostics.md %} +{% include_relative language/completion.md %} +{% include_relative language/hover.md %} +{% include_relative language/signatureHelp.md %} +{% include_relative language/declaration.md %} +{% include_relative language/definition.md %} +{% include_relative language/typeDefinition.md %} {% include_relative language/implementation.md %} {% include_relative language/references.md %} {% include_relative language/documentHighlight.md %} diff --git a/_specifications/lsp/3.17/telemetry/event.md b/_specifications/lsp/3.17/telemetry/event.md new file mode 100644 index 000000000..e7eed029a --- /dev/null +++ b/_specifications/lsp/3.17/telemetry/event.md @@ -0,0 +1,7 @@ +#### Telemetry Notification (:arrow_left:) + +The telemetry notification is sent from the server to the client to ask the client to log a telemetry event. The protocol doesn't specify the payload since no interpretation of the data happens in the protocol. Most clients even don't handle the event directly but forward them to the extensions owing the corresponding server issuing the event. + +_Notification_: +* method: 'telemetry/event' +* params: 'object' \| 'number' \| 'boolean' \| 'string'; diff --git a/_specifications/lsp/3.17/textDocument/didChange.md b/_specifications/lsp/3.17/textDocument/didChange.md new file mode 100644 index 000000000..9cc2a413c --- /dev/null +++ b/_specifications/lsp/3.17/textDocument/didChange.md @@ -0,0 +1,93 @@ +#### DidChangeTextDocument Notification (:arrow_right:) + +The document change notification is sent from the client to the server to signal changes to a text document. Before a client can change a text document it must claim ownership of its content using the `textDocument/didOpen` notification. In 2.0 the shape of the params has changed to include proper version numbers. + +_Client Capability_: +See general synchronization [client capabilities](#textDocument_synchronization_cc). + +_Server Capability_: +See general synchronization [server capabilities](#textDocument_synchronization_sc). + +_Registration Options_: `TextDocumentChangeRegistrationOptions` defined as follows: + +
+ +```typescript +/** + * Describe options to be used when registering for text document change events. + */ +export interface TextDocumentChangeRegistrationOptions + extends TextDocumentRegistrationOptions { + /** + * How documents are synced to the server. See TextDocumentSyncKind.Full + * and TextDocumentSyncKind.Incremental. + */ + syncKind: TextDocumentSyncKind; +} +``` + +_Notification_: +* method: `textDocument/didChange` +* params: `DidChangeTextDocumentParams` defined as follows: + +
+ +```typescript +interface DidChangeTextDocumentParams { + /** + * The document that did change. The version number points + * to the version after all provided content changes have + * been applied. + */ + textDocument: VersionedTextDocumentIdentifier; + + /** + * The actual content changes. The content changes describe single state + * changes to the document. So if there are two content changes c1 (at + * array index 0) and c2 (at array index 1) for a document in state S then + * c1 moves the document from S to S' and c2 from S' to S''. So c1 is + * computed on the state S and c2 is computed on the state S'. + * + * To mirror the content of a document using change events use the following + * approach: + * - start with the same initial content + * - apply the 'textDocument/didChange' notifications in the order you + * receive them. + * - apply the `TextDocumentContentChangeEvent`s in a single notification + * in the order you receive them. + */ + contentChanges: TextDocumentContentChangeEvent[]; +} +``` + +
+ +```typescript +/** + * An event describing a change to a text document. If range and rangeLength are + * omitted the new text is considered to be the full content of the document. + */ +export type TextDocumentContentChangeEvent = { + /** + * The range of the document that changed. + */ + range: Range; + + /** + * The optional length of the range that got replaced. + * + * @deprecated use range instead. + */ + rangeLength?: uinteger; + + /** + * The new text for the provided range. + */ + text: string; +} | { + /** + * The new text of the whole document. + */ + text: string; +}; +``` diff --git a/_specifications/lsp/3.17/textDocument/didClose.md b/_specifications/lsp/3.17/textDocument/didClose.md new file mode 100644 index 000000000..48e4032cc --- /dev/null +++ b/_specifications/lsp/3.17/textDocument/didClose.md @@ -0,0 +1,26 @@ +#### DidCloseTextDocument Notification (:arrow_right:) + +The document close notification is sent from the client to the server when the document got closed in the client. The document's master now exists where the document's Uri points to (e.g. if the document's Uri is a file Uri the master now exists on disk). As with the open notification the close notification is about managing the document's content. Receiving a close notification doesn't mean that the document was open in an editor before. A close notification requires a previous open notification to be sent. Note that a server's ability to fulfill requests is independent of whether a text document is open or closed. + +_Client Capability_: +See general synchronization [client capabilities](#textDocument_synchronization_cc). + +_Server Capability_: +See general synchronization [server capabilities](#textDocument_synchronization_sc). + +_Registration Options_: `TextDocumentRegistrationOptions` + +_Notification_: +* method: `textDocument/didClose` +* params: `DidCloseTextDocumentParams` defined as follows: + +
+ +```typescript +interface DidCloseTextDocumentParams { + /** + * The document that was closed. + */ + textDocument: TextDocumentIdentifier; +} +``` \ No newline at end of file diff --git a/_specifications/lsp/3.17/textDocument/didOpen.md b/_specifications/lsp/3.17/textDocument/didOpen.md new file mode 100644 index 000000000..9704bcfb9 --- /dev/null +++ b/_specifications/lsp/3.17/textDocument/didOpen.md @@ -0,0 +1,28 @@ +#### DidOpenTextDocument Notification (:arrow_right:) + +The document open notification is sent from the client to the server to signal newly opened text documents. The document's content is now managed by the client and the server must not try to read the document's content using the document's Uri. Open in this sense means it is managed by the client. It doesn't necessarily mean that its content is presented in an editor. An open notification must not be sent more than once without a corresponding close notification send before. This means open and close notification must be balanced and the max open count for a particular textDocument is one. Note that a server's ability to fulfill requests is independent of whether a text document is open or closed. + +The `DidOpenTextDocumentParams` contain the language id the document is associated with. If the language id of a document changes, the client needs to send a `textDocument/didClose` to the server followed by a `textDocument/didOpen` with the new language id if the server handles the new language id as well. + +_Client Capability_: +See general synchronization [client capabilities](#textDocument_synchronization_cc). + +_Server Capability_: +See general synchronization [server capabilities](#textDocument_synchronization_sc). + +_Registration Options_: [`TextDocumentRegistrationOptions`](#textDocumentRegistrationOptions) + +_Notification_: +* method: 'textDocument/didOpen' +* params: `DidOpenTextDocumentParams` defined as follows: + +
+ +```typescript +interface DidOpenTextDocumentParams { + /** + * The document that was opened. + */ + textDocument: TextDocumentItem; +} +``` \ No newline at end of file diff --git a/_specifications/lsp/3.17/textDocument/didSave.md b/_specifications/lsp/3.17/textDocument/didSave.md new file mode 100644 index 000000000..8e4f308be --- /dev/null +++ b/_specifications/lsp/3.17/textDocument/didSave.md @@ -0,0 +1,61 @@ +#### DidSaveTextDocument Notification (:arrow_right:) + +The document save notification is sent from the client to the server when the document was saved in the client. + +_Client Capability_: +* property name (optional): `textDocument.synchronization.didSave` +* property type: `boolean` + +The capability indicates that the client supports `textDocument/didSave` notifications. + +_Server Capability_: +* property name (optional): `textDocumentSync.save` +* property type: `boolean | SaveOptions` where `SaveOptions` is defined as follows: + +
+ +```typescript +export interface SaveOptions { + /** + * The client is supposed to include the content on save. + */ + includeText?: boolean; +} +``` + +The capability indicates that the server is interested in `textDocument/didSave` notifications. + +_Registration Options_: `TextDocumentSaveRegistrationOptions` defined as follows: + +
+ +```typescript +export interface TextDocumentSaveRegistrationOptions + extends TextDocumentRegistrationOptions { + /** + * The client is supposed to include the content on save. + */ + includeText?: boolean; +} +``` + +_Notification_: +* method: `textDocument/didSave` +* params: `DidSaveTextDocumentParams` defined as follows: + +
+ +```typescript +interface DidSaveTextDocumentParams { + /** + * The document that was saved. + */ + textDocument: TextDocumentIdentifier; + + /** + * Optional the content when saved. Depends on the includeText value + * when the save notification was requested. + */ + text?: string; +} +``` diff --git a/_specifications/lsp/3.17/textDocument/willSave.md b/_specifications/lsp/3.17/textDocument/willSave.md new file mode 100644 index 000000000..cb61d54db --- /dev/null +++ b/_specifications/lsp/3.17/textDocument/willSave.md @@ -0,0 +1,68 @@ +#### WillSaveTextDocument Notification (:arrow_right:) + +The document will save notification is sent from the client to the server before the document is actually saved. If a server has registered for open / close events clients should ensure that the document is open before a `willSave` notification is sent since clients can't change the content of a file without ownership transferal. + +_Client Capability_: +* property name (optional): `textDocument.synchronization.willSave` +* property type: `boolean` + +The capability indicates that the client supports `textDocument/willSave` notifications. + +_Server Capability_: +* property name (optional): `textDocumentSync.willSave` +* property type: `boolean` + +The capability indicates that the server is interested in `textDocument/willSave` notifications. + +_Registration Options_: `TextDocumentRegistrationOptions` + +_Notification_: +* method: 'textDocument/willSave' +* params: `WillSaveTextDocumentParams` defined as follows: + +
+ +```typescript +/** + * The parameters send in a will save text document notification. + */ +export interface WillSaveTextDocumentParams { + /** + * The document that will be saved. + */ + textDocument: TextDocumentIdentifier; + + /** + * The 'TextDocumentSaveReason'. + */ + reason: TextDocumentSaveReason; +} +``` + +
+ +```typescript +/** + * Represents reasons why a text document is saved. + */ +export namespace TextDocumentSaveReason { + + /** + * Manually triggered, e.g. by the user pressing save, by starting + * debugging, or by an API call. + */ + export const Manual = 1; + + /** + * Automatic after a delay. + */ + export const AfterDelay = 2; + + /** + * When the editor lost focus. + */ + export const FocusOut = 3; +} + +export type TextDocumentSaveReason = 1 | 2 | 3; +``` diff --git a/_specifications/lsp/3.17/textDocument/willSaveWaitUntil.md b/_specifications/lsp/3.17/textDocument/willSaveWaitUntil.md new file mode 100644 index 000000000..72cb161a5 --- /dev/null +++ b/_specifications/lsp/3.17/textDocument/willSaveWaitUntil.md @@ -0,0 +1,25 @@ +#### WillSaveWaitUntilTextDocument Request (:leftwards_arrow_with_hook:) + +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. If a server has registered for open / close events clients should ensure that the document is open before a `willSaveWaitUntil` notification is sent since clients can't change the content of a file without ownership transferal. + +_Client Capability_: +* property name (optional): `textDocument.synchronization.willSaveWaitUntil` +* property type: `boolean` + +The capability indicates that the client supports `textDocument/willSaveWaitUntil` requests. + +_Server Capability_: +* property name (optional): `textDocumentSync.willSaveWaitUntil` +* property type: `boolean` + +The capability indicates that the server is interested in `textDocument/willSaveWaitUntil` requests. + +_Registration Options_: `TextDocumentRegistrationOptions` + +_Request_: +* method: `textDocument/willSaveWaitUntil` +* params: `WillSaveTextDocumentParams` + +_Response_: +* result:[`TextEdit[]`](#textEdit) \| `null` +* error: code and message set in case an exception happens during the `textDocument/willSaveWaitUntil` request. diff --git a/_specifications/lsp/3.17/window/logMessage.md b/_specifications/lsp/3.17/window/logMessage.md new file mode 100644 index 000000000..7625ce4ce --- /dev/null +++ b/_specifications/lsp/3.17/window/logMessage.md @@ -0,0 +1,23 @@ +#### LogMessage Notification (:arrow_left:) + +The log message notification is sent from the server to the client to ask the client to log a particular message. + +_Notification_: +* method: 'window/logMessage' +* params: `LogMessageParams` defined as follows: + +
+ +```typescript +interface LogMessageParams { + /** + * The message type. See {@link MessageType} + */ + type: MessageType; + + /** + * The actual message + */ + message: string; +} +``` diff --git a/_specifications/lsp/3.17/window/showDocument.md b/_specifications/lsp/3.17/window/showDocument.md new file mode 100644 index 000000000..7ea92e478 --- /dev/null +++ b/_specifications/lsp/3.17/window/showDocument.md @@ -0,0 +1,88 @@ +#### Show Document Request (:arrow_right_hook:) + +> New in version 3.16.0 + +The show document request is sent from a server to a client to ask the client to display a particular document in the user interface. + +_Client Capability_: +* property path (optional): `window.showDocument` +* property type: `ShowDocumentClientCapabilities` defined as follows: + +```typescript +/** + * Client capabilities for the show document request. + * + * @since 3.16.0 + */ +export interface ShowDocumentClientCapabilities { + /** + * The client has support for the show document + * request. + */ + support: boolean; +} +``` + +_Request_: +* method: 'window/showDocument' +* params: `ShowDocumentParams` defined as follows: + +
+ +```typescript +/** + * Params to show a document. + * + * @since 3.16.0 + */ +export interface ShowDocumentParams { + /** + * The document uri to show. + */ + uri: URI; + + /** + * Indicates to show the resource in an external program. + * To show for example `https://code.visualstudio.com/` + * in the default WEB browser set `external` to `true`. + */ + external?: boolean; + + /** + * An optional property to indicate whether the editor + * showing the document should take focus or not. + * Clients might ignore this property if an external + * program is started. + */ + takeFocus?: boolean; + + /** + * An optional selection range if the document is a text + * document. Clients might ignore the property if an + * external program is started or the file is not a text + * file. + */ + selection?: Range; +} +``` + +_Response_: + +* result: `ShowDocumentResult` defined as follows: + +
+ +```typescript +/** + * The result of an show document request. + * + * @since 3.16.0 + */ +export interface ShowDocumentResult { + /** + * A boolean indicating if the show was successful. + */ + success: boolean; +} +``` +* error: code and message set in case an exception happens during showing a document. diff --git a/_specifications/lsp/3.17/window/showMessage.md b/_specifications/lsp/3.17/window/showMessage.md new file mode 100644 index 000000000..cd73c0c65 --- /dev/null +++ b/_specifications/lsp/3.17/window/showMessage.md @@ -0,0 +1,48 @@ +#### ShowMessage Notification (:arrow_left:) + +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. + +_Notification_: +* method: 'window/showMessage' +* params: `ShowMessageParams` defined as follows: + +```typescript +interface ShowMessageParams { + /** + * The message type. See {@link MessageType}. + */ + type: MessageType; + + /** + * The actual message. + */ + message: string; +} +``` + +Where the type is defined as follows: + +
+ +```typescript +export namespace MessageType { + /** + * An error message. + */ + export const Error = 1; + /** + * A warning message. + */ + export const Warning = 2; + /** + * An information message. + */ + export const Info = 3; + /** + * A log message. + */ + export const Log = 4; +} + +export type MessageType = 1 | 2 | 3 | 4; +``` diff --git a/_specifications/lsp/3.17/window/showMessageRequest.md b/_specifications/lsp/3.17/window/showMessageRequest.md new file mode 100644 index 000000000..28650c0f9 --- /dev/null +++ b/_specifications/lsp/3.17/window/showMessageRequest.md @@ -0,0 +1,68 @@ +#### ShowMessage Request (:arrow_right_hook:) + +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. + +_Client Capability_: +* property path (optional): `window.showMessage` +* property type: `ShowMessageRequestClientCapabilities` defined as follows: + +```typescript +/** + * Show message request client capabilities + */ +export interface ShowMessageRequestClientCapabilities { + /** + * Capabilities specific to the `MessageActionItem` type. + */ + messageActionItem?: { + /** + * Whether the client supports additional attributes which + * are preserved and sent back to the server in the + * request's response. + */ + additionalPropertiesSupport?: boolean; + }; +} +``` + +_Request_: +* method: 'window/showMessageRequest' +* params: `ShowMessageRequestParams` defined as follows: + +
+ +```typescript +interface ShowMessageRequestParams { + /** + * The message type. See {@link MessageType} + */ + type: MessageType; + + /** + * The actual message + */ + message: string; + + /** + * The message action items to present. + */ + actions?: MessageActionItem[]; +} +``` + +Where the `MessageActionItem` is defined as follows: + +
+ +```typescript +interface MessageActionItem { + /** + * A short title like 'Retry', 'Open Log' etc. + */ + title: string; +} +``` + +_Response_: +* result: the selected `MessageActionItem` \| `null` if none got selected. +* error: code and message set in case an exception happens during showing a message. diff --git a/_specifications/lsp/3.17/window/workDoneProgressCancel.md b/_specifications/lsp/3.17/window/workDoneProgressCancel.md new file mode 100644 index 000000000..ff04d1443 --- /dev/null +++ b/_specifications/lsp/3.17/window/workDoneProgressCancel.md @@ -0,0 +1,16 @@ +#### Canceling a Work Done Progress (:arrow_right:) + +The `window/workDoneProgress/cancel` notification is sent from the client to the server to cancel a progress initiated on the server side using the `window/workDoneProgress/create`. The progress need not be marked as `cancellable` to be cancelled and a client may cancel a progress for any number of reasons: in case of error, reloading a workspace etc. + +_Notification_: + +* method: 'window/workDoneProgress/cancel' +* params: `WorkDoneProgressCancelParams` defined as follows: +```typescript +export interface WorkDoneProgressCancelParams { + /** + * The token to be used to report progress. + */ + token: ProgressToken; +} +``` \ No newline at end of file diff --git a/_specifications/lsp/3.17/window/workDoneProgressCreate.md b/_specifications/lsp/3.17/window/workDoneProgressCreate.md new file mode 100644 index 000000000..a142bcee3 --- /dev/null +++ b/_specifications/lsp/3.17/window/workDoneProgressCreate.md @@ -0,0 +1,22 @@ +#### Creating Work Done Progress (:arrow_right_hook:) + +The `window/workDoneProgress/create` request is sent from the server to the client to ask the client to create a work done progress. + +_Request_: + +* method: 'window/workDoneProgress/create' +* params: `WorkDoneProgressCreateParams` defined as follows: + +```typescript +export interface WorkDoneProgressCreateParams { + /** + * The token to be used to report progress. + */ + token: ProgressToken; +} +``` + +_Response_: + +* result: void +* error: code and message set in case an exception happens during the 'window/workDoneProgress/create' request. In case an error occurs a server must not send any progress notification using the token provided in the `WorkDoneProgressCreateParams`. diff --git a/_specifications/lsp/3.17/workspace/applyEdit.md b/_specifications/lsp/3.17/workspace/applyEdit.md new file mode 100644 index 000000000..a26bdf973 --- /dev/null +++ b/_specifications/lsp/3.17/workspace/applyEdit.md @@ -0,0 +1,61 @@ +#### Applies a WorkspaceEdit (:arrow_right_hook:) + +The `workspace/applyEdit` request is sent from the server to the client to modify resource on the client side. + +_Client Capability_: +* property path (optional): `workspace.applyEdit` +* property type: `boolean` + +See also the [WorkspaceEditClientCapabilities](#workspaceEditClientCapabilities) for the supported capabilities of a workspace edit. + +_Request_: +* method: 'workspace/applyEdit' +* params: `ApplyWorkspaceEditParams` defined as follows: + +
+ +```typescript +export interface ApplyWorkspaceEditParams { + /** + * An optional label of the workspace edit. This label is + * presented in the user interface for example on an undo + * stack to undo the workspace edit. + */ + label?: string; + + /** + * The edits to apply. + */ + edit: WorkspaceEdit; +} +``` + +_Response_: +* result: `ApplyWorkspaceEditResult` defined as follows: + +
+ +```typescript +export interface ApplyWorkspaceEditResult { + /** + * Indicates whether the edit was applied or not. + */ + applied: boolean; + + /** + * An optional textual description for why the edit was not applied. + * This may be used by the server for diagnostic logging or to provide + * a suitable error for a request that triggered the edit. + */ + failureReason?: string; + + /** + * Depending on the client's failure handling strategy `failedChange` + * might contain the index of the change that failed. This property is + * only available if the client signals a `failureHandling` strategy + * in its client capabilities. + */ + failedChange?: uinteger; +} +``` +* error: code and message set in case an exception happens during the request. diff --git a/_specifications/lsp/3.17/workspace/configuration.md b/_specifications/lsp/3.17/workspace/configuration.md new file mode 100644 index 000000000..c79d4eba0 --- /dev/null +++ b/_specifications/lsp/3.17/workspace/configuration.md @@ -0,0 +1,43 @@ +#### Configuration Request (:arrow_right_hook:) + +> *Since version 3.6.0* + +The `workspace/configuration` request is sent from the server to the client to fetch configuration settings from the client. The request can fetch several configuration settings in one roundtrip. The order of the returned configuration settings correspond to the order of the passed `ConfigurationItems` (e.g. the first item in the response is the result for the first configuration item in the params). + +A `ConfigurationItem` consists of the configuration section to ask for and an additional scope URI. The configuration section asked for is defined by the server and doesn't necessarily need to correspond to the configuration store used by the client. So a server might ask for a configuration `cpp.formatterOptions` but the client stores the configuration in an XML store layout differently. It is up to the client to do the necessary conversion. If a scope URI is provided the client should return the setting scoped to the provided resource. If the client for example uses [EditorConfig](http://editorconfig.org/) to manage its settings the configuration should be returned for the passed resource URI. If the client can't provide a configuration setting for a given scope then `null` needs to be present in the returned array. + +_Client Capability_: +* property path (optional): `workspace.configuration` +* property type: `boolean` + +_Request_: +* method: 'workspace/configuration' +* params: `ConfigurationParams` defined as follows + +
+ +```typescript +export interface ConfigurationParams { + items: ConfigurationItem[]; +} +``` + +
+ +```typescript +export interface ConfigurationItem { + /** + * The scope to get the configuration section for. + */ + scopeUri?: DocumentUri; + + /** + * The configuration section asked for. + */ + section?: string; +} +``` + +_Response_: +* result: LSPAny[] +* error: code and message set in case an exception happens during the 'workspace/configuration' request diff --git a/_specifications/lsp/3.17/workspace/didChangeConfiguration.md b/_specifications/lsp/3.17/workspace/didChangeConfiguration.md new file mode 100644 index 000000000..04bf9bb2d --- /dev/null +++ b/_specifications/lsp/3.17/workspace/didChangeConfiguration.md @@ -0,0 +1,33 @@ +#### DidChangeConfiguration Notification (:arrow_right:) + +A notification sent from the client to the server to signal the change of configuration settings. + +_Client Capability_: +* property path (optional): `workspace.didChangeConfiguration` +* property type: `DidChangeConfigurationClientCapabilities` defined as follows: + +
+ +```typescript +export interface DidChangeConfigurationClientCapabilities { + /** + * Did change configuration notification supports dynamic registration. + */ + dynamicRegistration?: boolean; +} +``` + +_Notification_: +* method: 'workspace/didChangeConfiguration', +* params: `DidChangeConfigurationParams` defined as follows: + +
+ +```typescript +interface DidChangeConfigurationParams { + /** + * The actual changed settings + */ + settings: LSPAny; +} +``` diff --git a/_specifications/lsp/3.17/workspace/didChangeWatchedFiles.md b/_specifications/lsp/3.17/workspace/didChangeWatchedFiles.md new file mode 100644 index 000000000..0572d1cd1 --- /dev/null +++ b/_specifications/lsp/3.17/workspace/didChangeWatchedFiles.md @@ -0,0 +1,151 @@ +#### DidChangeWatchedFiles Notification (:arrow_right:) + +The watched files notification is sent from the client to the server when the client detects changes to files and folders watched by the language client (note although the name suggest that only file events are sent it is about file system events which include folders as well). It is recommended that servers register for these file system events using the registration mechanism. In former implementations clients pushed file events without the server actively asking for it. + +Servers are allowed to run their own file system watching mechanism and not rely on clients to provide file system events. However this is not recommended due to the following reasons: + +- to our experience getting file system watching on disk right is challenging, especially if it needs to be supported across multiple OSes. +- file system watching is not for free especially if the implementation uses some sort of polling and keeps a file system tree in memory to compare time stamps (as for example some node modules do) +- a client usually starts more than one server. If every server runs its own file system watching it can become a CPU or memory problem. +- in general there are more server than client implementations. So this problem is better solved on the client side. + +_Client Capability_: +* property path (optional): `workspace.didChangeWatchedFiles` +* property type: `DidChangeWatchedFilesClientCapabilities` defined as follows: + +
+ +```typescript +export interface DidChangeWatchedFilesClientCapabilities { + /** + * Did change watched files notification supports dynamic registration. + * Please note that the current protocol doesn't support static + * configuration for file changes from the server side. + */ + dynamicRegistration?: boolean; +} +``` + +_Registration Options_: `DidChangeWatchedFilesRegistrationOptions` defined as follows: + +
+ +```typescript +/** + * Describe options to be used when registering for file system change events. + */ +export interface DidChangeWatchedFilesRegistrationOptions { + /** + * The watchers to register. + */ + watchers: FileSystemWatcher[]; +} +``` + +
+ +```typescript +export interface FileSystemWatcher { + /** + * The glob pattern to watch. + * + * Glob patterns can have the following syntax: + * - `*` to match one or more characters in a path segment + * - `?` to match on one character in a path segment + * - `**` to match any number of path segments, including none + * - `{}` to group sub patterns into an OR expression. (e.g. `**​/*.{ts,js}` + * matches all TypeScript and JavaScript files) + * - `[]` to declare a range of characters to match in a path segment + * (e.g., `example.[0-9]` to match on `example.0`, `example.1`, …) + * - `[!...]` to negate a range of characters to match in a path segment + * (e.g., `example.[!0-9]` to match on `example.a`, `example.b`, but not + * `example.0`) + */ + globPattern: string; + + /** + * The kind of events of interest. If omitted it defaults + * to WatchKind.Create | WatchKind.Change | WatchKind.Delete + * which is 7. + */ + kind?: uinteger; +} +``` + +
+ +```typescript +export namespace WatchKind { + /** + * Interested in create events. + */ + export const Create = 1; + + /** + * Interested in change events + */ + export const Change = 2; + + /** + * Interested in delete events + */ + export const Delete = 4; +} +``` + +_Notification_: +* method: 'workspace/didChangeWatchedFiles' +* params: `DidChangeWatchedFilesParams` defined as follows: + +
+ +```typescript +interface DidChangeWatchedFilesParams { + /** + * The actual file events. + */ + changes: FileEvent[]; +} +``` + +Where FileEvents are described as follows: + +
+ +```typescript +/** + * An event describing a file change. + */ +interface FileEvent { + /** + * The file's URI. + */ + uri: DocumentUri; + /** + * The change type. + */ + type: uinteger; +} +``` + +
+ +```typescript +/** + * The file event type. + */ +export namespace FileChangeType { + /** + * The file got created. + */ + export const Created = 1; + /** + * The file got changed. + */ + export const Changed = 2; + /** + * The file got deleted. + */ + export const Deleted = 3; +} +``` diff --git a/_specifications/lsp/3.17/workspace/didChangeWorkspaceFolders.md b/_specifications/lsp/3.17/workspace/didChangeWorkspaceFolders.md new file mode 100644 index 000000000..6f2809317 --- /dev/null +++ b/_specifications/lsp/3.17/workspace/didChangeWorkspaceFolders.md @@ -0,0 +1,45 @@ +##### DidChangeWorkspaceFolders Notification (:arrow_right:) + +> *Since version 3.6.0* + +The `workspace/didChangeWorkspaceFolders` notification is sent from the client to the server to inform the server about workspace folder configuration changes. The notification is sent by default if both _client capability_ `workspace.workspaceFolders` and the _server capability_ `workspace.workspaceFolders.supported` are true; or if the server has registered itself to receive this notification. To register for the `workspace/didChangeWorkspaceFolders` send a `client/registerCapability` request from the server to the client. The registration parameter must have a `registrations` item of the following form, where `id` is a unique id used to unregister the capability (the example uses a UUID): +```ts +{ + id: "28c6150c-bd7b-11e7-abc4-cec278b6b50a", + method: "workspace/didChangeWorkspaceFolders" +} +``` + +_Notification_: +* method: 'workspace/didChangeWorkspaceFolders' +* params: `DidChangeWorkspaceFoldersParams` defined as follows: + +
+ +```typescript +export interface DidChangeWorkspaceFoldersParams { + /** + * The actual workspace folder change event. + */ + event: WorkspaceFoldersChangeEvent; +} +``` + +
+ +```typescript +/** + * The workspace folder change event. + */ +export interface WorkspaceFoldersChangeEvent { + /** + * The array of added workspace folders + */ + added: WorkspaceFolder[]; + + /** + * The array of the removed workspace folders + */ + removed: WorkspaceFolder[]; +} +``` diff --git a/_specifications/lsp/3.17/workspace/didCreateFiles.md b/_specifications/lsp/3.17/workspace/didCreateFiles.md new file mode 100644 index 000000000..04837a97d --- /dev/null +++ b/_specifications/lsp/3.17/workspace/didCreateFiles.md @@ -0,0 +1,19 @@ +#### DidCreateFiles Notification (:arrow_right:) + +The did create files notification is sent from the client to the server when files were created from within the client. + +_Client Capability_: +* property name (optional): `workspace.fileOperations.didCreate` +* property type: `boolean` + +The capability indicates that the client supports sending `workspace/didCreateFiles` notifications. + +_Server Capability_: +* property name (optional): `workspace.fileOperations.didCreate` +* property type: `FileOperationRegistrationOptions` + +The capability indicates that the server is interested in receiving `workspace/didCreateFiles` notifications. + +_Notification_: +* method: 'workspace/didCreateFiles' +* params: `CreateFilesParams` diff --git a/_specifications/lsp/3.17/workspace/didDeleteFiles.md b/_specifications/lsp/3.17/workspace/didDeleteFiles.md new file mode 100644 index 000000000..b2bcde517 --- /dev/null +++ b/_specifications/lsp/3.17/workspace/didDeleteFiles.md @@ -0,0 +1,19 @@ +#### DidDeleteFiles Notification (:arrow_right:) + +The did delete files notification is sent from the client to the server when files were deleted from within the client. + +_Client Capability_: +* property name (optional): `workspace.fileOperations.didDelete` +* property type: `boolean` + +The capability indicates that the client supports sending `workspace/didDeleteFiles` notifications. + +_Server Capability_: +* property name (optional): `workspace.fileOperations.didDelete` +* property type: `FileOperationRegistrationOptions` + +The capability indicates that the server is interested in receiving `workspace/didDeleteFiles` notifications. + +_Notification_: +* method: 'workspace/didDeleteFiles' +* params: `DeleteFilesParams` diff --git a/_specifications/lsp/3.17/workspace/didRenameFiles.md b/_specifications/lsp/3.17/workspace/didRenameFiles.md new file mode 100644 index 000000000..67cf77533 --- /dev/null +++ b/_specifications/lsp/3.17/workspace/didRenameFiles.md @@ -0,0 +1,19 @@ +#### DidRenameFiles Notification (:arrow_right:) + +The did rename files notification is sent from the client to the server when files were renamed from within the client. + +_Client Capability_: +* property name (optional): `workspace.fileOperations.didRename` +* property type: `boolean` + +The capability indicates that the client supports sending `workspace/didRenameFiles` notifications. + +_Server Capability_: +* property name (optional): `workspace.fileOperations.didRename` +* property type: `FileOperationRegistrationOptions` + +The capability indicates that the server is interested in receiving `workspace/didRenameFiles` notifications. + +_Notification_: +* method: 'workspace/didRenameFiles' +* params: `RenameFilesParams` diff --git a/_specifications/lsp/3.17/workspace/executeCommand.md b/_specifications/lsp/3.17/workspace/executeCommand.md new file mode 100644 index 000000000..6ca8a8c27 --- /dev/null +++ b/_specifications/lsp/3.17/workspace/executeCommand.md @@ -0,0 +1,72 @@ +#### Execute a command (:leftwards_arrow_with_hook:) + +The `workspace/executeCommand` request is sent from the client to the server to trigger command execution on the server. In most cases the server creates a `WorkspaceEdit` structure and applies the changes to the workspace using the request `workspace/applyEdit` which is sent from the server to the client. + +_Client Capability_: +* property path (optional): `workspace.executeCommand` +* property type: `ExecuteCommandClientCapabilities` defined as follows: + +
+ +```typescript +export interface ExecuteCommandClientCapabilities { + /** + * Execute command supports dynamic registration. + */ + dynamicRegistration?: boolean; +} +``` + +_Server Capability_: +* property path (optional): `executeCommandProvider` +* property type: `ExecuteCommandOptions` defined as follows: + +
+ +```typescript +export interface ExecuteCommandOptions extends WorkDoneProgressOptions { + /** + * The commands to be executed on the server + */ + commands: string[]; +} +``` + +_Registration Options_: `ExecuteCommandRegistrationOptions` defined as follows: + +
+ +```typescript +/** + * Execute command registration options. + */ +export interface ExecuteCommandRegistrationOptions + extends ExecuteCommandOptions { +} +``` + +_Request_: +* method: 'workspace/executeCommand' +* params: `ExecuteCommandParams` defined as follows: + +
+ +```typescript +export interface ExecuteCommandParams extends WorkDoneProgressParams { + + /** + * The identifier of the actual command handler. + */ + command: string; + /** + * Arguments that the command should be invoked with. + */ + arguments?: LSPAny[]; +} +``` + +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`. + +_Response_: +* result: `LSPAny` \| `null` +* error: code and message set in case an exception happens during the request. diff --git a/_specifications/lsp/3.17/workspace/symbol.md b/_specifications/lsp/3.17/workspace/symbol.md new file mode 100644 index 000000000..7852d7dbf --- /dev/null +++ b/_specifications/lsp/3.17/workspace/symbol.md @@ -0,0 +1,168 @@ +#### Workspace Symbols Request (:leftwards_arrow_with_hook:) + +The workspace symbol request is sent from the client to the server to list project-wide symbols matching the query string. Since 3.17.0 servers can also provider a handler for `workspaceSymbol/resolve` requests. This allows servers to return workspace symbols without a range for a `workspace/symbol` request. Clients then need to resolve the range when necessary using the `workspaceSymbol/resolve` request. Servers can only use this new model if clients advertise support for it via the `workspace.symbol.resolveSupport` capability. + +_Client Capability_: +* property path (optional): `workspace.symbol` +* property type: `WorkspaceSymbolClientCapabilities` defined as follows: + +```typescript +interface WorkspaceSymbolClientCapabilities { + /** + * Symbol request supports dynamic registration. + */ + dynamicRegistration?: boolean; + + /** + * Specific capabilities for the `SymbolKind` in the `workspace/symbol` + * request. + */ + symbolKind?: { + /** + * The symbol kind values the client supports. When this + * property exists the client also guarantees that it will + * handle values outside its set gracefully and falls back + * to a default value when unknown. + * + * If this property is not present the client only supports + * the symbol kinds from `File` to `Array` as defined in + * the initial version of the protocol. + */ + valueSet?: SymbolKind[]; + }; + + /** + * The client supports tags on `SymbolInformation` and `WorkspaceSymbol`. + * Clients supporting tags have to handle unknown tags gracefully. + * + * @since 3.16.0 + */ + tagSupport?: { + /** + * The tags supported by the client. + */ + valueSet: SymbolTag[]; + }; + + /** + * The client support partial workspace symbols. The client will send the + * request `workspaceSymbol/resolve` to the server to resolve additional + * properties. + * + * @since 3.17.0 - proposedState + */ + resolveSupport?: { + /** + * The properties that a client can resolve lazily. Usually + * `location.range` + */ + properties: string[]; + }; +} +``` + +_Server Capability_: +* property path (optional): `workspaceSymbolProvider` +* property type: `boolean | WorkspaceSymbolOptions` where `WorkspaceSymbolOptions` is defined as follows: + +
+ +```typescript +export interface WorkspaceSymbolOptions extends WorkDoneProgressOptions { + /** + * The server provides support to resolve additional + * information for a workspace symbol. + * + * @since 3.17.0 - proposed state + */ + resolveProvider?: boolean; +} +``` + +_Registration Options_: `WorkspaceSymbolRegistrationOptions` defined as follows: + +
+ +```typescript +export interface WorkspaceSymbolRegistrationOptions + extends WorkspaceSymbolOptions { +} +``` + +_Request_: +* method: 'workspace/symbol' +* params: `WorkspaceSymbolParams` defined as follows: + +
+ +```typescript +/** + * The parameters of a Workspace Symbol Request. + */ +interface WorkspaceSymbolParams extends WorkDoneProgressParams, + PartialResultParams { + /** + * A query string to filter symbols by. Clients may send an empty + * string here to request all symbols. + */ + query: string; +} +``` + +_Response_: +* result: `SymbolInformation[]` \| `WorkspaceSymbol[]` \| `null`. See above for the definition of `SymbolInformation`. `WorkspaceSymbol` is defined as follows: + +
+ +```typescript +/** + * A special workspace symbol that supports locations without a range + * + * @since 3.17.0 - proposed state + */ +export interface WorkspaceSymbol { + /** + * The name of this symbol. + */ + name: string; + + /** + * The kind of this symbol. + */ + kind: SymbolKind; + + /** + * Tags for this completion item. + */ + tags?: SymbolTag[]; + + /** + * The location of this symbol. + * + * See also `SymbolInformation.location`. + */ + location: Location | { uri: DocumentUri }; + + /** + * The name of the symbol containing this symbol. This information is for + * user interface purposes (e.g. to render a qualifier in the user interface + * if necessary). It can't be used to re-infer a hierarchy for the document + * symbols. + */ + containerName?: string; +} +``` +* partial result: `SymbolInformation[]` \| `WorkspaceSymbol[]` as defined above. +* error: code and message set in case an exception happens during the workspace symbol request. + +#### Workspace Symbol Resolve Request (:leftwards_arrow_with_hook:) + +The request is sent from the client to the server to resolve additional information for a given workspace symbol. + +_Request_: +* method: 'workspaceSymbol/resolve' +* params: `WorkspaceSymbol` + +_Response_: +* result: `WorkspaceSymbol` +* error: code and message set in case an exception happens during the workspace symbol resolve request. diff --git a/_specifications/lsp/3.17/workspace/willCreateFiles.md b/_specifications/lsp/3.17/workspace/willCreateFiles.md new file mode 100644 index 000000000..26aa1aa9d --- /dev/null +++ b/_specifications/lsp/3.17/workspace/willCreateFiles.md @@ -0,0 +1,179 @@ +#### WillCreateFiles Request (:leftwards_arrow_with_hook:) + +The will create files request is sent from the client to the server before files are actually created as long as the creation is triggered from within the client either by a user action or by applying a workspace edit. The request can return a WorkspaceEdit which will be applied to workspace before the files are created. Please note that clients might drop results if computing the edit took too long or if a server constantly fails on this request. This is done to keep creates fast and reliable. + +_Client Capability_: +* property name (optional): `workspace.fileOperations.willCreate` +* property type: `boolean` + +The capability indicates that the client supports sending `workspace/willCreateFiles` requests. + +_Server Capability_: +* property name (optional): `workspace.fileOperations.willCreate` +* property type: `FileOperationRegistrationOptions` where `FileOperationRegistrationOptions` is defined as follows: + +
+ +```typescript +/** + * The options to register for file operations. + * + * @since 3.16.0 + */ +interface FileOperationRegistrationOptions { + /** + * The actual filters. + */ + filters: FileOperationFilter[]; +} +``` + +
+ +```typescript +/** + * A pattern kind describing if a glob pattern matches a file a folder or + * both. + * + * @since 3.16.0 + */ +export namespace FileOperationPatternKind { + /** + * The pattern matches a file only. + */ + export const file: 'file' = 'file'; + + /** + * The pattern matches a folder only. + */ + export const folder: 'folder' = 'folder'; +} + +export type FileOperationPatternKind = 'file' | 'folder'; +``` + +
+ +```typescript +/** + * Matching options for the file operation pattern. + * + * @since 3.16.0 + */ +export interface FileOperationPatternOptions { + + /** + * The pattern should be matched ignoring casing. + */ + ignoreCase?: boolean; +} +``` + +
+ +```typescript +/** + * A pattern to describe in which file operation requests or notifications + * the server is interested in. + * + * @since 3.16.0 + */ +interface FileOperationPattern { + /** + * The glob pattern to match. Glob patterns can have the following syntax: + * - `*` to match one or more characters in a path segment + * - `?` to match on one character in a path segment + * - `**` to match any number of path segments, including none + * - `{}` to group sub patterns into an OR expression. (e.g. `**​/*.{ts,js}` + * matches all TypeScript and JavaScript files) + * - `[]` to declare a range of characters to match in a path segment + * (e.g., `example.[0-9]` to match on `example.0`, `example.1`, …) + * - `[!...]` to negate a range of characters to match in a path segment + * (e.g., `example.[!0-9]` to match on `example.a`, `example.b`, but + * not `example.0`) + */ + glob: string; + + /** + * Whether to match files or folders with this pattern. + * + * Matches both if undefined. + */ + matches?: FileOperationPatternKind; + + /** + * Additional options used during matching. + */ + options?: FileOperationPatternOptions; +} +``` + +
+ +```typescript +/** + * A filter to describe in which file operation requests or notifications + * the server is interested in. + * + * @since 3.16.0 + */ +export interface FileOperationFilter { + + /** + * A Uri like `file` or `untitled`. + */ + scheme?: string; + + /** + * The actual file operation pattern. + */ + pattern: FileOperationPattern; +} +``` + +The capability indicates that the server is interested in receiving `workspace/willCreateFiles` requests. + +_Registration Options_: none + +_Request_: +* method: 'workspace/willCreateFiles' +* params: `CreateFilesParams` defined as follows: + +
+ +```typescript +/** + * The parameters sent in notifications/requests for user-initiated creation + * of files. + * + * @since 3.16.0 + */ +export interface CreateFilesParams { + + /** + * An array of all files/folders created in this operation. + */ + files: FileCreate[]; +} +``` + +
+ +```typescript +/** + * Represents information on a file/folder create. + * + * @since 3.16.0 + */ +export interface FileCreate { + + /** + * A file:// URI for the location of the file/folder being created. + */ + uri: string; +} +``` + +_Response_: +* result:`WorkspaceEdit` \| `null` +* error: code and message set in case an exception happens during the `willCreateFiles` request. diff --git a/_specifications/lsp/3.17/workspace/willDeleteFiles.md b/_specifications/lsp/3.17/workspace/willDeleteFiles.md new file mode 100644 index 000000000..030206a58 --- /dev/null +++ b/_specifications/lsp/3.17/workspace/willDeleteFiles.md @@ -0,0 +1,60 @@ +#### WillDeleteFiles Request (:leftwards_arrow_with_hook:) + +The will delete files request is sent from the client to the server before files are actually deleted as long as the deletion is triggered from within the client either by a user action or by applying a workspace edit. The request can return a WorkspaceEdit which will be applied to workspace before the files are deleted. Please note that clients might drop results if computing the edit took too long or if a server constantly fails on this request. This is done to keep deletes fast and reliable. + +_Client Capability_: +* property name (optional): `workspace.fileOperations.willDelete` +* property type: `boolean` + +The capability indicates that the client supports sending `workspace/willDeleteFiles` requests. + +_Server Capability_: +* property name (optional): `workspace.fileOperations.willDelete` +* property type: `FileOperationRegistrationOptions` + +The capability indicates that the server is interested in receiving `workspace/willDeleteFiles` requests. + +_Registration Options_: none + +_Request_: +* method: `workspace/willDeleteFiles` +* params: `DeleteFilesParams` defined as follows: + +
+ +```typescript +/** + * The parameters sent in notifications/requests for user-initiated deletes + * of files. + * + * @since 3.16.0 + */ +export interface DeleteFilesParams { + + /** + * An array of all files/folders deleted in this operation. + */ + files: FileDelete[]; +} +``` + +
+ +```typescript +/** + * Represents information on a file/folder delete. + * + * @since 3.16.0 + */ +export interface FileDelete { + + /** + * A file:// URI for the location of the file/folder being deleted. + */ + uri: string; +} +``` + +_Response_: +* result:`WorkspaceEdit` \| `null` +* error: code and message set in case an exception happens during the `workspace/willDeleteFiles` request. diff --git a/_specifications/lsp/3.17/workspace/willRenameFiles.md b/_specifications/lsp/3.17/workspace/willRenameFiles.md new file mode 100644 index 000000000..1932678c2 --- /dev/null +++ b/_specifications/lsp/3.17/workspace/willRenameFiles.md @@ -0,0 +1,66 @@ +#### WillRenameFiles Request (:leftwards_arrow_with_hook:) + +The will rename files request is sent from the client to the server before files are actually renamed as long as the rename is triggered from within the client either by a user action or by applying a workspace edit. The request can return a WorkspaceEdit which will be applied to workspace before the files are renamed. Please note that clients might drop results if computing the edit took too long or if a server constantly fails on this request. This is done to keep renames fast and reliable. + +_Client Capability_: +* property name (optional): `workspace.fileOperations.willRename` +* property type: `boolean` + +The capability indicates that the client supports sending `workspace/willRenameFiles` requests. + +_Server Capability_: +* property name (optional): `workspace.fileOperations.willRename` +* property type: `FileOperationRegistrationOptions` + +The capability indicates that the server is interested in receiving `workspace/willRenameFiles` requests. + +_Registration Options_: none + +_Request_: +* method: 'workspace/willRenameFiles' +* params: `RenameFilesParams` defined as follows: + +
+ +```typescript +/** + * The parameters sent in notifications/requests for user-initiated renames + * of files. + * + * @since 3.16.0 + */ +export interface RenameFilesParams { + + /** + * An array of all files/folders renamed in this operation. When a folder + * is renamed, only the folder will be included, and not its children. + */ + files: FileRename[]; +} +``` + +
+ +```typescript +/** + * Represents information on a file/folder rename. + * + * @since 3.16.0 + */ +export interface FileRename { + + /** + * A file:// URI for the original location of the file/folder being renamed. + */ + oldUri: string; + + /** + * A file:// URI for the new location of the file/folder being renamed. + */ + newUri: string; +} +``` + +_Response_: +* result:`WorkspaceEdit` \| `null` +* error: code and message set in case an exception happens during the `workspace/willRenameFiles` request. diff --git a/_specifications/lsp/3.17/workspace/workspaceFolders.md b/_specifications/lsp/3.17/workspace/workspaceFolders.md new file mode 100644 index 000000000..409266bca --- /dev/null +++ b/_specifications/lsp/3.17/workspace/workspaceFolders.md @@ -0,0 +1,62 @@ +##### Workspace folders request (:arrow_right_hook:) + +> *Since version 3.6.0* + +Many tools support more than one root folder per workspace. Examples for this are VS Code's multi-root support, Atom's project folder support or Sublime's project support. If a client workspace consists of multiple roots then a server typically needs to know about this. The protocol up to now assumes one root folder which is announced to the server by the `rootUri` property of the `InitializeParams`. If the client supports workspace folders and announces them via the corresponding `workspaceFolders` client capability, the `InitializeParams` contain an additional property `workspaceFolders` with the configured workspace folders when the server starts. + +The `workspace/workspaceFolders` request is sent from the server to the client to fetch the current open list of workspace folders. Returns `null` in the response if only a single file is open in the tool. Returns an empty array if a workspace is open but no folders are configured. + +_Client Capability_: +* property path (optional): `workspace.workspaceFolders` +* property type: `boolean` + +_Server Capability_: +* property path (optional): `workspace.workspaceFolders` +* property type: `WorkspaceFoldersServerCapabilities` defined as follows: + +
+ +```typescript +export interface WorkspaceFoldersServerCapabilities { + /** + * The server has support for workspace folders + */ + supported?: boolean; + + /** + * Whether the server wants to receive workspace folder + * change notifications. + * + * If a string is provided, the string is treated as an ID + * under which the notification is registered on the client + * side. The ID can be used to unregister for these events + * using the `client/unregisterCapability` request. + */ + changeNotifications?: string | boolean; +} +``` + +_Request_: +* method: `workspace/workspaceFolders` +* params: none + +_Response_: +* result: `WorkspaceFolder[] | null` defined as follows: + +
+ +```typescript +export interface WorkspaceFolder { + /** + * The associated URI for this workspace folder. + */ + uri: DocumentUri; + + /** + * The name of the workspace folder. Used to refer to this + * workspace folder in the user interface. + */ + name: string; +} +``` +* error: code and message set in case an exception happens during the 'workspace/workspaceFolders' request