Skip to content

Commit

Permalink
Add support for completionList.applyKind to determine how values fr…
Browse files Browse the repository at this point in the history
…om `completionList.itemDefaults` and `completion` are combined. (#2018)

* Add support for `completionList.applyKind` to determine how values from `completionList.itemDefaults` and `completion` are combined.

Fixes #1802

* Update completion.md

* Simplify by removing distinction between null/undefined

* Use a single client capability + add ApplyKind enum/type

* Make this clearer

* Minor fixes

- commitCharacters isn't allowed to be null so no point mentioning this
- Fix missing quote
- Fix error in ApplyKind type (either needs "typeof" or to use literals, and other things use literals)

* Change ApplyKind to be integers

* Typos

---------

Co-authored-by: Dirk Bäumer <[email protected]>
  • Loading branch information
DanTup and dbaeumer authored Oct 8, 2024
1 parent dabf8b2 commit c6af121
Show file tree
Hide file tree
Showing 2 changed files with 120 additions and 1 deletion.
120 changes: 119 additions & 1 deletion _specifications/lsp/3.18/language/completion.md
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,21 @@ export interface CompletionClientCapabilities {
* @since 3.17.0
*/
itemDefaults?: string[];

/**
* Specifies whether the client supports `CompletionList.applyKind` to
* indicate how supported values from `completionList.itemDefaults`
* and `completion` will be combined.
*
* If a client supports `applyKind` it must support it for all fields
* that it supports that are listed in `CompletionList.applyKind`. This
* means when clients add support for new/future fields in completion
* items the MUST also support merge for them if those fields are
* defined in `CompletionList.applyKind`.
*
* @since 3.18.0
*/
applyKindSupport?: boolean;
}
}
```
Expand Down Expand Up @@ -338,7 +353,9 @@ export interface CompletionList {
* 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.
* also specifies a corresponding value, the rules for combining these are
* defined by `applyKinds` (if the client supports it), defaulting to
* ApplyKind.Replace.
*
* Servers are only allowed to return default values if the client
* signals support for this via the `completionList.itemDefaults`
Expand Down Expand Up @@ -386,6 +403,73 @@ export interface CompletionList {
data?: LSPAny;
}

/**
* Specifies how fields from a completion item should be combined with those
* from `completionList.itemDefaults`.
*
* If unspecified, all fields will be treated as ApplyKind.Replace.
*
* If a field's value is ApplyKind.Replace, the value from a completion item
* (if provided and not `null`) will always be used instead of the value
* from `completionItem.itemDefaults`.
*
* If a field's value is ApplyKind.Merge, the values will be merged using
* the rules defined against each field below.
*
* Servers are only allowed to return `applyKind` if the client
* signals support for this via the `completionList.applyKindSupport`
* capability.
*
* @since 3.18.0
*/
applyKind?: {
/**
* Specifies whether commitCharacters on a completion will replace or be
* merged with those in `completionList.itemDefaults.commitCharacters`.
*
* If ApplyKind.Replace, the commit characters from the completion item
* will always be used unless not provided, in which case those from
* `completionList.itemDefaults.commitCharacters` will be used. An
* empty list can be used if a completion item does not have any commit
* characters and also should not use those from
* `completionList.itemDefaults.commitCharacters`.
*
* If ApplyKind.Merge the commitCharacters for the completion will be
* the union of all values in both
* `completionList.itemDefaults.commitCharacters` and the completion's
* own `commitCharacters`.
*
* @since 3.18.0
*/
commitCharacters?: ApplyKind;

/**
* Specifies whether the `data` field on a completion will replace or
* be merged with data from `completionList.itemDefaults.data`.
*
* If ApplyKind.Replace, the data from the completion item will be used
* if provided (and not `null`), otherwise
* `completionList.itemDefaults.data` will be used. An empty object can
* be used if a completion item does not have any data but also should
* not use the value from `completionList.itemDefaults.data`.
*
* If ApplyKind.Merge, a shallow merge will be performed between
* `completionList.itemDefaults.data` and the completion's own data
* using the following rules:
*
* - If a completion's `data` field is not provided (or `null`), the
* entire `data` field from `completionList.itemDefaults.data` will be
* used as-is.
* - If a completion's `data` field is provided, each field will
* overwrite the field of the same name in
* `completionList.itemDefaults.data` but no merging of nested fields
* within that value will occur.
*
* @since 3.18.0
*/
data?: ApplyKind;
}

/**
* The completion items.
*/
Expand Down Expand Up @@ -525,6 +609,40 @@ export interface CompletionItemLabelDetails {
}
```

<div class="anchorHolder"><a href="#applyKind" name="applyKind" class="linkableAnchor"></a></div>

```typescript
/**
* Defines how values from a set of defaults and an individual item will be
* merged.
*
* @since 3.18.0
*/
export namespace ApplyKind {
/**
* The value from the individual item (if provided and not `null`) will be
* used instead of the default.
*/
export const Replace: 1 = 1;

/**
* The value from the item will be merged with the default.
*
* The specific rules for mergeing values are defined against each field
* that supports merging.
*/
export const Merge: 2 = 2;
}

/**
* Defines how values from a set of defaults and an individual item will be
* merged.
*
* @since 3.18.0
*/
export type ApplyKind = 1 | 2;
```

<div class="anchorHolder"><a href="#completionItem" name="completionItem" class="linkableAnchor"></a></div>

```typescript
Expand Down
1 change: 1 addition & 0 deletions _specifications/lsp/3.18/specification.md
Original file line number Diff line number Diff line change
Expand Up @@ -737,6 +737,7 @@ Since 3.17 there is a meta model describing the LSP protocol:
* Support for snippets in text document edits.
* Support for debug message kind.
* Client capability to enumerate properties that can be resolved for code lenses.
* Added support for `completionList.applyKind` to determine how values from `completionList.itemDefaults` and `completion` are combined.


#### <a href="#version_3_17_0" name="version_3_17_0" class="anchor">3.17.0 (05/10/2022)</a>
Expand Down

0 comments on commit c6af121

Please sign in to comment.