From d0e0e766340901c6053bd4c9495db62f85962d33 Mon Sep 17 00:00:00 2001 From: Cristopher Claeys <47442230+c-claeys@users.noreply.github.com> Date: Tue, 4 Jul 2023 10:50:54 +0200 Subject: [PATCH] Add textDocument/inlineCompletion to 3.18 (#1673) * Add textDocument/inlineCompletion * Define return types in metaModel.json * Copy generated metaModel.json from node pull/1190 * Add feature detail * Update initial .md description --- _data/linkableTypes.yml | 22 +- .../lsp/3.18/general/initialize.md | 14 + .../lsp/3.18/language/inlineCompletion.md | 242 +++++++++++++ .../lsp/3.18/metaModel/metaModel.json | 325 ++++++++++++++++-- _specifications/lsp/3.18/specification.md | 1 + 5 files changed, 582 insertions(+), 22 deletions(-) create mode 100644 _specifications/lsp/3.18/language/inlineCompletion.md diff --git a/_data/linkableTypes.yml b/_data/linkableTypes.yml index 2505dc406..af652e182 100644 --- a/_data/linkableTypes.yml +++ b/_data/linkableTypes.yml @@ -863,4 +863,24 @@ - type: 'WorkspaceDocumentDiagnosticReport' link: '#workspaceDocumentDiagnosticReport' - type: 'WorkspaceDiagnosticReportPartialResult' - link: '#workspaceDiagnosticReportPartialResult' \ No newline at end of file + link: '#workspaceDiagnosticReportPartialResult' + - type: 'textDocument/inlineCompletion' + link: '#textDocument_inlineCompletion' + - type: 'InlineCompletionClientCapabilities' + link: '#inlineCompletionClientCapabilities' + - type: 'InlineCompletionOptions' + link: '#inlineCompletionOptions' + - type: 'InlineCompletionRegistrationOptions' + link: '#inlineCompletionRegistrationOptions' + - type: 'InlineCompletionParams' + link: '#inlineCompletionParams' + - type: 'InlineCompletionContext' + link: '#inlineCompletionContext' + - type: 'InlineCompletionTriggerKind' + link: '#inlineCompletionTriggerKind' + - type: 'SelectedCompletionInfo' + link: '#selectedCompletionInfo' + - type: 'InlineCompletionList' + link: '#inlineCompletionList' + - type: 'InlineCompletionItem' + link: '#inlineCompletionItem' \ No newline at end of file diff --git a/_specifications/lsp/3.18/general/initialize.md b/_specifications/lsp/3.18/general/initialize.md index 70f998b69..c633c0e89 100644 --- a/_specifications/lsp/3.18/general/initialize.md +++ b/_specifications/lsp/3.18/general/initialize.md @@ -288,6 +288,13 @@ export interface TextDocumentClientCapabilities { * @since 3.17.0 */ diagnostic?: DiagnosticClientCapabilities; + + /** + * Capabilities specific to the `textDocument/inlineCompletion` request. + * + * @since 3.18.0 + */ + inlineCompletion?: InlineCompletionClientCapabilities; } ``` @@ -870,6 +877,13 @@ interface ServerCapabilities { */ workspaceSymbolProvider?: boolean | WorkspaceSymbolOptions; + /** + * The server provides inline completions. + * + * @since 3.18.0 + */ + inlineCompletionProvider?: boolean | InlineCompletionOptions; + /** * Workspace specific server capabilities */ diff --git a/_specifications/lsp/3.18/language/inlineCompletion.md b/_specifications/lsp/3.18/language/inlineCompletion.md new file mode 100644 index 000000000..f52c98c5c --- /dev/null +++ b/_specifications/lsp/3.18/language/inlineCompletion.md @@ -0,0 +1,242 @@ +#### Inline Completion Request (:leftwards_arrow_with_hook:) + +> *Since version 3.18.0* + +The inline completion request is sent from the client to the server to compute inline completions for a given text document either explicitly by a user gesture or implicitly when typing. + +Inline completion items usually complete bigger portions of text (e.g. whole methods, ...) and in contrast to completions items can complete code that might be syntactically or semantically incorrect. + +Due to this inline completion items are usually not suited to be presented in normal code completion widgets like a list of items. One possible approach can be to present the information inline in the editor with lower contrast. + +When multiple inline completion items are returned, the client may decide whether the user can cycle through them or if they, along with their `filterText`, are merely for filtering if the user continues to type without yet accepting the inline completion item. + +Clients may choose to send information about the user's current completion selection via context if completions are visible at the same time. In this case, returned inline completions should extend the text of the provided completion. + + +_Client Capability_: +* property name (optional): `textDocument.inlineCompletion` +* property type: `InlineCompletionClientCapabilities` defined as follows: + +
+ +```typescript +/** + * Client capabilities specific to inline completions. + * + * @since 3.18.0 + */ +export interface InlineCompletionClientCapabilities { + /** + * Whether implementation supports dynamic registration for inline + * completion providers. + */ + dynamicRegistration?: boolean; +} +``` + +_Server Capability_: +* property name (optional): `inlineCompletionProvider` +* property type: `InlineCompletionOptions` defined as follows: + +
+ +```typescript +/** + * Inline completion options used during static registration. + * + * @since 3.18.0 + */ +export interface InlineCompletionOptions extends WorkDoneProgressOptions { +} +``` + +_Registration Options_: `InlineCompletionRegistrationOptions` defined as follows: + +
+ +```typescript +/** + * Inline completion options used during static or dynamic registration. + * + * @since 3.18.0 + */ +export interface InlineCompletionRegistrationOptions extends + InlineCompletionOptions, TextDocumentRegistrationOptions, + StaticRegistrationOptions { +} +``` + +_Request_: +* method: `textDocument/inlineCompletion` +* params: `InlineCompletionParams` defined as follows: + +
+ +```typescript +/** + * A parameter literal used in inline completion requests. + * + * @since 3.18.0 + */ +export interface InlineCompletionParams extends TextDocumentPositionParams, + WorkDoneProgressParams { + /** + * Additional information about the context in which inline completions + * were requested. + */ + context: InlineCompletionContext; +} +``` + +
+ +```typescript +/** + * Provides information about the context in which an inline completion was + * requested. + * + * @since 3.18.0 + */ +export interface InlineCompletionContext { + /** + * Describes how the inline completion was triggered. + */ + triggerKind: InlineCompletionTriggerKind; + + /** + * Provides information about the currently selected item in the + * autocomplete widget if it is visible. + * + * If set, provided inline completions must extend the text of the + * selected item and use the same range, otherwise they are not shown as + * preview. + * As an example, if the document text is `console.` and the selected item + * is `.log` replacing the `.` in the document, the inline completion must + * also replace `.` and start with `.log`, for example `.log()`. + * + * Inline completion providers are requested again whenever the selected + * item changes. + */ + selectedCompletionInfo?: SelectedCompletionInfo; +} +``` + +
+ +```typescript +/** + * Describes how an {@link InlineCompletionItemProvider inline completion + * provider} was triggered. + * + * @since 3.18.0 + */ +export namespace InlineCompletionTriggerKind { + /** + * Completion was triggered explicitly by a user gesture. + * Return multiple completion items to enable cycling through them. + */ + export const Invoke: 0 = 0; + + /** + * Completion was triggered automatically while editing. + * It is sufficient to return a single completion item in this case. + */ + export const Automatic: 1 = 1; +} + +export type InlineCompletionTriggerKind = 0 | 1; +``` + +
+ +```typescript +/** + * Describes the currently selected completion item. + * + * @since 3.18.0 + */ +export interface SelectedCompletionInfo { + /** + * The range that will be replaced if this completion item is accepted. + */ + range: Range; + + /** + * The text the range will be replaced with if this completion is + * accepted. + */ + text: string; +} +``` + +_Response_: +* result: `InlineCompletionItem[]` \| `InlineCompletionList` \| `null` defined as follows: + +
+ +```typescript +/** + * Represents a collection of {@link InlineCompletionItem inline completion + * items} to be presented in the editor. + * + * @since 3.18.0 + */ +export interface InlineCompletionList { + /** + * The inline completion items. + */ + items: InlineCompletionItem[]; +} +``` + +
+ +```typescript +/** + * An inline completion item represents a text snippet that is proposed inline + * to complete text that is being typed. + * + * @since 3.18.0 + */ +export interface InlineCompletionItem { + /** + * The text to replace the range with. Must be set. + * Is used both for the preview and the accept operation. + */ + insertText: string; + + /** + * A text that is used to decide if this inline completion should be + * shown. When `falsy` the {@link InlineCompletionItem.insertText} is + * used. + * + * An inline completion is shown if the text to replace is a prefix of the + * filter text. + */ + filterText?: string; + + /** + * The range to replace. + * Must begin and end on the same line. + * + * Prefer replacements over insertions to provide a better experience when + * the user deletes typed text. + */ + range?: Range; + + /** + * An optional {@link Command} that is executed *after* inserting this + * completion. + */ + command?: Command; + + /** + * The format of the insert text. The format applies to the `insertText`. + * If omitted defaults to `InsertTextFormat.PlainText`. + */ + insertTextFormat?: InsertTextFormat; +} +``` + + +* error: code and message set in case an exception happens during the inline completions request. diff --git a/_specifications/lsp/3.18/metaModel/metaModel.json b/_specifications/lsp/3.18/metaModel/metaModel.json index 4903cf061..526c07099 100644 --- a/_specifications/lsp/3.18/metaModel/metaModel.json +++ b/_specifications/lsp/3.18/metaModel/metaModel.json @@ -1,6 +1,6 @@ { "metaData": { - "version": "3.17.0" + "version": "3.18.0" }, "requests": [ { @@ -975,6 +975,47 @@ "documentation": "The diagnostic refresh request definition.\n\n@since 3.17.0", "since": "3.17.0" }, + { + "method": "textDocument/inlineCompletion", + "result": { + "kind": "or", + "items": [ + { + "kind": "reference", + "name": "InlineCompletionList" + }, + { + "kind": "array", + "element": { + "kind": "reference", + "name": "InlineCompletionItem" + } + }, + { + "kind": "base", + "name": "null" + } + ] + }, + "messageDirection": "clientToServer", + "params": { + "kind": "reference", + "name": "InlineCompletionParams" + }, + "partialResult": { + "kind": "array", + "element": { + "kind": "reference", + "name": "InlineCompletionItem" + } + }, + "registrationOptions": { + "kind": "reference", + "name": "InlineCompletionRegistrationOptions" + }, + "documentation": "A request to provide inline completions in a document. The request's parameter is of\ntype {@link InlineCompletionParams}, the response is of type\n{@link InlineCompletion InlineCompletion[]} or a Thenable that resolves to such.\n\n@since 3.18.0", + "since": "3.18.0" + }, { "method": "client/registerCapability", "result": { @@ -4035,6 +4076,123 @@ "documentation": "The params sent in a close notebook document notification.\n\n@since 3.17.0", "since": "3.17.0" }, + { + "name": "InlineCompletionParams", + "properties": [ + { + "name": "context", + "type": { + "kind": "reference", + "name": "InlineCompletionContext" + }, + "documentation": "Additional information about the context in which inline completions were\nrequested." + } + ], + "extends": [ + { + "kind": "reference", + "name": "TextDocumentPositionParams" + } + ], + "mixins": [ + { + "kind": "reference", + "name": "WorkDoneProgressParams" + } + ], + "documentation": "A parameter literal used in inline completion requests.\n\n@since 3.18.0", + "since": "3.18.0" + }, + { + "name": "InlineCompletionList", + "properties": [ + { + "name": "items", + "type": { + "kind": "array", + "element": { + "kind": "reference", + "name": "InlineCompletionItem" + } + }, + "documentation": "The inline completion items" + } + ], + "documentation": "Represents a collection of {@link InlineCompletionItem inline completion items} to be presented in the editor." + }, + { + "name": "InlineCompletionItem", + "properties": [ + { + "name": "insertText", + "type": { + "kind": "base", + "name": "string" + }, + "documentation": "The text to replace the range with. Must be set." + }, + { + "name": "insertTextFormat", + "type": { + "kind": "reference", + "name": "InsertTextFormat" + }, + "optional": true, + "documentation": "The format of the insert text. The format applies to the `insertText`. If omitted defaults to `InsertTextFormat.PlainText`." + }, + { + "name": "filterText", + "type": { + "kind": "base", + "name": "string" + }, + "optional": true, + "documentation": "A text that is used to decide if this inline completion should be shown. When `falsy` the {@link InlineCompletionItem.insertText} is used." + }, + { + "name": "range", + "type": { + "kind": "reference", + "name": "Range" + }, + "optional": true, + "documentation": "The range to replace. Must begin and end on the same line." + }, + { + "name": "command", + "type": { + "kind": "reference", + "name": "Command" + }, + "optional": true, + "documentation": "An optional {@link Command} that is executed *after* inserting this completion." + } + ], + "documentation": "An inline completion item represents a text snippet that is proposed inline to complete text that is being typed.\n\n@since 3.18.0", + "since": "3.18.0" + }, + { + "name": "InlineCompletionRegistrationOptions", + "properties": [], + "extends": [ + { + "kind": "reference", + "name": "InlineCompletionOptions" + }, + { + "kind": "reference", + "name": "TextDocumentRegistrationOptions" + } + ], + "mixins": [ + { + "kind": "reference", + "name": "StaticRegistrationOptions" + } + ], + "documentation": "Inline completion options used during static or dynamic registration.\n\n@since 3.18.0", + "since": "3.18.0" + }, { "name": "RegistrationParams", "properties": [ @@ -7594,6 +7752,42 @@ "documentation": "A literal to identify a notebook document in the client.\n\n@since 3.17.0", "since": "3.17.0" }, + { + "name": "InlineCompletionContext", + "properties": [ + { + "name": "triggerKind", + "type": { + "kind": "reference", + "name": "InlineCompletionTriggerKind" + }, + "documentation": "Describes how the inline completion was triggered." + }, + { + "name": "selectedCompletionInfo", + "type": { + "kind": "reference", + "name": "SelectedCompletionInfo" + }, + "optional": true, + "documentation": "Provides information about the currently selected item in the autocomplete widget if it is visible." + } + ], + "documentation": "Provides information about the context in which an inline completion was requested.\n\n@since 3.18.0", + "since": "3.18.0" + }, + { + "name": "InlineCompletionOptions", + "mixins": [ + { + "kind": "reference", + "name": "WorkDoneProgressOptions" + } + ], + "properties": [], + "documentation": "Inline completion options used during static registration.\n\n@since 3.18.0", + "since": "3.18.0" + }, { "name": "Registration", "properties": [ @@ -8398,6 +8592,25 @@ "documentation": "The server has support for pull model diagnostics.\n\n@since 3.17.0", "since": "3.17.0" }, + { + "name": "inlineCompletionProvider", + "type": { + "kind": "or", + "items": [ + { + "kind": "base", + "name": "boolean" + }, + { + "kind": "reference", + "name": "InlineCompletionOptions" + } + ] + }, + "optional": true, + "documentation": "Inline completion options used during static registration.\n\n@since 3.18.0", + "since": "3.18.0" + }, { "name": "workspace", "type": { @@ -9671,6 +9884,29 @@ "documentation": "A change describing how to move a `NotebookCell`\narray from state S to S'.\n\n@since 3.17.0", "since": "3.17.0" }, + { + "name": "SelectedCompletionInfo", + "properties": [ + { + "name": "range", + "type": { + "kind": "reference", + "name": "Range" + }, + "documentation": "The range that will be replaced if this completion item is accepted." + }, + { + "name": "text", + "type": { + "kind": "base", + "name": "string" + }, + "documentation": "The text the range will be replaced with if this completion is accepted." + } + ], + "documentation": "Describes the currently selected completion item.\n\n@since 3.18.0", + "since": "3.18.0" + }, { "name": "ClientCapabilities", "properties": [ @@ -10606,6 +10842,16 @@ "optional": true, "documentation": "Capabilities specific to the diagnostic pull model.\n\n@since 3.17.0", "since": "3.17.0" + }, + { + "name": "inlineCompletion", + "type": { + "kind": "reference", + "name": "InlineCompletionClientCapabilities" + }, + "optional": true, + "documentation": "Client capabilities specific to inline completions.\n\n@since 3.18.0", + "since": "3.18.0" } ], "documentation": "Text document specific client capabilities." @@ -12430,6 +12676,22 @@ "documentation": "Client capabilities specific to diagnostic pull requests.\n\n@since 3.17.0", "since": "3.17.0" }, + { + "name": "InlineCompletionClientCapabilities", + "properties": [ + { + "name": "dynamicRegistration", + "type": { + "kind": "base", + "name": "boolean" + }, + "optional": true, + "documentation": "Whether implementation supports dynamic registration for inline completion providers." + } + ], + "documentation": "Client capabilities specific to inline completions.\n\n@since 3.18.0", + "since": "3.18.0" + }, { "name": "NotebookDocumentSyncClientCapabilities", "properties": [ @@ -13051,6 +13313,26 @@ "documentation": "Inlay hint kinds.\n\n@since 3.17.0", "since": "3.17.0" }, + { + "name": "InsertTextFormat", + "type": { + "kind": "base", + "name": "uinteger" + }, + "values": [ + { + "name": "PlainText", + "value": 1, + "documentation": "The primary text to be inserted is treated as a plain string." + }, + { + "name": "Snippet", + "value": 2, + "documentation": "The primary text to be inserted is treated as a snippet.\n\nA snippet can define tab stops and placeholders with `$1`, `$2`\nand `${3:foo}`. `$0` defines the final tab stop, it defaults to\nthe end of the snippet. Placeholders with equal identifiers are linked,\nthat is typing in one will update others too.\n\nSee also: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#snippet_syntax" + } + ], + "documentation": "Defines whether the insert text in a completion item should be interpreted as\nplain text or a snippet." + }, { "name": "MessageType", "type": { @@ -13257,26 +13539,6 @@ "documentation": "Completion item tags are extra annotations that tweak the rendering of a completion\nitem.\n\n@since 3.15.0", "since": "3.15.0" }, - { - "name": "InsertTextFormat", - "type": { - "kind": "base", - "name": "uinteger" - }, - "values": [ - { - "name": "PlainText", - "value": 1, - "documentation": "The primary text to be inserted is treated as a plain string." - }, - { - "name": "Snippet", - "value": 2, - "documentation": "The primary text to be inserted is treated as a snippet.\n\nA snippet can define tab stops and placeholders with `$1`, `$2`\nand `${3:foo}`. `$0` defines the final tab stop, it defaults to\nthe end of the snippet. Placeholders with equal identifiers are linked,\nthat is typing in one will update others too.\n\nSee also: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#snippet_syntax" - } - ], - "documentation": "Defines whether the insert text in a completion item should be interpreted as\nplain text or a snippet." - }, { "name": "InsertTextMode", "type": { @@ -13424,6 +13686,27 @@ ], "documentation": "Describes the content type that a client supports in various\nresult literals like `Hover`, `ParameterInfo` or `CompletionItem`.\n\nPlease note that `MarkupKinds` must not start with a `$`. This kinds\nare reserved for internal usage." }, + { + "name": "InlineCompletionTriggerKind", + "type": { + "kind": "base", + "name": "uinteger" + }, + "values": [ + { + "name": "Invoked", + "value": 0, + "documentation": "Completion was triggered explicitly by a user gesture." + }, + { + "name": "Automatic", + "value": 1, + "documentation": "Completion was triggered automatically while editing." + } + ], + "documentation": "Describes how an {@link InlineCompletionItemProvider inline completion provider} was triggered.\n\n@since 3.18.0", + "since": "3.18.0" + }, { "name": "PositionEncodingKind", "type": { diff --git a/_specifications/lsp/3.18/specification.md b/_specifications/lsp/3.18/specification.md index 78a20767c..44840408d 100644 --- a/_specifications/lsp/3.18/specification.md +++ b/_specifications/lsp/3.18/specification.md @@ -655,6 +655,7 @@ Language Features provide the actual smarts in the language server protocol. The {% include_relative language/onTypeFormatting.md %} {% include_relative language/rename.md %} {% include_relative language/linkedEditingRange.md %} +{% include_relative language/inlineCompletion.md %} ### Workspace Features