Language Server Protocol Spezifikation - 3.17
Dieses Dokument beschreibt die Version 3.17.x des Language Server Protocol. Eine Implementierung für Node der Version 3.17.x des Protokolls finden Sie hier.
Hinweis: Änderungen an dieser Spezifikation können über einen Pull-Request gegen dieses Markdown-Dokument gemacht werden.
Was ist neu in 3.17
Alle neuen Funktionen von 3.17 sind mit einem entsprechenden Text mit der Versionsnummer 3.17 oder mit der @since 3.17.0-Annotation im JSDoc gekennzeichnet. Hauptneuerungen sind: Typenhierarchie, Inline-Werte, Inlay-Hints, Unterstützung für Notebook-Dokumente und ein Meta-Modell, das die LSP-Version 3.17 beschreibt.
Eine detaillierte Liste der Änderungen finden Sie im Änderungsprotokoll.
Die Versionsnummer der Spezifikation wird verwendet, um Features in einer neuen Spezifikationsversion zu gruppieren und ihr erstes Auftreten zu referenzieren. Features in der Spezifikation bleiben durch sogenannte Capability-Flags kompatibel, die zwischen Client und Server während der Initialisierung ausgetauscht werden.
Basisprotokoll
Das Basisprotokoll besteht aus einem Header- und einem Inhaltsteil (vergleichbar mit HTTP). Der Header- und Inhaltsteil werden durch ein „\r\n“ getrennt.
Header-Teil
Der Headerteil besteht aus Header-Feldern. Jedes Header-Feld besteht aus einem Namen und einem Wert, die durch „: “ (ein Doppelpunkt und ein Leerzeichen) getrennt sind. Die Struktur der Header-Felder entspricht dem HTTP-Semantik. Jedes Header-Feld wird durch „\r\n“ beendet. Wenn man bedenkt, dass das letzte Header-Feld und der gesamte Header selbst jeweils mit „\r\n“ beendet werden und dass mindestens ein Header zwingend erforderlich ist, bedeutet dies, dass zwei „\r\n“-Sequenzen immer unmittelbar vor dem Inhaltsteil einer Nachricht stehen.
Aktuell werden folgende Header-Felder unterstützt
| Name des Header-Feldes | Wert-Typ | Beschreibung |
|---|---|---|
| Content-Length | number | Die Länge des Inhaltsteils in Bytes. Dieser Header ist erforderlich. |
| Content-Type | string | Der MIME-Typ des Inhaltsteils. Standardmäßig `application/vscode-jsonrpc; charset=utf-8` |
Der Header-Teil wird mit der ‚ascii‘-Kodierung codiert. Dies schließt die ‚\r\n‘, die den Header- und den Inhaltsteil trennen, mit ein.
Inhaltsteil
Enthält den eigentlichen Inhalt der Nachricht. Der Inhaltsteil einer Nachricht verwendet JSON-RPC, um Anfragen, Antworten und Benachrichtigungen zu beschreiben. Der Inhaltsteil wird mit dem im Feld `Content-Type` angegebenen Zeichensatz codiert. Er standardmäßig auf utf-8, was derzeit die einzige unterstützte Codierung ist. Wenn ein Server oder Client einen Header mit einer anderen Codierung als utf-8 empfängt, sollte er mit einem Fehler antworten.
(Frühere Versionen des Protokolls verwendeten die Zeichenkettenkonstante utf8, die gemäß der Spezifikation keine korrekte Kodierungskonstante ist.) Aus Gründen der Abwärtskompatibilität wird dringend empfohlen, dass ein Client und ein Server die Zeichenkette utf8 als utf-8 behandeln.
Beispiel
Content-Length: ...\r\n
\r\n
{
"jsonrpc": "2.0",
"id": 1,
"method": "textDocument/completion",
"params": {
...
}
}
Basisprotokoll JSON-Strukturen
Die folgenden TypeScript-Definitionen beschreiben das Basis JSON-RPC-Protokoll
Basistypen
Das Protokoll verwendet die folgenden Definitionen für ganze Zahlen, vorzeichenlose ganze Zahlen, Dezimalzahlen, Objekte und Arrays.
/**
* Defines an integer number in the range of -2^31 to 2^31 - 1.
*/
export type integer = number;
/**
* Defines an unsigned integer number in the range of 0 to 2^31 - 1.
*/
export type uinteger = number;
/**
* Defines a decimal number. Since decimal numbers are very
* rare in the language server specification we denote the
* exact range with every decimal using the mathematics
* interval notation (e.g. [0, 1] denotes all decimals d with
* 0 <= d <= 1.
*/
export type decimal = number;
/**
* The LSP any type
*
* @since 3.17.0
*/
export type LSPAny = LSPObject | LSPArray | string | integer | uinteger |
decimal | boolean | null;
/**
* LSP object definition.
*
* @since 3.17.0
*/
export type LSPObject = { [key: string]: LSPAny };
/**
* LSP arrays.
*
* @since 3.17.0
*/
export type LSPArray = LSPAny[];
Abstrakte Nachricht
Eine allgemeine Nachricht gemäß JSON-RPC. Das Language Server Protocol verwendet immer „2.0“ als jsonrpc-Version.
interface Message {
jsonrpc: string;
}
Anfrage-Nachricht
Eine Anfrage-Nachricht zur Beschreibung einer Anfrage zwischen Client und Server. Jede verarbeitete Anfrage muss eine Antwort an den Absender der Anfrage zurücksenden.
interface RequestMessage extends Message {
/**
* The request id.
*/
id: integer | string;
/**
* The method to be invoked.
*/
method: string;
/**
* The method's params.
*/
params?: array | object;
}
Antwort-Nachricht
Eine Antwortnachricht, die als Ergebnis einer Anfrage gesendet wird. Wenn eine Anfrage keinen Ergebniswert liefert, muss der Empfänger einer Anfrage dennoch eine Antwortnachricht zurückgeben, um der JSON-RPC-Spezifikation zu entsprechen. Die Ergebnis-Eigenschaft der Antwortnachricht sollte in diesem Fall auf null gesetzt werden, um eine erfolgreiche Anfrage zu signalisieren.
interface ResponseMessage extends Message {
/**
* The request id.
*/
id: integer | string | null;
/**
* The result of a request. This member is REQUIRED on success.
* This member MUST NOT exist if there was an error invoking the method.
*/
result?: LSPAny;
/**
* The error object in case a request fails.
*/
error?: ResponseError;
}
interface ResponseError {
/**
* A number indicating the error type that occurred.
*/
code: integer;
/**
* A string providing a short description of the error.
*/
message: string;
/**
* A primitive or structured value that contains additional
* information about the error. Can be omitted.
*/
data?: LSPAny;
}
export namespace ErrorCodes {
// Defined by JSON-RPC
export const ParseError: integer = -32700;
export const InvalidRequest: integer = -32600;
export const MethodNotFound: integer = -32601;
export const InvalidParams: integer = -32602;
export const InternalError: integer = -32603;
/**
* This is the start range of JSON-RPC reserved error codes.
* It doesn't denote a real error code. No LSP error codes should
* be defined between the start and end range. For backwards
* compatibility the `ServerNotInitialized` and the `UnknownErrorCode`
* are left in the range.
*
* @since 3.16.0
*/
export const jsonrpcReservedErrorRangeStart: integer = -32099;
/** @deprecated use jsonrpcReservedErrorRangeStart */
export const serverErrorStart: integer = jsonrpcReservedErrorRangeStart;
/**
* Error code indicating that a server received a notification or
* request before the server received the `initialize` request.
*/
export const ServerNotInitialized: integer = -32002;
export const UnknownErrorCode: integer = -32001;
/**
* This is the end range of JSON-RPC reserved error codes.
* It doesn't denote a real error code.
*
* @since 3.16.0
*/
export const jsonrpcReservedErrorRangeEnd = -32000;
/** @deprecated use jsonrpcReservedErrorRangeEnd */
export const serverErrorEnd: integer = jsonrpcReservedErrorRangeEnd;
/**
* This is the start range of LSP reserved error codes.
* It doesn't denote a real error code.
*
* @since 3.16.0
*/
export const lspReservedErrorRangeStart: integer = -32899;
/**
* A request failed but it was syntactically correct, e.g the
* method name was known and the parameters were valid. The error
* message should contain human readable information about why
* the request failed.
*
* @since 3.17.0
*/
export const RequestFailed: integer = -32803;
/**
* The server cancelled the request. This error code should
* only be used for requests that explicitly support being
* server cancellable.
*
* @since 3.17.0
*/
export const ServerCancelled: integer = -32802;
/**
* The server detected that the content of a document got
* modified outside normal conditions. A server should
* NOT send this error code if it detects a content change
* in its unprocessed messages. The result even computed
* on an older state might still be useful for the client.
*
* If a client decides that a result is not of any use anymore
* the client should cancel the request.
*/
export const ContentModified: integer = -32801;
/**
* The client has canceled a request and a server has detected
* the cancel.
*/
export const RequestCancelled: integer = -32800;
/**
* This is the end range of LSP reserved error codes.
* It doesn't denote a real error code.
*
* @since 3.16.0
*/
export const lspReservedErrorRangeEnd: integer = -32800;
}
Benachrichtigungs-Nachricht
Eine Benachrichtigungs-Nachricht. Eine verarbeitete Benachrichtigungs-Nachricht darf keine Antwort zurücksenden. Sie funktionieren wie Ereignisse.
interface NotificationMessage extends Message {
/**
* The method to be invoked.
*/
method: string;
/**
* The notification's params.
*/
params?: array | object;
}
$ Benachrichtigungen und Anfragen
Benachrichtigungen und Anfragen, deren Methoden mit „$/“ beginnen, sind Nachrichten, die von der Protokollimplementierung abhängig sind und möglicherweise nicht auf allen Clients oder Servern implementiert werden können. Wenn beispielsweise die Serverimplementierung eine Single-Threaded-synchrone Programmiersprache verwendet, kann ein Server kaum auf eine $/cancelRequest-Benachrichtigung reagieren. Wenn ein Server oder Client Benachrichtigungen erhält, die mit „$/“ beginnen, steht es ihm frei, die Benachrichtigung zu ignorieren. Wenn ein Server oder Client eine Anfrage mit „$/“ erhält, muss er die Anfrage mit dem Fehlercode MethodNotFound (z. B. -32601) ablehnen.
Unterstützung für Abbruch (
)
Das Basisprotokoll bietet Unterstützung für den Abbruch von Anfragen. Um eine Anfrage abzubrechen, wird eine Benachrichtigungsnachricht mit den folgenden Eigenschaften gesendet
Benachrichtigung:
- Methode: ‚$/cancelRequest‘
- params:
CancelParams, wie folgt definiert
interface CancelParams {
/**
* The request id to cancel.
*/
id: integer | string;
}
Eine abgebrochene Anfrage muss immer noch vom Server zurückgegeben und eine Antwort gesendet werden. Sie kann nicht offen / hängend bleiben. Dies steht im Einklang mit dem JSON-RPC-Protokoll, das verlangt, dass jede Anfrage eine Antwort sendet. Darüber hinaus ermöglicht es die Rückgabe von Teilergebnissen beim Abbruch. Wenn die Anfrage eine Fehlermeldung beim Abbruch zurückgibt, wird empfohlen, den Fehlercode auf ErrorCodes.RequestCancelled zu setzen.
Fortschrittsunterstützung ( )
Seit Version 3.15.0
Das Basisprotokoll bietet auch die Unterstützung für die allgemeine Berichterstattung von Fortschritten. Dieser Mechanismus kann verwendet werden, um jede Art von Fortschritt zu melden, einschließlich Arbeitsfortschritt (normalerweise verwendet, um den Fortschritt in der Benutzeroberfläche mit einer Fortschrittsanzeige zu melden) und Teilergebnisfortschritt zur Unterstützung des Streamings von Ergebnissen.
Eine Fortschrittsbenachrichtigung hat die folgenden Eigenschaften
Benachrichtigung:
- Methode: ‚$/progress‘
- params:
ProgressParams, wie folgt definiert
type ProgressToken = integer | string;
interface ProgressParams<T> {
/**
* The progress token provided by the client or server.
*/
token: ProgressToken;
/**
* The progress data.
*/
value: T;
}
Der Fortschritt wird gegen ein Token gemeldet. Das Token unterscheidet sich von der Anfragedatenbank-ID, was es ermöglicht, Fortschritte "out of band" zu melden und auch für Benachrichtigungen.
Language Server Protocol
Das Language Server Protocol definiert eine Reihe von JSON-RPC-Anfrage-, Antwort- und Benachrichtigungsnachrichten, die über das oben genannte Basisprotokoll ausgetauscht werden. Dieser Abschnitt beginnt mit der Beschreibung der grundlegenden JSON-Strukturen, die im Protokoll verwendet werden. Das Dokument verwendet TypeScript-Schnittstellen im Strict-Modus, um diese zu beschreiben. Das bedeutet zum Beispiel, dass ein null-Wert explizit aufgeführt werden muss und dass eine obligatorische Eigenschaft aufgeführt werden muss, auch wenn ein falscher Wert existieren könnte. Basierend auf den grundlegenden JSON-Strukturen werden die tatsächlichen Anfragen mit ihren Antworten und die Benachrichtigungen beschrieben.
Ein Beispiel wäre eine Anfrage vom Client an den Server, um einen Hover-Wert für ein Symbol an einer bestimmten Position in einem Textdokument anzufordern. Die Methode der Anfrage wäre textDocument/hover mit Parametern wie diesen:
interface HoverParams {
textDocument: string; /** The text document's URI in string form */
position: { line: uinteger; character: uinteger; };
}
Das Ergebnis der Anfrage wäre der darzustellende Hover. In seiner einfachen Form kann dies eine Zeichenkette sein. Das Ergebnis sieht also so aus:
interface HoverResult {
value: string;
}
Bitte beachten Sie auch, dass ein Rückgabewert von null kein Ergebnis bedeutet. Es weist den Client nicht an, die Anfrage erneut zu senden.
Im Allgemeinen unterstützt das Language Server Protocol JSON-RPC-Nachrichten, das hier definierte Basisprotokoll verwendet jedoch eine Konvention, dass die an Anfrage-/Benachrichtigungsnachrichten übergebenen Parameter vom Typ object sein sollten (sofern überhaupt übergeben). Dies schließt jedoch nicht die Verwendung von Array-Parametertypen in benutzerdefinierten Nachrichten aus.
Das Protokoll geht derzeit davon aus, dass ein Server ein Werkzeug bedient. Es gibt derzeit keine Unterstützung im Protokoll, um einen Server zwischen verschiedenen Werkzeugen zu teilen. Eine solche gemeinsame Nutzung würde zusätzliche Protokolle erfordern, z. B. um ein Dokument zum Bearbeiten zu sperren, um gleichzeitiges Bearbeiten zu unterstützen.
Fähigkeiten
Nicht jeder Language Server kann alle im Protokoll definierten Funktionen unterstützen. LSP bietet daher „Capabilities“. Eine Capability gruppiert eine Reihe von Sprachfunktionen. Ein Entwicklungstool und der Language Server kündigen ihre unterstützten Funktionen mithilfe von Capabilities an. Beispielsweise kündigt ein Server an, dass er die textDocument/hover-Anfrage bearbeiten kann, aber möglicherweise nicht die workspace/symbol-Anfrage. Ebenso kündigt ein Entwicklungstool seine Fähigkeit an, Benachrichtigungen vor dem Speichern (`about to save`) zu senden, bevor ein Dokument gespeichert wird, damit ein Server Textänderungen berechnen kann, um das bearbeitete Dokument zu formatieren, bevor es gespeichert wird.
Der Satz von Capabilities wird zwischen Client und Server während der initialisieren-Anfrage ausgetauscht.
Reihenfolge von Anfragen, Benachrichtigungen und Antworten
Antworten auf Anfragen sollten ungefähr in der gleichen Reihenfolge gesendet werden, in der die Anfragen auf der Server- oder Clientseite erscheinen. Wenn also ein Server beispielsweise eine textDocument/completion-Anfrage und dann eine textDocument/signatureHelp-Anfrage empfängt, wird er normalerweise zuerst die Antwort für textDocument/completion und dann die Antwort für textDocument/signatureHelp zurückgeben.
Der Server kann jedoch entscheiden, eine parallele Ausführungsstrategie zu verwenden und Antworten in einer anderen Reihenfolge als die empfangenen Anfragen zurückzugeben. Der Server kann dies tun, solange diese Neuanordnung die Korrektheit der Antworten nicht beeinträchtigt. Zum Beispiel ist die Neuanordnung der Ergebnisse von textDocument/completion und textDocument/signatureHelp zulässig, da jede dieser Anfragen normalerweise die Ausgabe der anderen nicht beeinflusst. Auf der anderen Seite sollte der Server wahrscheinlich keine textDocument/definition- und textDocument/rename-Anfragen neu ordnen, da die Ausführung der letzteren das Ergebnis der ersteren beeinflussen kann.
Nachrichtendokumentation
Wie bereits erwähnt, definiert LSP eine Reihe von Anfragen, Antworten und Benachrichtigungen. Jede davon wird mit dem folgenden Format dokumentiert:
- Eine Kopfzeile, die die Anfrage beschreibt
- Ein optionaler Abschnitt *Client-Fähigkeit*, der die Client-Fähigkeit der Anfrage beschreibt. Dies beinhaltet den Pfad der Client-Fähigkeitseigenschaft und die JSON-Struktur.
- Ein optionaler Abschnitt *Server-Fähigkeit*, der die Server-Fähigkeit der Anfrage beschreibt. Dies beinhaltet den Pfad der Server-Fähigkeitseigenschaft und die JSON-Struktur. Clients sollten Server-Fähigkeiten ignorieren, die sie nicht verstehen (z. B. sollte die initialize-Anfrage in diesem Fall nicht fehlschlagen).
- Ein optionaler Abschnitt *Registrierungsoptionen*, der die Registrierungsoptionen beschreibt, falls die Anfrage oder Benachrichtigung dynamische Fähigkeitsregistrierung unterstützt. Siehe die register- und unregister-Anfragen für Details, wie dies funktioniert.
- Ein Abschnitt *Anfrage*, der das Format der gesendeten Anfrage beschreibt. Die Methode ist eine Zeichenkette, die die Anfrage identifiziert, die Parameter werden mit einer TypeScript-Schnittstelle dokumentiert. Es wird auch dokumentiert, ob die Anfrage Work Done-Fortschritt und Partial Result-Fortschritt unterstützt.
- Ein Abschnitt *Antwort*, der das Format der Antwort beschreibt. Das Ergebnis-Element beschreibt die zurückgegebenen Daten im Erfolgsfall. Das optionale Teilergebnis-Element beschreibt die zurückgegebenen Daten einer Teilergebnis-Benachrichtigung. Die error.data beschreibt die zurückgegebenen Daten im Fehlerfall. Bitte denken Sie daran, dass die Antwort im Fehlerfall bereits ein error.code und ein error.message Feld enthält. Diese Felder werden nur angegeben, wenn das Protokoll die Verwendung bestimmter Fehlercodes oder Nachrichten erzwingt. In Fällen, in denen der Server diese Werte frei wählen kann, werden sie hier nicht aufgeführt.
Grundlegende JSON-Strukturen
Es gibt eine ganze Reihe von JSON-Strukturen, die zwischen verschiedenen Anfragen und Benachrichtigungen gemeinsam genutzt werden. Ihre Struktur und ihre Fähigkeiten werden in diesem Abschnitt dokumentiert.
URI
URIs werden als Zeichenketten übertragen. Das Format der URIs ist in https://tools.ietf.org/html/rfc3986 definiert.
foo://example.com:8042/over/there?name=ferret#nose
\_/ \______________/\_________/ \_________/ \__/
| | | | |
scheme authority path query fragment
| _____________________|__
/ \ / \
urn:example:animal:ferret:nose
Wir pflegen auch ein Node-Modul, um eine Zeichenkette in scheme, authority, path, query und fragment URI-Komponenten zu parsen. Das GitHub-Repository ist https://github.com/Microsoft/vscode-uri, und das npm-Modul ist https://www.npmjs.com/package/vscode-uri.
Viele der Interfaces enthalten Felder, die der URI eines Dokuments entsprechen. Zur Verdeutlichung wird der Typ eines solchen Feldes als DocumentUri deklariert. Über das Netzwerk wird es weiterhin als Zeichenkette übertragen, aber dies garantiert, dass der Inhalt dieser Zeichenkette als gültige URI geparst werden kann.
Es ist Vorsicht geboten, die Kodierung in URIs zu behandeln. Einige Clients (wie VS Code) kodieren beispielsweise Doppelpunkte in Laufwerksbuchstaben, während andere dies nicht tun. Die folgenden URIs sind beide gültig, aber Clients und Server sollten konsistent mit der Form sein, die sie selbst verwenden, um sicherzustellen, dass die andere Partei sie nicht als unterschiedliche URIs interpretiert. Clients und Server sollten nicht davon ausgehen, dass die andere Partei auf die gleiche Weise kodiert (z. B. kann ein Client, der Doppelpunkte in Laufwerksbuchstaben kodiert, nicht davon ausgehen, dass Serverantworten kodierte Doppelpunkte enthalten). Dasselbe gilt für die Groß-/Kleinschreibung von Laufwerksbuchstaben – eine Partei sollte nicht davon ausgehen, dass die andere Partei Pfade mit Laufwerksbuchstaben zurückgibt, die die gleiche Groß-/Kleinschreibung haben wie sie selbst.
file:///c:/project/readme.md
file:///C%3A/project/readme.md
type DocumentUri = string;
Es gibt auch ein Tagging-Interface für normale, nicht-dokumentbezogene URIs. Es wird ebenfalls auf eine string abgebildet.
type URI = string;
Reguläre Ausdrücke
Reguläre Ausdrücke sind ein mächtiges Werkzeug und es gibt tatsächliche Anwendungsfälle für sie im Language Server Protocol. Der Nachteil ist jedoch, dass fast jede Programmiersprache ihre eigenen regulären Ausdrücke hat, sodass die Spezifikation sie nicht einfach als regulären Ausdruck bezeichnen kann. LSP verwendet daher einen zweistufigen Ansatz zur Unterstützung von regulären Ausdrücken:
- der Client kündigt an, welche reguläre Ausdrucksengine er verwenden wird. Dies ermöglicht es Servern, die für einen sehr spezifischen Client geschrieben wurden, die vollen regulären Ausdrucksmöglichkeiten des Clients zu nutzen.
- Die Spezifikation definiert eine Reihe von Funktionen für reguläre Ausdrücke, die von einem Client unterstützt werden sollten. Anstatt eine neue Spezifikation zu schreiben, verweist LSP auf die ECMAScript Regular Expression Specification und entfernt daraus Funktionen, die im Kontext von LSP nicht notwendig oder für andere Clients schwer zu implementieren sind.
Client Capability:
Die folgende Client-Capability wird verwendet, um die Regex-Engine eines Clients anzukündigen
- Eigenschaftspfad (optional):
general.regularExpressions - Eigenschaftstyp:
RegularExpressionsClientCapabilities, wie folgt definiert
/**
* Client capabilities specific to regular expressions.
*/
export interface RegularExpressionsClientCapabilities {
/**
* The engine's name.
*/
engine: string;
/**
* The engine's version.
*/
version?: string;
}
Die folgende Tabelle listet die bekannten Engine-Werte auf. Bitte beachten Sie, dass die Tabelle von der Community, die LSP in bestehende Clients integriert, gepflegt werden sollte. Es ist nicht das Ziel der Spezifikation, alle verfügbaren regulären Ausdrucksengines aufzulisten.
| Engine | Version | Dokumentation |
|---|---|---|
| ECMAScript | ES2020 |
ECMAScript 2020 & MDN |
Regulärer Ausdruck-Teilmengen:
Die folgenden Features der ECMAScript 2020-Spezifikation für reguläre Ausdrücke sind für einen Client NICHT zwingend erforderlich
- Assertions: Lookahead-Assertion, Negative Lookahead-Assertion, Lookbehind-Assertion, Negative Lookbehind-Assertion.
-
Zeichenklassen: Übereinstimmung von Steuerzeichen mit Hilfe von Caret-Notation (z. B.
\cX) und Übereinstimmung von UTF-16-Codeeinheiten (z. B.\uhhhh). - Gruppen und Bereiche: benannte Erfassungsgruppen.
- Unicode-Eigenschaftsfluchten: Keine der Funktionen muss unterstützt werden.
Das einzige reguläre Ausdrucksflag, das ein Client unterstützen muss, ist „i“, um eine Suche ohne Berücksichtigung der Groß-/Kleinschreibung anzugeben.
Aufzählungen
Das Protokoll unterstützt zwei Arten von Aufzählungen: (a) ganzzahlbasierte Aufzählungen und (b) zeichenkettenbasierte Aufzählungen. Ganzzahlbasierte Aufzählungen beginnen normalerweise mit 1. Diejenigen, die dies nicht tun, sind historisch bedingt und wurden zur Aufrechterhaltung der Abwärtskompatibilität beibehalten. Falls zutreffend, wird der Wertebereich einer Aufzählung von der definierenden Seite (z. B. Client oder Server) angekündigt und während des Initialisierungs-Handshakes an die andere Seite übermittelt. Ein Beispiel ist die CompletionItemKind-Aufzählung. Sie wird vom Client über die Client-Eigenschaft textDocument.completion.completionItemKind angekündigt.
Um die Weiterentwicklung von Aufzählungen zu unterstützen, sollte die verwendende Seite einer Aufzählung nicht fehlschlagen, wenn sie einen unbekannten Aufzählungswert erhält. Sie sollte ihn einfach als nicht nutzbaren Wert ignorieren und versuchen, den Wert bei Rundreisendurchläufen so gut wie möglich zu erhalten. Betrachten wir noch einmal die CompletionItemKind-Aufzählung: Wenn in einer zukünftigen Version der Spezifikation ein zusätzlicher Vervollständigungspositionstyp mit dem Wert n hinzugefügt und von einem Client angekündigt wird, sollte ein (älterer) Server, der den Wert nicht kennt, nicht fehlschlagen, sondern den Wert einfach als nutzbaren Elementtyp ignorieren.
Textdokumente
Das aktuelle Protokoll ist auf Textdokumente zugeschnitten, deren Inhalt als Zeichenkette dargestellt werden kann. Für Binärdokumente gibt es derzeit keine Unterstützung. Eine Position innerhalb eines Dokuments (siehe Positionsdefinition unten) wird als nullbasierter Zeilen- und Zeichenoffset ausgedrückt.
Neu in 3.17
Vor 3.17 basierten die Offsets immer auf einer UTF-16-Zeichenkettenrepräsentation. In einer Zeichenkette wie a𐐀b ist der Zeichenoffset des Zeichens a 0, der Zeichenoffset von 𐐀 ist 1 und der Zeichenoffset von b ist 3, da 𐐀 mit zwei Codeeinheiten in UTF-16 dargestellt wird. Seit 3.17 können Clients und Server eine andere Zeichenkodierungsrepräsentation (z. B. UTF-8) vereinbaren. Der Client kündigt seine unterstützte Kodierung über die Client-Capability general.positionEncodings an. Der Wert ist ein Array von Positionscodierungen, die der Client unterstützt, mit abnehmender Präferenz (d. h. die Codierung an Index 0 ist die am meisten bevorzugte). Um die Abwärtskompatibilität zu gewährleisten, ist die einzige obligatorische Codierung UTF-16, dargestellt durch die Zeichenkette utf-16. Der Server kann eine der vom Client angebotenen Codierungen auswählen und signalisiert diese Codierung über die capabilities.positionEncoding-Eigenschaft des initialize-Ergebnisses zurück an den Client. Wenn der Zeichenkettenwert utf-16 aus der Client-Capability general.positionEncodings fehlt, kann der Server davon ausgehen, dass der Client UTF-16 unterstützt. Wenn der Server die Positionscodierung in seinem initialize-Ergebnis weglässt, wird die Codierung standardmäßig auf den Zeichenkettenwert utf-16 gesetzt. Implementierungsüberlegungen: Da die Konvertierung von einer Codierung in eine andere den Inhalt der Datei / Zeile erfordert, erfolgt die Konvertierung am besten dort, wo die Datei gelesen wird, was normalerweise auf der Serverseite der Fall ist.
Um sicherzustellen, dass sowohl Client als auch Server die Zeichenkette in die gleiche Zeilenrepräsentation aufteilen, gibt das Protokoll die folgenden Zeilenende-Sequenzen an: „\n“, „\r\n“ und „\r“. Positionen sind unabhängig von den Zeilenendezeichen. Sie können also keine Position angeben, die \r|\n oder \n| bezeichnet, wobei | den Zeichenoffset darstellt.
export const EOL: string[] = ['\n', '\r\n', '\r'];
Position
Position in einem Textdokument, ausgedrückt als nullbasierte Zeile und nullbasierter Zeichen-Offset. Eine Position liegt zwischen zwei Zeichen, wie ein „Einfüge“-Cursor in einem Editor. Sonderwerte wie z. B. -1, um das Ende einer Zeile zu bezeichnen, werden nicht unterstützt.
interface Position {
/**
* Line position in a document (zero-based).
*/
line: uinteger;
/**
* Character offset on a line in a document (zero-based). The meaning of this
* offset is determined by the negotiated `PositionEncodingKind`.
*
* If the character value is greater than the line length it defaults back
* to the line length.
*/
character: uinteger;
}
Bei der Beschreibung von Positionen muss das Protokoll angeben, wie Offsets (insbesondere Zeichenoffsets) interpretiert werden sollen. Die entsprechende PositionEncodingKind wird während der Initialisierung zwischen Client und Server ausgehandelt.
/**
* A type indicating how positions are encoded,
* specifically what column offsets mean.
*
* @since 3.17.0
*/
export type PositionEncodingKind = string;
/**
* A set of predefined position encoding kinds.
*
* @since 3.17.0
*/
export namespace PositionEncodingKind {
/**
* Character offsets count UTF-8 code units (e.g bytes).
*/
export const UTF8: PositionEncodingKind = 'utf-8';
/**
* Character offsets count UTF-16 code units.
*
* This is the default and must always be supported
* by servers
*/
export const UTF16: PositionEncodingKind = 'utf-16';
/**
* Character offsets count UTF-32 code units.
*
* Implementation note: these are the same as Unicode code points,
* so this `PositionEncodingKind` may also be used for an
* encoding-agnostic representation of character offsets.
*/
export const UTF32: PositionEncodingKind = 'utf-32';
}
Range
Ein Bereich in einem Textdokument, ausgedrückt als (nullbasierte) Start- und Endpositionen. Ein Bereich ist vergleichbar mit einer Auswahl in einem Editor. Daher ist die Endposition exklusiv. Wenn Sie einen Bereich angeben möchten, der eine Zeile einschließlich der Zeilenendezeichen enthält, verwenden Sie eine Endposition, die den Beginn der nächsten Zeile bezeichnet. Zum Beispiel:
{
start: { line: 5, character: 23 },
end : { line: 6, character: 0 }
}
interface Range {
/**
* The range's start position.
*/
start: Position;
/**
* The range's end position.
*/
end: Position;
}
TextDocumentItem
Ein Element zur Übertragung eines Textdokuments vom Client zum Server.
interface TextDocumentItem {
/**
* The text document's URI.
*/
uri: DocumentUri;
/**
* The text document's language identifier.
*/
languageId: string;
/**
* The version number of this document (it will increase after each
* change, including undo/redo).
*/
version: integer;
/**
* The content of the opened text document.
*/
text: string;
}
Textdokumente haben eine Sprachkennung, um ein Dokument auf der Serverseite zu identifizieren, wenn es mehr als eine Sprache verarbeitet, um eine Neuinterpretation der Dateierweiterung zu vermeiden. Wenn ein Dokument auf eine der unten aufgeführten Programmiersprachen verweist, wird empfohlen, dass Clients diese IDs verwenden.
| Sprache | Bezeichner |
|---|---|
| ABAP | abap |
| Windows Bat | bat |
| BibTeX | bibtex |
| Clojure | clojure |
| Coffeescript | coffeescript |
| C | c |
| C++ | cpp |
| C# | csharp |
| CSS | css |
| Diff | diff |
| Dart | dart |
| Dockerfile | dockerfile |
| Elixir | elixir |
| Erlang | erlang |
| F# | fsharp |
| Git |
git-commit und git-rebase |
| Go | go |
| Groovy | groovy |
| Handlebars | handlebars |
| HTML | html |
| Ini | ini |
| Java | java |
| JavaScript | javascript |
| JavaScript React | javascriptreact |
| JSON | json |
| LaTeX | latex |
| Less | less |
| Lua | lua |
| Makefile | makefile |
| Markdown | markdown |
| Objective-C | objective-c |
| Objective-C++ | objective-cpp |
| Perl | perl |
| Perl 6 | perl6 |
| PHP | php |
| Powershell | powershell |
| Pug | jade |
| Python | python |
| R | r |
| Razor (cshtml) | razor |
| Ruby | ruby |
| Rust | rust |
| SCSS |
scss (Syntax mit geschweiften Klammern), sass (eingezogene Syntax) |
| Scala | scala |
| ShaderLab | shaderlab |
| Shell Script (Bash) | shellscript |
| SQL | sql |
| Swift | swift |
| TypeScript | typescript |
| TypeScript React | typescriptreact |
| TeX | tex |
| Visual Basic | vb |
| XML | xml |
| XSL | xsl |
| YAML | yaml |
TextDocumentIdentifier
Textdokumente werden über eine URI identifiziert. Auf Protokollebene werden URIs als Zeichenketten übergeben. Die entsprechende JSON-Struktur sieht wie folgt aus
interface TextDocumentIdentifier {
/**
* The text document's URI.
*/
uri: DocumentUri;
}
VersionedTextDocumentIdentifier
Eine Kennung zur Bezeichnung einer bestimmten Version eines Textdokuments. Diese Information fließt normalerweise vom Client zum Server.
interface VersionedTextDocumentIdentifier extends TextDocumentIdentifier {
/**
* The version number of this document.
*
* The version number of a document will increase after each change,
* including undo/redo. The number doesn't need to be consecutive.
*/
version: integer;
}
Eine Kennung, die optional eine bestimmte Version eines Textdokuments bezeichnet. Diese Information fließt normalerweise vom Server zum Client.
interface OptionalVersionedTextDocumentIdentifier extends TextDocumentIdentifier {
/**
* The version number of this document. If an optional versioned text document
* identifier is sent from the server to the client and the file is not
* open in the editor (the server has not received an open notification
* before) the server can send `null` to indicate that the version is
* known and the content on disk is the master (as specified with document
* content ownership).
*
* The version number of a document will increase after each change,
* including undo/redo. The number doesn't need to be consecutive.
*/
version: integer | null;
}
TextDocumentPositionParams
War in Version 1.0 TextDocumentPosition mit inline-Parametern.
Ein Parameterliteral, das in Anfragen verwendet wird, um ein Textdokument und eine Position innerhalb dieses Dokuments zu übergeben. Es liegt am Client zu entscheiden, wie eine Auswahl in eine Position umgewandelt wird, wenn eine Anfrage für ein Textdokument ausgegeben wird. Der Client kann beispielsweise die Auswahlrichtung berücksichtigen oder ignorieren, um LSP-Anfragen mit intern implementierten Funktionen konsistent zu machen.
interface TextDocumentPositionParams {
/**
* The text document.
*/
textDocument: TextDocumentIdentifier;
/**
* The position inside the text document.
*/
position: Position;
}
DocumentFilter
Ein Dokumentfilter bezeichnet ein Dokument anhand von Eigenschaften wie language, scheme oder pattern. Ein Beispiel ist ein Filter, der für TypeScript-Dateien auf der Festplatte gilt. Ein weiteres Beispiel ist ein Filter, der für JSON-Dateien mit dem Namen package.json gilt.
{ language: 'typescript', scheme: 'file' }
{ language: 'json', pattern: '**/package.json' }
export interface DocumentFilter {
/**
* A language id, like `typescript`.
*/
language?: string;
/**
* A Uri scheme, like `file` or `untitled`.
*/
scheme?: string;
/**
* A glob pattern, like `*.{ts,js}`.
*
* Glob patterns can have the following syntax:
* - `*` to match zero 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`)
*/
pattern?: string;
}
Bitte beachten Sie, dass für einen Dokumentenfilter mindestens eine der Eigenschaften language, scheme oder pattern gesetzt sein muss, um gültig zu sein. Um die Typdefinition einfach zu halten, sind alle Eigenschaften als optional markiert.
Ein Dokumentselektor ist die Kombination aus einem oder mehreren Dokumentfiltern.
export type DocumentSelector = DocumentFilter[];
TextEdit & AnnotatedTextEdit
Neu in Version 3.16: Unterstützung für
AnnotatedTextEdit.
Eine Textbearbeitung, die auf ein Textdokument angewendet werden kann.
interface TextEdit {
/**
* The range of the text document to be manipulated. To insert
* text into a document create a range where start === end.
*/
range: Range;
/**
* The string to be inserted. For delete operations use an
* empty string.
*/
newText: string;
}
Seit 3.16.0 gibt es auch das Konzept eines annotierten Textedits, das die Möglichkeit unterstützt, einem Textedit eine Anmerkung hinzuzufügen. Die Anmerkung kann Informationen hinzufügen, die die Änderung am Textedit beschreiben.
/**
* Additional information that describes document changes.
*
* @since 3.16.0
*/
export interface ChangeAnnotation {
/**
* A human-readable string describing the actual change. The string
* is rendered prominent in the user interface.
*/
label: string;
/**
* A flag which indicates that user confirmation is needed
* before applying the change.
*/
needsConfirmation?: boolean;
/**
* A human-readable string which is rendered less prominent in
* the user interface.
*/
description?: string;
}
Normalerweise bieten Clients Optionen zum Gruppieren von Änderungen entlang der Anmerkungen, mit denen sie verknüpft sind. Um dies im Protokoll zu unterstützen, bezieht sich eine Bearbeitungs- oder Ressourcenoperation unter Verwendung einer Kennung auf eine Änderungsanmerkung und nicht auf das Änderungsanmerkungs-Literal selbst. Dies ermöglicht es Servern, die identische Anmerkung für mehrere Bearbeitungen oder Ressourcenoperationen zu verwenden, was es Clients ermöglicht, die Operationen unter dieser Änderungsanmerkung zu gruppieren. Die tatsächlichen Änderungsanmerkungen werden zusammen mit ihren Kennungen über die neue Eigenschaft changeAnnotations vom WorkspaceEdit verwaltet.
/**
* An identifier referring to a change annotation managed by a workspace
* edit.
*
* @since 3.16.0.
*/
export type ChangeAnnotationIdentifier = string;
/**
* A special text edit with an additional change annotation.
*
* @since 3.16.0.
*/
export interface AnnotatedTextEdit extends TextEdit {
/**
* The actual annotation identifier.
*/
annotationId: ChangeAnnotationIdentifier;
}
TextEdit[]
Komplexe Textmanipulationen werden mit einem Array von TextEdits oder AnnotatedTextEdits beschrieben, die eine einzelne Änderung am Dokument darstellen.
Alle TextEdit-Bereiche beziehen sich auf Positionen im Dokument, auf dem sie berechnet werden. Sie bewegen ein Dokument also von Zustand S1 nach S2, ohne einen Zwischenzustand zu beschreiben. TextEdit-Bereiche dürfen sich niemals überlappen, d. h. kein Teil des ursprünglichen Dokuments darf von mehr als einem Edit bearbeitet werden. Es ist jedoch möglich, dass mehrere Edits dieselbe Startposition haben: mehrere Einfügungen oder beliebig viele Einfügungen gefolgt von einer einzigen Lösch- oder Ersetzungsbearbeitung. Wenn mehrere Einfügungen dieselbe Position haben, definiert die Reihenfolge im Array die Reihenfolge, in der die eingefügten Zeichenketten im resultierenden Text erscheinen.
TextDocumentEdit
Neu in Version 3.16: Unterstützung für
AnnotatedTextEdit. Die Unterstützung wird durch die Client-Capabilityworkspace.workspaceEdit.changeAnnotationSupportgesteuert. Wenn ein Client die Capability nicht signalisiert, sollten Server keineAnnotatedTextEdit-Literale an den Client zurücksenden.
Beschreibt textuelle Änderungen an einem einzelnen Textdokument. Das Textdokument wird als OptionalVersionedTextDocumentIdentifier bezeichnet, damit Clients die Version des Textdokuments überprüfen können, bevor eine Bearbeitung angewendet wird. Ein TextDocumentEdit beschreibt alle Änderungen an einer Version Si und verschiebt das Dokument nach der Anwendung auf Version Si+1. Daher muss der Ersteller eines TextDocumentEdit das Array von Bearbeitungen nicht sortieren oder irgendeine Art von Reihenfolge vornehmen. Die Bearbeitungen müssen jedoch nicht überlappend sein.
export interface TextDocumentEdit {
/**
* The text document to change.
*/
textDocument: OptionalVersionedTextDocumentIdentifier;
/**
* The edits to be applied.
*
* @since 3.16.0 - support for AnnotatedTextEdit. This is guarded by the
* client capability `workspace.workspaceEdit.changeAnnotationSupport`
*/
edits: (TextEdit | AnnotatedTextEdit)[];
}
Location
Repräsentiert einen Ort innerhalb einer Ressource, z. B. eine Zeile in einer Textdatei.
interface Location {
uri: DocumentUri;
range: Range;
}
LocationLink
Repräsentiert einen Link zwischen einer Quell- und einer Zielposition.
interface LocationLink {
/**
* Span of the origin of this link.
*
* Used as the underlined span for mouse interaction. Defaults to the word
* range at the mouse position.
*/
originSelectionRange?: Range;
/**
* The target resource identifier of this link.
*/
targetUri: DocumentUri;
/**
* The full target range of this link. If the target for example is a symbol
* then target range is the range enclosing this symbol not including
* leading/trailing whitespace but everything else like comments. This
* information is typically used to highlight the range in the editor.
*/
targetRange: Range;
/**
* The range that should be selected and revealed when this link is being
* followed, e.g the name of a function. Must be contained by the
* `targetRange`. See also `DocumentSymbol#range`
*/
targetSelectionRange: Range;
}
Diagnostic
Repräsentiert eine Diagnose, wie z. B. einen Compilerfehler oder eine Warnung. Diagnoseobjekte sind nur im Gültigkeitsbereich einer Ressource gültig.
export interface Diagnostic {
/**
* The range at which the message applies.
*/
range: Range;
/**
* The diagnostic's severity. To avoid interpretation mismatches when a
* server is used with different clients it is highly recommended that
* servers always provide a severity value. If omitted, it’s recommended
* for the client to interpret it as an Error severity.
*/
severity?: DiagnosticSeverity;
/**
* The diagnostic's code, which might appear in the user interface.
*/
code?: integer | string;
/**
* An optional property to describe the error code.
*
* @since 3.16.0
*/
codeDescription?: CodeDescription;
/**
* A human-readable string describing the source of this
* diagnostic, e.g. 'typescript' or 'super lint'.
*/
source?: string;
/**
* The diagnostic's message.
*/
message: string;
/**
* Additional metadata about the diagnostic.
*
* @since 3.15.0
*/
tags?: DiagnosticTag[];
/**
* An array of related diagnostic information, e.g. when symbol-names within
* a scope collide all definitions can be marked via this property.
*/
relatedInformation?: DiagnosticRelatedInformation[];
/**
* A data entry field that is preserved between a
* `textDocument/publishDiagnostics` notification and
* `textDocument/codeAction` request.
*
* @since 3.16.0
*/
data?: LSPAny;
}
Das Protokoll unterstützt derzeit die folgenden Diagnose-Schweregrade und Tags
export namespace DiagnosticSeverity {
/**
* Reports an error.
*/
export const Error: 1 = 1;
/**
* Reports a warning.
*/
export const Warning: 2 = 2;
/**
* Reports an information.
*/
export const Information: 3 = 3;
/**
* Reports a hint.
*/
export const Hint: 4 = 4;
}
export type DiagnosticSeverity = 1 | 2 | 3 | 4;
/**
* The diagnostic tags.
*
* @since 3.15.0
*/
export namespace DiagnosticTag {
/**
* Unused or unnecessary code.
*
* Clients are allowed to render diagnostics with this tag faded out
* instead of having an error squiggle.
*/
export const Unnecessary: 1 = 1;
/**
* Deprecated or obsolete code.
*
* Clients are allowed to rendered diagnostics with this tag strike through.
*/
export const Deprecated: 2 = 2;
}
export type DiagnosticTag = 1 | 2;
DiagnosticRelatedInformation ist wie folgt definiert
/**
* Represents a related message and source code location for a diagnostic.
* This should be used to point to code locations that cause or are related to
* a diagnostics, e.g when duplicating a symbol in a scope.
*/
export interface DiagnosticRelatedInformation {
/**
* The location of this related diagnostic information.
*/
location: Location;
/**
* The message of this related diagnostic information.
*/
message: string;
}
CodeDescription ist wie folgt definiert
/**
* Structure to capture a description for an error code.
*
* @since 3.16.0
*/
export interface CodeDescription {
/**
* An URI to open with more information about the diagnostic error.
*/
href: URI;
}
Befehl
Repräsentiert einen Verweis auf einen Befehl. Bietet einen Titel, der zur Darstellung eines Befehls in der Benutzeroberfläche verwendet wird. Befehle werden durch eine Zeichenkettenkennung identifiziert. Der empfohlene Weg zur Handhabung von Befehlen ist die Implementierung ihrer Ausführung auf der Serverseite, wenn der Client und der Server die entsprechenden Capabilities bereitstellen. Alternativ könnte der Tool-Erweiterungscode den Befehl behandeln. Das Protokoll spezifiziert derzeit keine bekannten Befehle.
interface Command {
/**
* Title of the command, like `save`.
*/
title: string;
/**
* The identifier of the actual command handler.
*/
command: string;
/**
* Arguments that the command handler should be
* invoked with.
*/
arguments?: LSPAny[];
}
MarkupContent
Ein MarkupContent-Literal repräsentiert einen Zeichenkettenwert, dessen Inhalt in verschiedenen Formaten dargestellt werden kann. Derzeit werden die Formate plaintext und markdown unterstützt. MarkupContent wird normalerweise in den Dokumentationseigenschaften von Ergebnis-Literalen wie CompletionItem oder SignatureInformation verwendet. Wenn das Format markdown ist, sollte der Inhalt der GitHub Flavored Markdown Specification folgen.
/**
* Describes the content type that a client supports in various
* result literals like `Hover`, `ParameterInfo` or `CompletionItem`.
*
* Please note that `MarkupKinds` must not start with a `$`. This kinds
* are reserved for internal usage.
*/
export namespace MarkupKind {
/**
* Plain text is supported as a content format
*/
export const PlainText: 'plaintext' = 'plaintext';
/**
* Markdown is supported as a content format
*/
export const Markdown: 'markdown' = 'markdown';
}
export type MarkupKind = 'plaintext' | 'markdown';
/**
* A `MarkupContent` literal represents a string value which content is
* interpreted base on its kind flag. Currently the protocol supports
* `plaintext` and `markdown` as markup kinds.
*
* If the kind is `markdown` then the value can contain fenced code blocks like
* in GitHub issues.
*
* Here is an example how such a string can be constructed using
* JavaScript / TypeScript:
* ```typescript
* let markdown: MarkdownContent = {
* kind: MarkupKind.Markdown,
* value: [
* '# Header',
* 'Some text',
* '```typescript',
* 'someCode();',
* '```'
* ].join('\n')
* };
* ```
*
* *Please Note* that clients might sanitize the return markdown. A client could
* decide to remove HTML from the markdown to avoid script execution.
*/
export interface MarkupContent {
/**
* The type of the Markup
*/
kind: MarkupKind;
/**
* The content itself
*/
value: string;
}
Zusätzlich sollten Clients den Markdown-Parser signalisieren, den sie verwenden, über die Client-Capability general.markdown, die in Version 3.16.0 eingeführt wurde und wie folgt definiert ist:
/**
* Client capabilities specific to the used markdown parser.
*
* @since 3.16.0
*/
export interface MarkdownClientCapabilities {
/**
* The name of the parser.
*/
parser: string;
/**
* The version of the parser.
*/
version?: string;
/**
* A list of HTML tags that the client allows / supports in
* Markdown.
*
* @since 3.17.0
*/
allowedTags?: string[];
}
Bekannte Markdown-Parser, die von Clients derzeit verwendet werden, sind
| Parser | Version | Dokumentation |
|---|---|---|
| marked | 1.1.0 | Marked Documentation |
| Python-Markdown | 3.2.2 | Python-Markdown Dokumentation |
File Resource changes
Neu in Version 3.13. Seit Version 3.16 können Datei-Ressourcenänderungen eine zusätzliche Eigenschaft
changeAnnotationtragen, um die tatsächliche Änderung detaillierter zu beschreiben. Ob ein Client Unterstützung für Änderungsannotationen hat, wird durch die Client-Capabilityworkspace.workspaceEdit.changeAnnotationSupportgesteuert.
Datei-Ressourcenänderungen erlauben es Servern, Dateien und Ordner über den Client zu erstellen, umzubenennen und zu löschen. Beachten Sie, dass die Namen sich auf Dateien beziehen, die Operationen jedoch auf Dateien und Ordner angewendet werden sollen. Dies entspricht der Namensgebung in anderen Teilen des Language Server Protocols (siehe File Watcher, die Dateien und Ordner beobachten können). Die entsprechenden Änderungs-Literale sehen wie folgt aus
/**
* Options to create a file.
*/
export interface CreateFileOptions {
/**
* Overwrite existing file. Overwrite wins over `ignoreIfExists`
*/
overwrite?: boolean;
/**
* Ignore if exists.
*/
ignoreIfExists?: boolean;
}
/**
* Create file operation
*/
export interface CreateFile {
/**
* A create
*/
kind: 'create';
/**
* The resource to create.
*/
uri: DocumentUri;
/**
* Additional options
*/
options?: CreateFileOptions;
/**
* An optional annotation identifier describing the operation.
*
* @since 3.16.0
*/
annotationId?: ChangeAnnotationIdentifier;
}
/**
* Rename file options
*/
export interface RenameFileOptions {
/**
* Overwrite target if existing. Overwrite wins over `ignoreIfExists`
*/
overwrite?: boolean;
/**
* Ignores if target exists.
*/
ignoreIfExists?: boolean;
}
/**
* Rename file operation
*/
export interface RenameFile {
/**
* A rename
*/
kind: 'rename';
/**
* The old (existing) location.
*/
oldUri: DocumentUri;
/**
* The new location.
*/
newUri: DocumentUri;
/**
* Rename options.
*/
options?: RenameFileOptions;
/**
* An optional annotation identifier describing the operation.
*
* @since 3.16.0
*/
annotationId?: ChangeAnnotationIdentifier;
}
/**
* Delete file options
*/
export interface DeleteFileOptions {
/**
* Delete the content recursively if a folder is denoted.
*/
recursive?: boolean;
/**
* Ignore the operation if the file doesn't exist.
*/
ignoreIfNotExists?: boolean;
}
/**
* Delete file operation
*/
export interface DeleteFile {
/**
* A delete
*/
kind: 'delete';
/**
* The file to delete.
*/
uri: DocumentUri;
/**
* Delete options.
*/
options?: DeleteFileOptions;
/**
* An optional annotation identifier describing the operation.
*
* @since 3.16.0
*/
annotationId?: ChangeAnnotationIdentifier;
}
WorkspaceEdit
Eine Workspace-Bearbeitung repräsentiert Änderungen an vielen Ressourcen, die im Workspace verwaltet werden. Die Bearbeitung sollte entweder changes oder documentChanges bereitstellen. Wenn der Client versionierte Dokumentbearbeitungen verarbeiten kann und documentChanges vorhanden sind, werden letztere gegenüber changes bevorzugt.
Seit Version 3.13.0 kann ein WorkspaceEdit auch Ressourcenoperationen (Erstellen, Löschen oder Umbenennen von Dateien und Ordnern) enthalten. Wenn Ressourcenoperationen vorhanden sind, müssen Clients die Operationen in der Reihenfolge ausführen, in der sie angegeben sind. Ein WorkspaceEdit kann beispielsweise aus den folgenden beiden Änderungen bestehen: (1) Erstellen der Datei a.txt und (2) eine Textdokumentbearbeitung, die Text in die Datei a.txt einfügt. Eine ungültige Reihenfolge (z. B. (1) Löschen der Datei a.txt und (2) Einfügen von Text in die Datei a.txt) führt zum Fehlschlag der Operation. Wie der Client mit dem Fehlschlag umgeht, wird durch die Client-Capability workspace.workspaceEdit.failureHandling beschrieben.
export interface WorkspaceEdit {
/**
* Holds changes to existing resources.
*/
changes?: { [uri: DocumentUri]: TextEdit[]; };
/**
* Depending on the client capability
* `workspace.workspaceEdit.resourceOperations` document changes are either
* an array of `TextDocumentEdit`s to express changes to n different text
* documents where each text document edit addresses a specific version of
* a text document. Or it can contain above `TextDocumentEdit`s mixed with
* create, rename and delete file / folder operations.
*
* Whether a client supports versioned document edits is expressed via
* `workspace.workspaceEdit.documentChanges` client capability.
*
* If a client neither supports `documentChanges` nor
* `workspace.workspaceEdit.resourceOperations` then only plain `TextEdit`s
* using the `changes` property are supported.
*/
documentChanges?: (
TextDocumentEdit[] |
(TextDocumentEdit | CreateFile | RenameFile | DeleteFile)[]
);
/**
* A map of change annotations that can be referenced in
* `AnnotatedTextEdit`s or create, rename and delete file / folder
* operations.
*
* Whether clients honor this property depends on the client capability
* `workspace.changeAnnotationSupport`.
*
* @since 3.16.0
*/
changeAnnotations?: {
[id: string /* ChangeAnnotationIdentifier */]: ChangeAnnotation;
};
}
WorkspaceEditClientCapabilities
Neu in Version 3.13:
ResourceOperationKindundFailureHandlingKindsowie die Client-Capabilityworkspace.workspaceEdit.resourceOperationssowieworkspace.workspaceEdit.failureHandling.
Die Fähigkeiten eines Arbeitsbereich-Bearbeitungsereignisses haben sich im Laufe der Zeit entwickelt. Clients können ihre Unterstützung mit der folgenden Client-Fähigkeit beschreiben
Client Capability:
- Eigenschaftspfad (optional):
workspace.workspaceEdit - Eigenschaftstyp:
WorkspaceEditClientCapabilities, wie folgt definiert
export interface WorkspaceEditClientCapabilities {
/**
* The client supports versioned document changes in `WorkspaceEdit`s
*/
documentChanges?: boolean;
/**
* The resource operations the client supports. Clients should at least
* support 'create', 'rename' and 'delete' files and folders.
*
* @since 3.13.0
*/
resourceOperations?: ResourceOperationKind[];
/**
* The failure handling strategy of a client if applying the workspace edit
* fails.
*
* @since 3.13.0
*/
failureHandling?: FailureHandlingKind;
/**
* Whether the client normalizes line endings to the client specific
* setting.
* If set to `true` the client will normalize line ending characters
* in a workspace edit to the client specific new line character(s).
*
* @since 3.16.0
*/
normalizesLineEndings?: boolean;
/**
* Whether the client in general supports change annotations on text edits,
* create file, rename file and delete file changes.
*
* @since 3.16.0
*/
changeAnnotationSupport?: {
/**
* Whether the client groups edits with equal labels into tree nodes,
* for instance all edits labelled with "Changes in Strings" would
* be a tree node.
*/
groupsOnLabel?: boolean;
};
}
/**
* The kind of resource operations supported by the client.
*/
export type ResourceOperationKind = 'create' | 'rename' | 'delete';
export namespace ResourceOperationKind {
/**
* Supports creating new files and folders.
*/
export const Create: ResourceOperationKind = 'create';
/**
* Supports renaming existing files and folders.
*/
export const Rename: ResourceOperationKind = 'rename';
/**
* Supports deleting existing files and folders.
*/
export const Delete: ResourceOperationKind = 'delete';
}
export type FailureHandlingKind = 'abort' | 'transactional' | 'undo'
| 'textOnlyTransactional';
export namespace FailureHandlingKind {
/**
* Applying the workspace change is simply aborted if one of the changes
* provided fails. All operations executed before the failing operation
* stay executed.
*/
export const Abort: FailureHandlingKind = 'abort';
/**
* All operations are executed transactional. That means they either all
* succeed or no changes at all are applied to the workspace.
*/
export const Transactional: FailureHandlingKind = 'transactional';
/**
* If the workspace edit contains only textual file changes they are
* executed transactional. If resource changes (create, rename or delete
* file) are part of the change the failure handling strategy is abort.
*/
export const TextOnlyTransactional: FailureHandlingKind
= 'textOnlyTransactional';
/**
* The client tries to undo the operations already executed. But there is no
* guarantee that this is succeeding.
*/
export const Undo: FailureHandlingKind = 'undo';
}
Work Done Progress
Seit Version 3.15.0
Work Done Progress wird über die generische Benachrichtigung $/progress gemeldet. Der Wert-Payload einer Work Done Progress-Benachrichtigung kann drei verschiedene Formen haben.
Work Done Progress Begin
Um die Fortschrittsmeldung zu starten, muss eine $/progress-Benachrichtigung mit dem folgenden Payload gesendet werden
export interface WorkDoneProgressBegin {
kind: 'begin';
/**
* Mandatory title of the progress operation. Used to briefly inform about
* the kind of operation being performed.
*
* Examples: "Indexing" or "Linking dependencies".
*/
title: string;
/**
* Controls if a cancel button should show to allow the user to cancel the
* long running operation. Clients that don't support cancellation are
* allowed to ignore the setting.
*/
cancellable?: boolean;
/**
* Optional, more detailed associated progress message. Contains
* complementary information to the `title`.
*
* Examples: "3/25 files", "project/src/module2", "node_modules/some_dep".
* If unset, the previous progress message (if any) is still valid.
*/
message?: string;
/**
* Optional progress percentage to display (value 100 is considered 100%).
* If not provided infinite progress is assumed and clients are allowed
* to ignore the `percentage` value in subsequent report notifications.
*
* The value should be steadily rising. Clients are free to ignore values
* that are not following this rule. The value range is [0, 100].
*/
percentage?: uinteger;
}
Work Done Progress Report
Die Fortschrittsmeldung erfolgt über den folgenden Payload
export interface WorkDoneProgressReport {
kind: 'report';
/**
* Controls enablement state of a cancel button. This property is only valid
* if a cancel button got requested in the `WorkDoneProgressBegin` payload.
*
* Clients that don't support cancellation or don't support control the
* button's enablement state are allowed to ignore the setting.
*/
cancellable?: boolean;
/**
* Optional, more detailed associated progress message. Contains
* complementary information to the `title`.
*
* Examples: "3/25 files", "project/src/module2", "node_modules/some_dep".
* If unset, the previous progress message (if any) is still valid.
*/
message?: string;
/**
* Optional progress percentage to display (value 100 is considered 100%).
* If not provided infinite progress is assumed and clients are allowed
* to ignore the `percentage` value in subsequent report notifications.
*
* The value should be steadily rising. Clients are free to ignore values
* that are not following this rule. The value range is [0, 100].
*/
percentage?: uinteger;
}
Work Done Progress End
Das Ende der Fortschrittsmeldung wird über den folgenden Payload signalisiert
export interface WorkDoneProgressEnd {
kind: 'end';
/**
* Optional, a final message indicating to for example indicate the outcome
* of the operation.
*/
message?: string;
}
Initiierung von Work Done Progress
Work Done Progress kann auf zwei verschiedene Arten initiiert werden
- durch den Absender einer Anfrage (meist Clients) über die vordefinierte
workDoneToken-Eigenschaft im Parameter-Literal der Anfrage. Das Dokument wird diese Art von Fortschritt als vom Client initiierte Fortschrittsmeldung bezeichnen. - durch einen Server über die Anfrage
window/workDoneProgress/create. Das Dokument wird diese Art von Fortschritt als vom Server initiierte Fortschrittsmeldung bezeichnen.
Vom Client initiierter Fortschritt
Betrachten Sie einen Client, der eine textDocument/reference-Anfrage an einen Server sendet und der Client die Meldung von Work Done Progress für diese Anfrage akzeptiert. Um dies dem Server zu signalisieren, würde der Client eine workDoneToken-Eigenschaft zu den Parameter des Referenz-Anfrage hinzufügen. Etwas wie dies
{
"textDocument": {
"uri": "file:///folder/file.ts"
},
"position": {
"line": 9,
"character": 5
},
"context": {
"includeDeclaration": true
},
// The token used to report work done progress.
"workDoneToken": "1d546990-40a3-4b77-b134-46622995f6ae"
}
Die entsprechende Typdefinition für die Parameter-Eigenschaft sieht wie folgt aus
export interface WorkDoneProgressParams {
/**
* An optional token that a server can use to report work done progress.
*/
workDoneToken?: ProgressToken;
}
Ein Server verwendet das workDoneToken, um Fortschritte für die spezifische textDocument/reference zu melden. Für die obige Anfrage sieht der $/progress-Benachrichtigungs-Payload wie folgt aus
{
"token": "1d546990-40a3-4b77-b134-46622995f6ae",
"value": {
"kind": "begin",
"title": "Finding references for A#foo",
"cancellable": false,
"message": "Processing file X.ts",
"percentage": 0
}
}
Der Token, der über die workDoneToken-Eigenschaft im Parameterliteral einer Anfrage empfangen wird, ist nur gültig, solange die Anfrage keine Antwort gesendet hat. Das Abbrechen von Arbeitsfortschritten erfolgt durch einfaches Abbrechen der entsprechenden Anfrage.
Es gibt keine spezifische Client-Capability, die signalisiert, ob ein Client ein Fortschrittstoken pro Anfrage sendet. Der Grund dafür ist, dass dies bei vielen Clients kein statischer Aspekt ist und sich sogar für jede Anfrageinstanz desselben Anfragetyps ändern kann. Daher wird die Capability bei jeder Anfrageinstanz durch das Vorhandensein einer workDoneToken-Eigenschaft signalisiert.
Um zu vermeiden, dass Clients eine Fortschrittsüberwachungs-Benutzeroberfläche einrichten, bevor sie eine Anfrage senden, der Server aber tatsächlich keinen Fortschritt meldet, muss ein Server die allgemeine Unterstützung für die Fortschrittsmeldung von Arbeit in den entsprechenden Serverfähigkeiten signalisieren. Für das obige Beispiel des Auffindens von Referenzen würde ein Server eine solche Unterstützung signalisieren, indem er die Eigenschaft referencesProvider in den Serverfähigkeiten wie folgt setzt
{
"referencesProvider": {
"workDoneProgress": true
}
}
Die entsprechende Typdefinition für die Serverfähigkeit sieht wie folgt aus
export interface WorkDoneProgressOptions {
workDoneProgress?: boolean;
}
Vom Server initiierter Fortschritt
Server können auch die Fortschrittsberichterstattung über die window/workDoneProgress/create-Anfrage initiieren. Dies ist nützlich, wenn der Server den Fortschritt außerhalb einer Anfrage melden muss (z. B. muss der Server eine Datenbank neu indizieren). Der Token kann dann verwendet werden, um den Fortschritt mit denselben Benachrichtigungen zu melden, die auch für clientinitiierte Fortschritte verwendet werden. Der in der Erstellungsanfrage bereitgestellte Token sollte nur einmal verwendet werden (z. B. sollte nur eine Start-, viele Berichts- und eine Endbenachrichtigung dafür gesendet werden).
Um das Protokoll abwärtskompatibel zu halten, dürfen Server die window/workDoneProgress/create-Anfrage nur verwenden, wenn der Client die entsprechende Unterstützung über die Clientfähigkeit window.workDoneProgress signalisiert, die wie folgt definiert ist
/**
* Window specific client capabilities.
*/
window?: {
/**
* Whether client supports server initiated progress using the
* `window/workDoneProgress/create` request.
*/
workDoneProgress?: boolean;
};
Teilergebnis-Fortschritt
Seit Version 3.15.0
Teilergebnisse werden ebenfalls über die allgemeine Benachrichtigung $/progress gemeldet. Die Werte-Nutzlast einer Teilergebnis-Fortschrittsbenachrichtigung ist in den meisten Fällen dieselbe wie das Endergebnis. Beispielsweise hat die workspace/symbol-Anfrage SymbolInformation[] | WorkspaceSymbol[] als Ergebnistyp. Teilergebnisse sind daher ebenfalls vom Typ SymbolInformation[] | WorkspaceSymbol[]. Ob ein Client Teilergebnisbenachrichtigungen für eine Anfrage akzeptiert, wird signalisiert, indem ein partialResultToken zu den Anfrageparametern hinzugefügt wird. Beispielsweise könnte eine textDocument/reference-Anfrage, die sowohl Arbeitsfortschritt als auch Teilergebnisfortschritt unterstützt, wie folgt aussehen:
{
"textDocument": {
"uri": "file:///folder/file.ts"
},
"position": {
"line": 9,
"character": 5
},
"context": {
"includeDeclaration": true
},
// The token used to report work done progress.
"workDoneToken": "1d546990-40a3-4b77-b134-46622995f6ae",
// The token used to report partial result progress.
"partialResultToken": "5f6f349e-4f81-4a3b-afff-ee04bff96804"
}
Der partialResultToken wird dann verwendet, um Teilergebnisse für die Suche nach Referenzen zu melden.
Wenn ein Server Teilergebnisse über eine entsprechende $/progress-Benachrichtigung meldet, muss das gesamte Ergebnis über n $/progress-Benachrichtigungen gemeldet werden. Jede der n $/progress-Benachrichtigungen fügt dem Ergebnis Elemente hinzu. Die endgültige Antwort muss in Bezug auf die Ergebniswerte leer sein. Dies vermeidet Verwirrung darüber, wie das Endergebnis interpretiert werden soll, z. B. als weiteres Teilergebnis oder als ersetzendes Ergebnis.
Wenn die Antwort fehlerhaft ist, sollten die bereitgestellten Teilergebnisse wie folgt behandelt werden
- Der
codeist gleichRequestCancelled: Der Client ist frei, die bereitgestellten Ergebnisse zu verwenden, sollte aber klarstellen, dass die Anfrage abgebrochen wurde und möglicherweise unvollständig ist. - In allen anderen Fällen sollten die bereitgestellten Teilergebnisse nicht verwendet werden.
PartialResultParams
Ein Parameter-Literal, das verwendet wird, um einen Teilergebnis-Token zu übergeben.
export interface PartialResultParams {
/**
* An optional token that a server can use to report partial results (e.g.
* streaming) to the client.
*/
partialResultToken?: ProgressToken;
}
TraceValue
Ein TraceValue repräsentiert die Ausführlichkeitsstufe, mit der der Server systematisch seine Ausführungstraces über $/logTrace-Benachrichtigungen meldet. Der anfängliche Trace-Wert wird vom Client bei der Initialisierung gesetzt und kann später über die $/setTrace-Benachrichtigung geändert werden.
export type TraceValue = 'off' | 'messages' | 'verbose';
Server-Lebenszyklus
Die aktuelle Protokollspezifikation besagt, dass der Lebenszyklus eines Servers vom Client verwaltet wird (z. B. ein Tool wie VS Code oder Emacs). Es liegt am Client zu entscheiden, wann ein Server gestartet (prozessual) und wann er heruntergefahren wird.
Initialize-Anfrage (
)
Die initialize-Anfrage wird als erste Anfrage vom Client an den Server gesendet. Wenn der Server vor der initialize-Anfrage eine Anfrage oder Benachrichtigung empfängt, sollte er wie folgt vorgehen
- Bei einer Anfrage sollte die Antwort ein Fehler mit
code: -32002sein. Die Nachricht kann vom Server gewählt werden. - Benachrichtigungen sollten verworfen werden, mit Ausnahme der exit-Benachrichtigung. Dies ermöglicht das Beenden eines Servers ohne eine initialize-Anfrage.
Bis der Server mit einem InitializeResult auf die initialize-Anfrage geantwortet hat, darf der Client keine zusätzlichen Anfragen oder Benachrichtigungen an den Server senden. Darüber hinaus darf der Server keine Anfragen oder Benachrichtigungen an den Client senden, bis er mit einem InitializeResult geantwortet hat, mit der Ausnahme, dass während der initialize-Anfrage der Server die Benachrichtigungen window/showMessage, window/logMessage und telemetry/event sowie die window/showMessageRequest-Anfrage an den Client senden darf. Falls der Client einen Fortschritts-Token in den initialize-Parametern setzt (z. B. workDoneToken-Eigenschaft), darf der Server diesen Token (und nur diesen) auch über die $/progress-Benachrichtigung vom Server zum Client verwenden.
Die initialize-Anfrage darf nur einmal gesendet werden.
Anfrage:
- method: ‘initialize’
- params:
InitializeParams, wie folgt definiert
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;
}
Dabei sind ClientCapabilities und TextDocumentClientCapabilities wie folgt definiert
TextDocumentClientCapabilities
TextDocumentClientCapabilities definieren die Fähigkeiten, die der Editor/das Tool für Textdokumente bietet.
/**
* 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;
/**
* Capabilities specific to the various type hierarchy requests.
*
* @since 3.17.0
*/
typeHierarchy?: TypeHierarchyClientCapabilities;
/**
* Capabilities specific to the `textDocument/inlineValue` request.
*
* @since 3.17.0
*/
inlineValue?: InlineValueClientCapabilities;
/**
* Capabilities specific to the `textDocument/inlayHint` request.
*
* @since 3.17.0
*/
inlayHint?: InlayHintClientCapabilities;
/**
* Capabilities specific to the diagnostic pull model.
*
* @since 3.17.0
*/
diagnostic?: DiagnosticClientCapabilities;
}
NotebookDocumentClientCapabilities
NotebookDocumentClientCapabilities definieren die Capabilities, die der Editor/das Tool für Notebook-Dokumente bereitstellt.
/**
* Capabilities specific to the notebook document support.
*
* @since 3.17.0
*/
export interface NotebookDocumentClientCapabilities {
/**
* Capabilities specific to notebook document synchronization
*
* @since 3.17.0
*/
synchronization: NotebookDocumentSyncClientCapabilities;
}
ClientCapabilities definieren die Fähigkeiten für dynamische Registrierung, Workspace- und Textdokument-Features, die der Client unterstützt. Das experimental kann verwendet werden, um experimentelle, in Entwicklung befindliche Fähigkeiten zu übergeben. Für zukünftige Kompatibilität kann ein ClientCapabilities-Objektliteral mehr Eigenschaften aufweisen als derzeit definiert. Server, die ein ClientCapabilities-Objektliteral mit unbekannten Eigenschaften erhalten, sollten diese Eigenschaften ignorieren. Eine fehlende Eigenschaft sollte als Abwesenheit der Fähigkeit interpretiert werden. Wenn eine fehlende Eigenschaft normalerweise Untereigenschaften definiert, sollten alle fehlenden Untereigenschaften als Abwesenheit der entsprechenden Fähigkeit interpretiert werden.
Client-Fähigkeiten wurden mit Version 3.0 des Protokolls eingeführt. Sie beschreiben daher nur Fähigkeiten, die in 3.x oder später eingeführt wurden. Fähigkeiten, die bereits in Version 2.x des Protokolls vorhanden waren, sind für Clients weiterhin obligatorisch. Clients können sich nicht von der Bereitstellung dieser Fähigkeiten abmelden. Selbst wenn ein Client ClientCapabilities.textDocument.synchronization weglässt, ist der Client immer noch verpflichtet, Textsynchronisierungsfunktionen (z. B. open-, changed- und close-Benachrichtigungen) bereitzustellen.
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;
};
/**
* Client workspace capabilities specific to inline values.
*
* @since 3.17.0
*/
inlineValue?: InlineValueWorkspaceClientCapabilities;
/**
* Client workspace capabilities specific to inlay hints.
*
* @since 3.17.0
*/
inlayHint?: InlayHintWorkspaceClientCapabilities;
/**
* Client workspace capabilities specific to diagnostics.
*
* @since 3.17.0.
*/
diagnostics?: DiagnosticWorkspaceClientCapabilities;
};
/**
* Text document specific client capabilities.
*/
textDocument?: TextDocumentClientCapabilities;
/**
* Capabilities specific to the notebook document support.
*
* @since 3.17.0
*/
notebookDocument?: NotebookDocumentClientCapabilities;
/**
* Window specific client capabilities.
*/
window?: {
/**
* It indicates whether the client supports server initiated
* progress using the `window/workDoneProgress/create` request.
*
* The capability also controls Whether client supports handling
* of progress notifications. If set servers are allowed to report a
* `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;
/**
* The position encodings supported by the client. Client and server
* have to agree on the same position encoding to ensure that offsets
* (e.g. character position in a line) are interpreted the same on both
* side.
*
* To keep the protocol backwards compatible the following applies: if
* the value 'utf-16' is missing from the array of position encodings
* servers can assume that the client supports UTF-16. UTF-16 is
* therefore a mandatory encoding.
*
* If omitted it defaults to ['utf-16'].
*
* Implementation considerations: since the conversion from one encoding
* into another requires the content of the file / line the conversion
* is best done where the file is read which is usually on the server
* side.
*
* @since 3.17.0
*/
positionEncodings?: PositionEncodingKind[];
};
/**
* Experimental client capabilities.
*/
experimental?: LSPAny;
}
Antwort:
- result:
InitializeResult, wie folgt definiert
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
/**
* Known error codes for an `InitializeErrorCodes`;
*/
export namespace InitializeErrorCodes {
/**
* 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;
}
export type InitializeErrorCodes = 1;
- error.data
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;
}
Der Server kann folgende Fähigkeiten signalisieren
interface ServerCapabilities {
/**
* The position encoding the server picked from the encodings offered
* by the client via the client capability `general.positionEncodings`.
*
* If the client didn't provide any position encodings the only valid
* value that a server can return is 'utf-16'.
*
* If omitted it defaults to 'utf-16'.
*
* @since 3.17.0
*/
positionEncoding?: PositionEncodingKind;
/**
* 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;
/**
* Defines how notebook documents are synced.
*
* @since 3.17.0
*/
notebookDocumentSync?: NotebookDocumentSyncOptions
| NotebookDocumentSyncRegistrationOptions;
/**
* 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 type hierarchy support.
*
* @since 3.17.0
*/
typeHierarchyProvider?: boolean | TypeHierarchyOptions
| TypeHierarchyRegistrationOptions;
/**
* The server provides inline values.
*
* @since 3.17.0
*/
inlineValueProvider?: boolean | InlineValueOptions
| InlineValueRegistrationOptions;
/**
* The server provides inlay hints.
*
* @since 3.17.0
*/
inlayHintProvider?: boolean | InlayHintOptions
| InlayHintRegistrationOptions;
/**
* The server has support for pull model diagnostics.
*
* @since 3.17.0
*/
diagnosticProvider?: DiagnosticOptions | DiagnosticRegistrationOptions;
/**
* 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-Benachrichtigung ()
Die initialized-Benachrichtigung wird vom Client an den Server gesendet, nachdem der Client das Ergebnis der initialize-Anfrage erhalten hat, aber bevor der Client andere Anfragen oder Benachrichtigungen an den Server sendet. Der Server kann die initialized-Benachrichtigung beispielsweise verwenden, um Capabilities dynamisch zu registrieren. Die initialized-Benachrichtigung darf nur einmal gesendet werden.
Benachrichtigung:
- method: ‘initialized’
- params:
InitializedParams, wie folgt definiert
interface InitializedParams {
}
Capability registrieren (
)
Die client/registerCapability-Anfrage wird vom Server an den Client gesendet, um eine neue Fähigkeit auf der Clientseite zu registrieren. Nicht alle Clients müssen die dynamische Fähigkeitsregistrierung unterstützen. Ein Client wählt über die dynamicRegistration-Eigenschaft bei den spezifischen Client-Fähigkeiten eine Option. Ein Client kann sogar eine dynamische Registrierung für Fähigkeit A, aber nicht für Fähigkeit B bereitstellen (siehe TextDocumentClientCapabilities als Beispiel).
Server dürfen dieselbe Fähigkeit nicht sowohl statisch über das initialize-Ergebnis als auch dynamisch für denselben Dokumentselektor registrieren. Wenn ein Server sowohl statische als auch dynamische Registrierung unterstützen möchte, muss er die Client-Fähigkeit in der initialize-Anfrage prüfen und die Fähigkeit nur statisch registrieren, wenn der Client keine dynamische Registrierung für diese Fähigkeit unterstützt.
Anfrage:
- method: ‘client/registerCapability’
- params:
RegistrationParams
Dabei ist RegistrationParams wie folgt definiert
/**
* 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;
}
export interface RegistrationParams {
registrations: Registration[];
}
Da die meisten Registrierungsoptionen die Angabe eines Dokumentselektors erfordern, gibt es eine Basis-Schnittstelle, die verwendet werden kann. Siehe TextDocumentRegistrationOptions.
Das folgende Beispiel zeigt eine JSON-RPC-Nachricht zur dynamischen Registrierung für die textDocument/willSaveWaitUntil-Funktion auf der Clientseite (nur Details angezeigt):
{
"method": "client/registerCapability",
"params": {
"registrations": [
{
"id": "79eee87c-c409-4664-8102-e03263673f6f",
"method": "textDocument/willSaveWaitUntil",
"registerOptions": {
"documentSelector": [
{ "language": "javascript" }
]
}
}
]
}
}
Diese Nachricht wird vom Server an den Client gesendet und nachdem der Client die Anfrage erfolgreich ausgeführt hat, werden weitere textDocument/willSaveWaitUntil-Anfragen für JavaScript-Textdokumente vom Client an den Server gesendet.
Antwort:
- result: void.
- error: code und message werden gesetzt, wenn während der Anfrage ein Fehler auftritt.
StaticRegistrationOptions können verwendet werden, um eine Funktion im initialize-Ergebnis mit einer gegebenen Server-Steuerungs-ID zu registrieren, um die Funktion später deregistrieren zu können.
/**
* Static registration options to be returned in the initialize request.
*/
export interface StaticRegistrationOptions {
/**
* The id used to register the request. The id can be used to deregister
* the request again. See also Registration#id.
*/
id?: string;
}
TextDocumentRegistrationOptions kann verwendet werden, um sich dynamisch für Anfragen für eine Reihe von Textdokumenten zu registrieren.
/**
* General text document registration options.
*/
export interface TextDocumentRegistrationOptions {
/**
* A document selector to identify the scope of the registration. If set to
* null the document selector provided on the client side will be used.
*/
documentSelector: DocumentSelector | null;
}
Capability abmelden ()
Die client/unregisterCapability-Anfrage wird vom Server an den Client gesendet, um eine zuvor registrierte Fähigkeit abzumelden.
Anfrage:
- method: ‘client/unregisterCapability’
- params:
UnregistrationParams
Dabei ist UnregistrationParams wie folgt definiert
/**
* 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;
}
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[];
}
Das folgende Beispiel zeigt eine JSON-RPC-Nachricht zur Deregistrierung der oben registrierten textDocument/willSaveWaitUntil-Funktion:
{
"method": "client/unregisterCapability",
"params": {
"unregisterations": [
{
"id": "79eee87c-c409-4664-8102-e03263673f6f",
"method": "textDocument/willSaveWaitUntil"
}
]
}
}
Antwort:
- result: void.
- error: code und message werden gesetzt, wenn während der Anfrage ein Fehler auftritt.
SetTrace-Benachrichtigung ()
Eine Benachrichtigung, die vom Client verwendet werden sollte, um die Trace-Einstellung des Servers zu ändern.
Benachrichtigung:
- method: ‘$/setTrace’
- params:
SetTraceParams, wie folgt definiert
interface SetTraceParams {
/**
* The new value that should be assigned to the trace setting.
*/
value: TraceValue;
}
LogTrace-Benachrichtigung ()
Eine Benachrichtigung, um den Trace der Serverausführung zu protokollieren. Der Umfang und Inhalt dieser Benachrichtigungen hängen von der aktuellen trace-Konfiguration ab. Wenn trace auf 'off' gesetzt ist, sollte der Server keine logTrace-Benachrichtigung senden. Wenn trace auf 'messages' gesetzt ist, sollte der Server das Feld 'verbose' in LogTraceParams nicht hinzufügen.
$/logTrace sollte für die systematische Trace-Berichterstattung verwendet werden. Für einzelne Debugging-Nachrichten sollte der Server window/logMessage-Benachrichtigungen senden.
Benachrichtigung:
- method: ‘$/logTrace’
- params:
LogTraceParams, wie folgt definiert
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;
}
Shutdown-Anfrage ()
Die shutdown-Anfrage wird vom Client an den Server gesendet. Sie fordert den Server auf, sich herunterzufahren, aber nicht zu beenden (andernfalls könnte die Antwort möglicherweise nicht korrekt an den Client geliefert werden). Es gibt eine separate exit-Benachrichtigung, die den Server zum Beenden auffordert. Clients dürfen nach dem Senden einer shutdown-Anfrage keine anderen Benachrichtigungen als exit oder Anfragen an einen Server senden. Clients sollten auch mit dem Senden der exit-Benachrichtigung warten, bis sie eine Antwort auf die shutdown-Anfrage erhalten haben.
Wenn ein Server nach einer shutdown-Anfrage Anfragen erhält, sollten diese mit InvalidRequest fehlschlagen.
Anfrage:
- method: ‘shutdown’
- params: none
Antwort:
- result: null
- error: code und message werden gesetzt, wenn während der shutdown-Anfrage ein Fehler auftritt.
Exit-Benachrichtigung ()
Eine Benachrichtigung, die den Server auffordert, seinen Prozess zu beenden. Der Server sollte mit dem Erfolgs-Code 0 beenden, wenn die shutdown-Anfrage zuvor empfangen wurde; andernfalls mit dem Fehler-Code 1.
Benachrichtigung:
- method: ‘exit’
- params: none
Textdokument-Synchronisierung
Die Client-Unterstützung für die Benachrichtigungen textDocument/didOpen, textDocument/didChange und textDocument/didClose ist im Protokoll zwingend erforderlich und Clients können sich von der Unterstützung nicht abmelden. Dies beinhaltet sowohl die vollständige als auch die inkrementelle Synchronisation in der textDocument/didChange-Benachrichtigung. Darüber hinaus muss ein Server entweder alle drei oder keine davon implementieren. Ihre Capabilities werden daher über eine kombinierte Client- und Server-Capability gesteuert. Der Verzicht auf Textdokument-Synchronisation ist nur dann sinnvoll, wenn die vom Client angezeigten Dokumente schreibgeschützt sind. Andernfalls kann der Server Anfragen für Dokumente erhalten, deren Inhalt im Client verwaltet wird (z. B. diese könnten sich geändert haben).
- Eigenschaftspfad (optional):
textDocument.synchronization.dynamicRegistration - property type:
boolean
Steuert, ob die Textdokument-Synchronisierung dynamische Registrierung unterstützt.
- Eigenschaftspfad (optional):
textDocumentSync - Eigenschaftstyp:
TextDocumentSyncKind | TextDocumentSyncOptions. Die folgende Definition vonTextDocumentSyncOptionsdeckt nur die Eigenschaften ab, die spezifisch für die Benachrichtigungen open, change und close sind. Eine vollständige Definition, die alle Eigenschaften abdeckt, finden Sie hier.
/**
* 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
* sent.
*/
export const Incremental = 2;
}
export type TextDocumentSyncKind = 0 | 1 | 2;
export interface TextDocumentSyncOptions {
/**
* Open and close notifications are sent to the server. If omitted open
* close notifications 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 ()
Die Benachrichtigung „Dokument geöffnet“ wird vom Client an den Server gesendet, um neu geöffnete Textdokumente zu signalisieren. Der Inhalt des Dokuments wird nun vom Client verwaltet und der Server darf nicht versuchen, den Inhalt des Dokuments mithilfe der URI des Dokuments zu lesen. Öffnen in diesem Sinne bedeutet, dass es vom Client verwaltet wird. Es bedeutet nicht unbedingt, dass sein Inhalt in einem Editor angezeigt wird. Eine Öffnungsbenachrichtigung darf nicht mehr als einmal gesendet werden, ohne dass zuvor eine entsprechende Schließungsbenachrichtigung gesendet wurde. Das bedeutet, dass die Öffnungs- und Schließungsbenachrichtigungen ausgeglichen sein müssen und die maximale Anzahl offener Dokumente für ein bestimmtes Textdokument eins beträgt. Beachten Sie, dass die Fähigkeit eines Servers, Anfragen zu erfüllen, unabhängig davon ist, ob ein Textdokument geöffnet oder geschlossen ist.
Die DidOpenTextDocumentParams enthalten die Sprach-ID, mit der das Dokument verknüpft ist. Wenn sich die Sprach-ID eines Dokuments ändert, muss der Client eine textDocument/didClose an den Server senden, gefolgt von einer textDocument/didOpen mit der neuen Sprach-ID, wenn der Server die neue Sprach-ID ebenfalls verarbeitet.
Client-Fähigkeit: Siehe allgemeine Synchronisierungs- Client-Fähigkeiten.
Server-Fähigkeit: Siehe allgemeine Synchronisierungs- Server-Fähigkeiten.
Registrierungsoptionen: TextDocumentRegistrationOptions
Benachrichtigung:
- methode: „textDocument/didOpen“
- parameter:
DidOpenTextDocumentParamswie folgt definiert
interface DidOpenTextDocumentParams {
/**
* The document that was opened.
*/
textDocument: TextDocumentItem;
}
DidChangeTextDocument Notification ()
Die Benachrichtigung „Dokument ändern“ wird vom Client an den Server gesendet, um Änderungen an einem Textdokument zu signalisieren. Bevor ein Client ein Textdokument ändern kann, muss er den Besitz seines Inhalts mithilfe der Benachrichtigung textDocument/didOpen beanspruchen. In Version 2.0 wurde die Form der Parameter geändert, um korrekte Versionsnummern aufzunehmen.
Bevor Informationen vom Server angefordert werden (z. B. textDocument/completion oder textDocument/signatureHelp), muss der Client sicherstellen, dass der Zustand des Dokuments mit dem Server synchronisiert ist, um zuverlässige Ergebnisse zu gewährleisten.
Das folgende Beispiel zeigt, wie der Client den Zustand synchronisieren sollte, wenn der Benutzer kontinuierlich Eingaben macht, vorausgesetzt, die Benutzereingabe hat textDocument/completion ausgelöst:
| Dokumentversion | Benutzereingabe | Verhalten des Clients | Anfrage |
|---|---|---|---|
| 5 | Dokumentänderung eins | Dokument v5 an den Server synchronisieren |
textDocument/didChange |
| 5 | - | Anfrage vom Server, basierend auf Dokument v5 |
textDocument/completion |
| 6 | Dokumentänderung zwei | Dokument v6 an den Server synchronisieren |
textDocument/didChange |
Client-Fähigkeit: Siehe allgemeine Synchronisierungs- Client-Fähigkeiten.
Server-Fähigkeit: Siehe allgemeine Synchronisierungs- Server-Fähigkeiten.
Registrierungsoptionen: TextDocumentChangeRegistrationOptions wie folgt definiert
/**
* 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;
}
Benachrichtigung:
- Methode:
textDocument/didChange - parameter:
DidChangeTextDocumentParamswie folgt definiert
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[];
}
/**
* An event describing a change to a text document. If only a text is provided
* it 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 ()
Die willSave-Benachrichtigung wird vom Client an den Server gesendet, bevor das Dokument tatsächlich gespeichert wird. Wenn ein Server für Open/Close-Ereignisse registriert ist, sollte der Client sicherstellen, dass das Dokument geöffnet ist, bevor eine willSave-Benachrichtigung gesendet wird, da Clients den Inhalt einer Datei nicht ändern können, ohne die Übertragung der Berechtigung.
Client Capability:
- Eigenschaftsname (optional):
textDocument.synchronization.willSave - property type:
boolean
Die Fähigkeit zeigt an, dass der Client textDocument/willSave-Benachrichtigungen unterstützt.
Server-Fähigkeit:
- Eigenschaftsname (optional):
textDocumentSync.willSave - property type:
boolean
Die Fähigkeit zeigt an, dass der Server an textDocument/willSave-Benachrichtigungen interessiert ist.
Registrierungsoptionen: TextDocumentRegistrationOptions
Benachrichtigung:
- methode: „textDocument/willSave“
- parameter:
WillSaveTextDocumentParamswie folgt definiert
/**
* 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;
}
/**
* 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 ()
Die willSaveWaitUntil-Anfrage wird vom Client an den Server gesendet, bevor das Dokument tatsächlich gespeichert wird. Die Anfrage kann ein Array von TextEdits zurückgeben, die vor dem Speichern auf das Textdokument angewendet werden. Bitte beachten Sie, dass Clients Ergebnisse verwerfen können, wenn die Berechnung der TextEdits zu lange dauert oder wenn ein Server bei dieser Anfrage ständig fehlschlägt. Dies geschieht, um das Speichern schnell und zuverlässig zu halten. Wenn ein Server für Open/Close-Ereignisse registriert ist, sollte der Client sicherstellen, dass das Dokument geöffnet ist, bevor eine willSaveWaitUntil-Benachrichtigung gesendet wird, da Clients den Inhalt einer Datei nicht ändern können, ohne die Übertragung der Berechtigung.
Client Capability:
- Eigenschaftsname (optional):
textDocument.synchronization.willSaveWaitUntil - property type:
boolean
Die Fähigkeit zeigt an, dass der Client textDocument/willSaveWaitUntil-Anfragen unterstützt.
Server-Fähigkeit:
- Eigenschaftsname (optional):
textDocumentSync.willSaveWaitUntil - property type:
boolean
Die Fähigkeit zeigt an, dass der Server an textDocument/willSaveWaitUntil-Anfragen interessiert ist.
Registrierungsoptionen: TextDocumentRegistrationOptions
Anfrage:
- Methode:
textDocument/willSaveWaitUntil - parameter:
WillSaveTextDocumentParams
Antwort:
- Ergebnis:
TextEdit[]|null - Fehler: Code und Nachricht werden gesetzt, falls während der
textDocument/willSaveWaitUntil-Anfrage eine Ausnahme auftritt.
DidSaveTextDocument Notification ()
Die Benachrichtigung „Dokument gespeichert“ wird vom Client an den Server gesendet, wenn das Dokument im Client gespeichert wurde.
Client Capability:
- Eigenschaftsname (optional):
textDocument.synchronization.didSave - property type:
boolean
Die Fähigkeit zeigt an, dass der Client textDocument/didSave-Benachrichtigungen unterstützt.
Server-Fähigkeit:
- Eigenschaftsname (optional):
textDocumentSync.save - Eigenschaftstyp:
boolean | SaveOptions, wobeiSaveOptionswie folgt definiert ist
export interface SaveOptions {
/**
* The client is supposed to include the content on save.
*/
includeText?: boolean;
}
Die Fähigkeit zeigt an, dass der Server an textDocument/didSave-Benachrichtigungen interessiert ist.
Registrierungsoptionen: TextDocumentSaveRegistrationOptions wie folgt definiert
export interface TextDocumentSaveRegistrationOptions
extends TextDocumentRegistrationOptions {
/**
* The client is supposed to include the content on save.
*/
includeText?: boolean;
}
Benachrichtigung:
- Methode:
textDocument/didSave - parameter:
DidSaveTextDocumentParamswie folgt definiert
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 ()
Die Benachrichtigung „Dokument geschlossen“ wird vom Client an den Server gesendet, wenn das Dokument im Client geschlossen wurde. Der Master des Dokuments existiert nun dort, wo die URI des Dokuments hinzeigt (z.B. wenn die URI des Dokuments eine Datei-URI ist, existiert der Master nun auf der Festplatte). Wie bei der Öffnungsbenachrichtigung geht es bei der Schließungsbenachrichtigung um die Verwaltung des Dokumenteninhalts. Der Empfang einer Schließungsbenachrichtigung bedeutet nicht, dass das Dokument zuvor in einem Editor geöffnet war. Eine Schließungsbenachrichtigung erfordert die vorherige Zusendung einer Öffnungsbenachrichtigung. Beachten Sie, dass die Fähigkeit eines Servers, Anfragen zu erfüllen, unabhängig davon ist, ob ein Textdokument geöffnet oder geschlossen ist.
Client-Fähigkeit: Siehe allgemeine Synchronisierungs- Client-Fähigkeiten.
Server-Fähigkeit: Siehe allgemeine Synchronisierungs- Server-Fähigkeiten.
Registrierungsoptionen: TextDocumentRegistrationOptions
Benachrichtigung:
- Methode:
textDocument/didClose - parameter:
DidCloseTextDocumentParamswie folgt definiert
interface DidCloseTextDocumentParams {
/**
* The document that was closed.
*/
textDocument: TextDocumentIdentifier;
}
Umbenennen eines Dokuments
Dokumentumbenennungen sollten an einen Server signalisiert werden, indem eine document close-Benachrichtigung mit dem alten Namen des Dokuments gesendet und anschließend eine document open-Benachrichtigung mit dem neuen Namen des Dokuments gesendet wird. Der Hauptgrund dafür ist, dass neben dem Namen auch andere Attribute wie die Sprache, die dem Dokument zugeordnet ist, geändert werden können. Darüber hinaus ist das neue Dokument für den Server möglicherweise nicht mehr von Interesse.
Server können an einer Dokumentumbenennung teilnehmen, indem sie sich für die workspace/didRenameFiles-Benachrichtigung oder die workspace/willRenameFiles-Anfrage abonnieren.
Die endgültige Struktur der TextDocumentSyncClientCapabilities und der TextDocumentSyncOptions Serveroptionen sieht wie folgt aus
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;
}
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;
}
Synchronisation von Notebook-Dokumenten
Notebooks werden immer beliebter. Die Hinzufügung von Unterstützung für sie zum Language Server Protocol ermöglicht es Notebook-Editoren, Sprachintelligenz wiederzuverwenden, die vom Server innerhalb eines Notebooks oder einer Notebook-Zelle bereitgestellt wird. Um Protokollteile und damit Serverimplementierungen wiederzuverwenden, werden Notebooks im LSP wie folgt modelliert:
- Notebook-Dokument: eine Sammlung von Notebook-Zellen, die typischerweise in einer Datei auf der Festplatte gespeichert ist. Ein Notebook-Dokument hat einen Typ und kann eindeutig anhand einer Ressourcen-URI identifiziert werden.
- Notebook-Zelle: enthält den eigentlichen Textinhalt. Zellen haben eine Art (entweder Code oder Markdown). Der eigentliche Textinhalt der Zelle wird in einem Textdokument gespeichert, das wie alle anderen Textdokumente an den Server synchronisiert werden kann. Zelltextdokumente haben eine URI, aber Server sollten sich nicht auf ein bestimmtes Format dieser URI verlassen, da es dem Client überlassen bleibt, wie er diese URIs erstellt. Die URIs müssen über ALLE Notebook-Zellen hinweg eindeutig sein und können daher verwendet werden, um eine Notebook-Zelle oder das Textdokument der Zelle eindeutig zu identifizieren.
Die beiden Konzepte werden wie folgt definiert:
/**
* A notebook document.
*
* @since 3.17.0
*/
export interface NotebookDocument {
/**
* The notebook document's URI.
*/
uri: URI;
/**
* The type of the notebook.
*/
notebookType: string;
/**
* The version number of this document (it will increase after each
* change, including undo/redo).
*/
version: integer;
/**
* Additional metadata stored with the notebook
* document.
*/
metadata?: LSPObject;
/**
* The cells of a notebook.
*/
cells: NotebookCell[];
}
/**
* A notebook cell.
*
* A cell's document URI must be unique across ALL notebook
* cells and can therefore be used to uniquely identify a
* notebook cell or the cell's text document.
*
* @since 3.17.0
*/
export interface NotebookCell {
/**
* The cell's kind
*/
kind: NotebookCellKind;
/**
* The URI of the cell's text document
* content.
*/
document: DocumentUri;
/**
* Additional metadata stored with the cell.
*/
metadata?: LSPObject;
/**
* Additional execution summary information
* if supported by the client.
*/
executionSummary?: ExecutionSummary;
}
/**
* A notebook cell kind.
*
* @since 3.17.0
*/
export namespace NotebookCellKind {
/**
* A markup-cell is formatted source that is used for display.
*/
export const Markup: 1 = 1;
/**
* A code-cell is source code.
*/
export const Code: 2 = 2;
}
export interface ExecutionSummary {
/**
* A strict monotonically increasing value
* indicating the execution order of a cell
* inside a notebook.
*/
executionOrder: uinteger;
/**
* Whether the execution was successful or
* not if known by the client.
*/
success?: boolean;
}
Im Folgenden beschreiben wir, wie Notebooks, Notebook-Zellen und der Inhalt einer Notebook-Zelle an einen Language Server synchronisiert werden sollten.
Die Synchronisation des Textinhalts einer Zelle ist relativ einfach, da Clients sie als Textdokumente modellieren sollten. Da die URI eines Notebook-Zelltextdokuments jedoch opak sein soll, kann der Server weder sein Schema noch seinen Pfad kennen. Was jedoch bekannt ist, ist das Notebook-Dokument selbst. Wir führen daher einen speziellen Filter für Notebook-Zellendokumente ein:
/**
* A notebook cell text document filter denotes a cell text
* document by different properties.
*
* @since 3.17.0
*/
export interface NotebookCellTextDocumentFilter {
/**
* A filter that matches against the notebook
* containing the notebook cell. If a string
* value is provided it matches against the
* notebook type. '*' matches every notebook.
*/
notebook: string | NotebookDocumentFilter;
/**
* A language id like `python`.
*
* Will be matched against the language id of the
* notebook cell document. '*' matches every language.
*/
language?: string;
}
/**
* A notebook document filter denotes a notebook document by
* different properties.
*
* @since 3.17.0
*/
export type NotebookDocumentFilter = {
/** The type of the enclosing notebook. */
notebookType: string;
/** A Uri scheme, like `file` or `untitled`. */
scheme?: string;
/** A glob pattern. */
pattern?: string;
} | {
/** The type of the enclosing notebook. */
notebookType?: string;
/** A Uri scheme, like `file` or `untitled`.*/
scheme: string;
/** A glob pattern. */
pattern?: string;
} | {
/** The type of the enclosing notebook. */
notebookType?: string;
/** A Uri scheme, like `file` or `untitled`. */
scheme?: string;
/** A glob pattern. */
pattern: string;
};
Angesichts dieser Strukturen kann ein Python-Zellendokument in einem Jupyter-Notebook, das auf der Festplatte in einem Ordner mit books1 in seinem Pfad gespeichert ist, wie folgt identifiziert werden;
{
notebook: {
scheme: 'file',
pattern '**/books1/**',
notebookType: 'jupyter-notebook'
},
language: 'python'
}
Ein NotebookCellTextDocumentFilter kann verwendet werden, um Anbieter für bestimmte Anfragen wie Code-Vervollständigung oder Hover zu registrieren. Wenn ein solcher Anbieter registriert ist, sendet der Client die entsprechenden textDocument/*-Anfragen an den Server, wobei die URI des Zelltextdokuments als Dokumenten-URI verwendet wird.
Es gibt Fälle, in denen es für einen Server nicht ausreicht, nur den Textinhalt einer Zelle zu kennen, um über den Inhalt der Zelle nachzudenken und gute Sprachintelligenz bereitzustellen. Manchmal ist es notwendig, alle Zellen eines Notebook-Dokuments einschließlich des Notebook-Dokuments selbst zu kennen. Betrachten Sie ein Notebook, das zwei JavaScript-Zellen mit folgendem Inhalt hat:
Zelle eins
function add(a, b) {
return a + b;
}
Zelle zwei
add/*<cursor>*/;
Das Anfordern von Code-Assistenz in Zelle zwei an der markierten Cursorposition sollte die Funktion add vorschlagen, was nur möglich ist, wenn der Server Zelle eins und Zelle zwei kennt und weiß, dass sie zum selben Notebook-Dokument gehören.
Das Protokoll unterstützt daher zwei Modi bei der Synchronisation des Zelltextinhalts:
-
cellContent: In diesem Modus wird nur der Zelltextinhalt über die Standardbenachrichtigung
textDocument/did*an den Server synchronisiert. Kein Notebook-Dokument und keine Zellstruktur wird synchronisiert. Dieser Modus ermöglicht eine einfache Übernahme von Notebooks, da Server den größten Teil ihrer Implementierungslogik wiederverwenden können. -
notebook: In diesem Modus werden das Notebook-Dokument, die Notebook-Zellen und der Notebook-Zelltextinhalt an den Server synchronisiert. Um Servern zu ermöglichen, ein konsistentes Bild eines Notebook-Dokuments zu erstellen, wird der Zelltextinhalt NICHT über die Standardbenachrichtigungen
textDocument/did*synchronisiert. Stattdessen wird er über speziellenotebookDocument/did*-Benachrichtigungen synchronisiert. Dies stellt sicher, dass die Zelle und ihr Textinhalt über ein einziges Open-, Change- oder Close-Ereignis auf dem Server ankommen.
Um nur den Zellinhalt abzurufen, kann ein normaler Dokumenten-Selektor verwendet werden. Zum Beispiel synchronisiert der Selektor [{ language: 'python' }] Python-Notebook-Dokumentenzellen mit dem Server. Da dies jedoch auch unerwünschte Dokumente synchronisieren könnte, kann ein Dokumentenfilter auch ein NotebookCellTextDocumentFilter sein. So synchronisiert { notebook: { scheme: 'file', notebookType: 'jupyter-notebook' }, language: 'python' } alle Python-Zellen in einem Jupyter-Notebook, das auf der Festplatte gespeichert ist.
Um das gesamte Notebook-Dokument zu synchronisieren, stellt ein Server in seinen Server-Capabilities eine notebookDocumentSync-Option bereit. Zum Beispiel:
{
notebookDocumentSync: {
notebookSelector: [
{
notebook: { scheme: 'file', notebookType: 'jupyter-notebook' },
cells: [{ language: 'python' }]
}
]
}
}
Synchronisiert das Notebook einschließlich aller Python-Zellen mit dem Server, wenn das Notebook auf der Festplatte gespeichert ist.
Client Capability:
Die folgenden Client-Capabilities sind für Notebook-Dokumente definiert:
- Eigenschaftsname (optional):
notebookDocument.synchronization - Eigenschaftstyp:
NotebookDocumentSyncClientCapabilities, wie folgt definiert:
/**
* Notebook specific client capabilities.
*
* @since 3.17.0
*/
export interface NotebookDocumentSyncClientCapabilities {
/**
* Whether implementation supports dynamic registration. If this is
* set to `true` the client supports the new
* `(NotebookDocumentSyncRegistrationOptions & NotebookDocumentSyncOptions)`
* return value for the corresponding server capability as well.
*/
dynamicRegistration?: boolean;
/**
* The client supports sending execution summary data per cell.
*/
executionSummarySupport?: boolean;
}
Server-Fähigkeit:
Die folgenden Server-Capabilities sind für Notebook-Dokumente definiert:
- Eigenschaftsname (optional):
notebookDocumentSync - Eigenschaftstyp:
NotebookDocumentSyncOptions | NotebookDocumentSyncRegistrationOptions, wobeiNotebookDocumentOptionswie folgt definiert ist:
/**
* Options specific to a notebook plus its cells
* to be synced to the server.
*
* If a selector provides a notebook document
* filter but no cell selector all cells of a
* matching notebook document will be synced.
*
* If a selector provides no notebook document
* filter but only a cell selector all notebook
* documents that contain at least one matching
* cell will be synced.
*
* @since 3.17.0
*/
export interface NotebookDocumentSyncOptions {
/**
* The notebooks to be synced
*/
notebookSelector: ({
/**
* The notebook to be synced. If a string
* value is provided it matches against the
* notebook type. '*' matches every notebook.
*/
notebook: string | NotebookDocumentFilter;
/**
* The cells of the matching notebook to be synced.
*/
cells?: { language: string }[];
} | {
/**
* The notebook to be synced. If a string
* value is provided it matches against the
* notebook type. '*' matches every notebook.
*/
notebook?: string | NotebookDocumentFilter;
/**
* The cells of the matching notebook to be synced.
*/
cells: { language: string }[];
})[];
/**
* Whether save notification should be forwarded to
* the server. Will only be honored if mode === `notebook`.
*/
save?: boolean;
}
Registrierungsoptionen: notebookDocumentSyncRegistrationOptions, wie folgt definiert:
/**
* Registration options specific to a notebook.
*
* @since 3.17.0
*/
export interface NotebookDocumentSyncRegistrationOptions extends
NotebookDocumentSyncOptions, StaticRegistrationOptions {
}
DidOpenNotebookDocument Benachrichtigung ()
Die Benachrichtigung über das Öffnen wird vom Client an den Server gesendet, wenn ein Notebook-Dokument geöffnet wird. Sie wird nur von einem Client gesendet, wenn der Server den Synchronisationsmodus notebook in seiner notebookDocumentSync Fähigkeit angefordert hat.
Benachrichtigung:
- Methode:
notebookDocument/didOpen - Parameter:
DidOpenNotebookDocumentParamswie folgt definiert
/**
* The params sent in an open notebook document notification.
*
* @since 3.17.0
*/
export interface DidOpenNotebookDocumentParams {
/**
* The notebook document that got opened.
*/
notebookDocument: NotebookDocument;
/**
* The text documents that represent the content
* of a notebook cell.
*/
cellTextDocuments: TextDocumentItem[];
}
DidChangeNotebookDocument Benachrichtigung ()
Die Änderungsbenachrichtigung wird vom Client an den Server gesendet, wenn sich ein Notebook-Dokument ändert. Sie wird nur von einem Client gesendet, wenn der Server den Synchronisationsmodus notebook in seiner notebookDocumentSync Fähigkeit angefordert hat.
Benachrichtigung:
- Methode:
notebookDocument/didChange - Parameter:
DidChangeNotebookDocumentParamswie folgt definiert
/**
* The params sent in a change notebook document notification.
*
* @since 3.17.0
*/
export interface DidChangeNotebookDocumentParams {
/**
* The notebook document that did change. The version number points
* to the version after all provided changes have been applied.
*/
notebookDocument: VersionedNotebookDocumentIdentifier;
/**
* The actual changes to the notebook document.
*
* The change describes single state change to the notebook document.
* So it moves a notebook document, its cells and its cell text document
* contents from state S to S'.
*
* To mirror the content of a notebook using change events use the
* following approach:
* - start with the same initial content
* - apply the 'notebookDocument/didChange' notifications in the order
* you receive them.
*/
change: NotebookDocumentChangeEvent;
}
/**
* A versioned notebook document identifier.
*
* @since 3.17.0
*/
export interface VersionedNotebookDocumentIdentifier {
/**
* The version number of this notebook document.
*/
version: integer;
/**
* The notebook document's URI.
*/
uri: URI;
}
/**
* A change event for a notebook document.
*
* @since 3.17.0
*/
export interface NotebookDocumentChangeEvent {
/**
* The changed meta data if any.
*/
metadata?: LSPObject;
/**
* Changes to cells
*/
cells?: {
/**
* Changes to the cell structure to add or
* remove cells.
*/
structure?: {
/**
* The change to the cell array.
*/
array: NotebookCellArrayChange;
/**
* Additional opened cell text documents.
*/
didOpen?: TextDocumentItem[];
/**
* Additional closed cell text documents.
*/
didClose?: TextDocumentIdentifier[];
};
/**
* Changes to notebook cells properties like its
* kind, execution summary or metadata.
*/
data?: NotebookCell[];
/**
* Changes to the text content of notebook cells.
*/
textContent?: {
document: VersionedTextDocumentIdentifier;
changes: TextDocumentContentChangeEvent[];
}[];
};
}
/**
* A change describing how to move a `NotebookCell`
* array from state S to S'.
*
* @since 3.17.0
*/
export interface NotebookCellArrayChange {
/**
* The start offset of the cell that changed.
*/
start: uinteger;
/**
* The deleted cells
*/
deleteCount: uinteger;
/**
* The new cells, if any
*/
cells?: NotebookCell[];
}
DidSaveNotebookDocument Benachrichtigung ()
Die Speicherbenachrichtigung wird vom Client an den Server gesendet, wenn ein Notebook-Dokument gespeichert wird. Sie wird nur von einem Client gesendet, wenn der Server den Synchronisationsmodus notebook in seiner notebookDocumentSync Fähigkeit angefordert hat.
Benachrichtigung:
- Methode:
notebookDocument/didSave - Parameter:
DidSaveNotebookDocumentParamswie folgt definiert
/**
* The params sent in a save notebook document notification.
*
* @since 3.17.0
*/
export interface DidSaveNotebookDocumentParams {
/**
* The notebook document that got saved.
*/
notebookDocument: NotebookDocumentIdentifier;
}
DidCloseNotebookDocument Benachrichtigung ()
Die Schließungsbenachrichtigung wird vom Client an den Server gesendet, wenn ein Notebook-Dokument geschlossen wird. Sie wird nur von einem Client gesendet, wenn der Server den Synchronisationsmodus notebook in seiner notebookDocumentSync Fähigkeit angefordert hat.
Benachrichtigung:
- Methode:
notebookDocument/didClose - Parameter:
DidCloseNotebookDocumentParamswie folgt definiert
/**
* The params sent in a close notebook document notification.
*
* @since 3.17.0
*/
export interface DidCloseNotebookDocumentParams {
/**
* The notebook document that got closed.
*/
notebookDocument: NotebookDocumentIdentifier;
/**
* The text documents that represent the content
* of a notebook cell that got closed.
*/
cellTextDocuments: TextDocumentIdentifier[];
}
/**
* A literal to identify a notebook document in the client.
*
* @since 3.17.0
*/
export interface NotebookDocumentIdentifier {
/**
* The notebook document's URI.
*/
uri: URI;
}
Sprachfunktionen
Sprachfunktionen (Language Features) bieten die eigentliche Intelligenz im Language Server Protocol. Sie werden normalerweise auf einem Tupel aus [Textdokument, Position] ausgeführt. Die Hauptkategorien von Sprachfunktionen sind:
- Funktionen zur Code-Verständigung wie Hover oder Goto Definition.
- Codierungsfunktionen wie Diagnostik, Code-Vervollständigung oder Code-Aktionen.
Die Sprachfunktionen sollten auf dem synchronisierten Zustand des Dokuments berechnet werden.
Goto Declaration Request ()
Seit Version 3.14.0
Die Anfrage „Zu Deklaration springen“ wird vom Client an den Server gesendet, um die Deklarationsposition eines Symbols an einer gegebenen Textdokumentposition aufzulösen.
Der Ergebnistyp LocationLink[] wurde mit Version 3.14.0 eingeführt und hängt von der entsprechenden Client-Fähigkeit textDocument.declaration.linkSupport ab.
Client Capability:
- Eigenschaftsname (optional):
textDocument.declaration - Eigenschaftstyp:
DeclarationClientCapabilitieswie folgt definiert
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-Fähigkeit:
- Eigenschaftsname (optional):
declarationProvider - Eigenschaftstyp:
boolean | DeclarationOptions | DeclarationRegistrationOptions, wobeiDeclarationOptionswie folgt definiert ist
export interface DeclarationOptions extends WorkDoneProgressOptions {
}
Registrierungsoptionen: DeclarationRegistrationOptions wie folgt definiert
export interface DeclarationRegistrationOptions extends DeclarationOptions,
TextDocumentRegistrationOptions, StaticRegistrationOptions {
}
Anfrage:
- Methode:
textDocument/declaration - parameter:
DeclarationParamswie folgt definiert
export interface DeclarationParams extends TextDocumentPositionParams,
WorkDoneProgressParams, PartialResultParams {
}
Antwort:
- Ergebnis:
Location|Location[] |LocationLink[] |null - Teilergebnis:
Location[] |LocationLink[] - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Deklarationsanfrage auftritt.
Gehe zu Definition Anfrage ()
Die Anfrage "Gehe zu Definition" wird vom Client an den Server gesendet, um die Definitionsstelle eines Symbols an einer gegebenen Textdokumentposition aufzulösen.
Der Ergebnistyp LocationLink[] wurde mit Version 3.14.0 eingeführt und hängt von der entsprechenden Client-Fähigkeit textDocument.definition.linkSupport ab.
Client Capability:
- Eigenschaftsname (optional):
textDocument.definition - Eigenschaftstyp:
DefinitionClientCapabilities, wie folgt definiert:
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-Fähigkeit:
- Eigenschaftsname (optional):
definitionProvider - Eigenschaftstyp:
boolean | DefinitionOptions, wobeiDefinitionOptionswie folgt definiert ist:
export interface DefinitionOptions extends WorkDoneProgressOptions {
}
Registrierungsoptionen: DefinitionRegistrationOptions, wie folgt definiert:
export interface DefinitionRegistrationOptions extends
TextDocumentRegistrationOptions, DefinitionOptions {
}
Anfrage:
- Methode:
textDocument/definition - Parameter:
DefinitionParams, wie folgt definiert:
export interface DefinitionParams extends TextDocumentPositionParams,
WorkDoneProgressParams, PartialResultParams {
}
Antwort:
- Ergebnis:
Location|Location[] |LocationLink[] |null - Teilergebnis:
Location[] |LocationLink[] - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Definitionsanfrage auftritt.
Gehe zu Typdefinition Anfrage ()
Seit Version 3.6.0
Die Anfrage "Gehe zu Typdefinition" wird vom Client an den Server gesendet, um die Typdefinitionsstelle eines Symbols an einer gegebenen Textdokumentposition aufzulösen.
Der Ergebnistyp LocationLink[] wurde mit Version 3.14.0 eingeführt und hängt von der entsprechenden Client-Fähigkeit textDocument.typeDefinition.linkSupport ab.
Client Capability:
- Eigenschaftsname (optional):
textDocument.typeDefinition - Eigenschaftstyp:
TypeDefinitionClientCapabilities, wie folgt definiert:
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-Fähigkeit:
- Eigenschaftsname (optional):
typeDefinitionProvider - Eigenschaftstyp:
boolean | TypeDefinitionOptions | TypeDefinitionRegistrationOptions, wobeiTypeDefinitionOptionswie folgt definiert ist:
export interface TypeDefinitionOptions extends WorkDoneProgressOptions {
}
Registrierungsoptionen: TypeDefinitionRegistrationOptions, wie folgt definiert:
export interface TypeDefinitionRegistrationOptions extends
TextDocumentRegistrationOptions, TypeDefinitionOptions,
StaticRegistrationOptions {
}
Anfrage:
- Methode:
textDocument/typeDefinition - Parameter:
TypeDefinitionParams, wie folgt definiert:
export interface TypeDefinitionParams extends TextDocumentPositionParams,
WorkDoneProgressParams, PartialResultParams {
}
Antwort:
- Ergebnis:
Location|Location[] |LocationLink[] |null - Teilergebnis:
Location[] |LocationLink[] - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Definitionsanfrage auftritt.
Suche Implementierungsanfrage ()
Seit Version 3.6.0
Die Anfrage "Suche Implementierung" wird vom Client an den Server gesendet, um die Implementierungsstelle eines Symbols an einer gegebenen Textdokumentposition aufzulösen.
Der Ergebnistyp LocationLink[] wurde mit Version 3.14.0 eingeführt und hängt von der entsprechenden Client-Fähigkeit textDocument.implementation.linkSupport ab.
Client Capability:
- Eigenschaftsname (optional):
textDocument.implementation - Eigenschaftstyp:
ImplementationClientCapabilities, wie folgt definiert:
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-Fähigkeit:
- Eigenschaftsname (optional):
implementationProvider - Eigenschaftstyp:
boolean | ImplementationOptions | ImplementationRegistrationOptions, wobeiImplementationOptionswie folgt definiert ist:
export interface ImplementationOptions extends WorkDoneProgressOptions {
}
Registrierungsoptionen: ImplementationRegistrationOptions, wie folgt definiert:
export interface ImplementationRegistrationOptions extends
TextDocumentRegistrationOptions, ImplementationOptions,
StaticRegistrationOptions {
}
Anfrage:
- Methode:
textDocument/implementation - Parameter:
ImplementationParams, wie folgt definiert:
export interface ImplementationParams extends TextDocumentPositionParams,
WorkDoneProgressParams, PartialResultParams {
}
Antwort:
- Ergebnis:
Location|Location[] |LocationLink[] |null - Teilergebnis:
Location[] |LocationLink[] - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Definitionsanfrage auftritt.
Suche Referenzanfrage ()
Die Referenzanfrage wird vom Client an den Server gesendet, um projektweite Referenzen für das durch die gegebene Textdokumentposition bezeichnete Symbol aufzulösen.
Client Capability:
- Eigenschaftsname (optional):
textDocument.references - Eigenschaftstyp:
ReferenceClientCapabilities, wie folgt definiert:
export interface ReferenceClientCapabilities {
/**
* Whether references supports dynamic registration.
*/
dynamicRegistration?: boolean;
}
Server-Fähigkeit:
- Eigenschaftsname (optional):
referencesProvider - Eigenschaftstyp:
boolean | ReferenceOptions, wobeiReferenceOptionswie folgt definiert ist:
export interface ReferenceOptions extends WorkDoneProgressOptions {
}
Registrierungsoptionen: ReferenceRegistrationOptions, wie folgt definiert:
export interface ReferenceRegistrationOptions extends
TextDocumentRegistrationOptions, ReferenceOptions {
}
Anfrage:
- Methode:
textDocument/references - Parameter:
ReferenceParams, wie folgt definiert:
export interface ReferenceParams extends TextDocumentPositionParams,
WorkDoneProgressParams, PartialResultParams {
context: ReferenceContext;
}
export interface ReferenceContext {
/**
* Include the declaration of the current symbol.
*/
includeDeclaration: boolean;
}
Antwort:
- Ergebnis:
Location[] |null - Teilergebnis:
Location[] - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Referenzanfrage auftritt.
Aufrufhierarchie vorbereiten Anfrage ()
Seit Version 3.16.0
Die Anfrage zur Aufrufhierarchie wird vom Client an den Server gesendet, um eine Aufrufhierarchie für das Sprachelement der angegebenen Textdokumentpositionen zurückzugeben. Die Anfragen zur Aufrufhierarchie werden in zwei Schritten ausgeführt:
- zuerst wird ein Aufrufhierarchie-Element für die gegebene Textdokumentposition aufgelöst
- für ein Aufrufhierarchie-Element werden die eingehenden oder ausgehenden Aufrufhierarchie-Elemente aufgelöst.
Client Capability:
- Eigenschaftsname (optional):
textDocument.callHierarchy - property type:
CallHierarchyClientCapabilitiesdefiniert wie folgt
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-Fähigkeit:
- property name (optional):
callHierarchyProvider - property type:
boolean | CallHierarchyOptions | CallHierarchyRegistrationOptionswobeiCallHierarchyOptionswie folgt definiert ist
export interface CallHierarchyOptions extends WorkDoneProgressOptions {
}
Registration Options: CallHierarchyRegistrationOptions definiert wie folgt
export interface CallHierarchyRegistrationOptions extends
TextDocumentRegistrationOptions, CallHierarchyOptions,
StaticRegistrationOptions {
}
Anfrage:
- Methode:
textDocument/prepareCallHierarchy - params:
CallHierarchyPrepareParamsdefiniert wie folgt
export interface CallHierarchyPrepareParams extends TextDocumentPositionParams,
WorkDoneProgressParams {
}
Antwort:
- result:
CallHierarchyItem[] | nulldefiniert wie folgt
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?: LSPAny;
}
- error: code und message gesetzt im Falle eines Exceptions während der ‘textDocument/prepareCallHierarchy’ Anfrage
Call Hierarchy Incoming Calls ()
Seit Version 3.16.0
Die Anfrage wird vom Client an den Server gesendet, um eingehende Aufrufe für ein gegebenes Call-Hierarchy-Element aufzulösen. Die Anfrage definiert keine eigenen Client- und Server-Capabilities. Sie wird nur ausgestellt, wenn ein Server für die textDocument/prepareCallHierarchy Anfrage registriert ist.
Anfrage:
- Methode:
callHierarchy/incomingCalls - params:
CallHierarchyIncomingCallsParamsdefiniert wie folgt
export interface CallHierarchyIncomingCallsParams extends
WorkDoneProgressParams, PartialResultParams {
item: CallHierarchyItem;
}
Antwort:
- result:
CallHierarchyIncomingCall[] | nulldefiniert wie folgt
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 und message gesetzt im Falle eines Exceptions während der ‘callHierarchy/incomingCalls’ Anfrage
Call Hierarchy Outgoing Calls ()
Seit Version 3.16.0
Die Anfrage wird vom Client an den Server gesendet, um ausgehende Aufrufe für ein gegebenes Call-Hierarchy-Element aufzulösen. Die Anfrage definiert keine eigenen Client- und Server-Capabilities. Sie wird nur ausgestellt, wenn ein Server für die textDocument/prepareCallHierarchy Anfrage registriert ist.
Anfrage:
- Methode:
callHierarchy/outgoingCalls - params:
CallHierarchyOutgoingCallsParamsdefiniert wie folgt
export interface CallHierarchyOutgoingCallsParams extends
WorkDoneProgressParams, PartialResultParams {
item: CallHierarchyItem;
}
Antwort:
- result:
CallHierarchyOutgoingCall[] | nulldefiniert wie folgt
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 und message gesetzt im Falle eines Exceptions während der ‘callHierarchy/outgoingCalls’ Anfrage
Anfrage zur Vorbereitung der Typenhierarchie ()
Seit Version 3.17.0
Die Anfrage zur Typenhierarchie wird vom Client an den Server gesendet, um eine Typenhierarchie für das Sprachelement der angegebenen Textdokumentpositionen zurückzugeben. Gibt null zurück, wenn der Server keine gültige Typinferenz von der Position vornehmen konnte. Die Anfragen zur Typenhierarchie werden in zwei Schritten ausgeführt:
- zuerst wird ein Typenhierarchie-Element für die angegebene Textdokumentposition vorbereitet.
- für ein Typenhierarchie-Element werden die Obertyp- oder Untertyp-Typenhierarchie-Elemente aufgelöst.
Client Capability:
- Eigenschaftsname (optional):
textDocument.typeHierarchy - Eigenschaftstyp:
TypeHierarchyClientCapabilitieswie folgt definiert
type TypeHierarchyClientCapabilities = {
/**
* 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-Fähigkeit:
- Eigenschaftsname (optional):
typeHierarchyProvider - Eigenschaftstyp:
boolean | TypeHierarchyOptions | TypeHierarchyRegistrationOptionswobeiTypeHierarchyOptionswie folgt definiert ist
export interface TypeHierarchyOptions extends WorkDoneProgressOptions {
}
Registrierungsoptionen: TypeHierarchyRegistrationOptions wie folgt definiert
export interface TypeHierarchyRegistrationOptions extends
TextDocumentRegistrationOptions, TypeHierarchyOptions,
StaticRegistrationOptions {
}
Anfrage:
- Methode: ‘textDocument/prepareTypeHierarchy’
- Parameter:
TypeHierarchyPrepareParamswie folgt definiert
export interface TypeHierarchyPrepareParams extends TextDocumentPositionParams,
WorkDoneProgressParams {
}
Antwort:
- Ergebnis:
TypeHierarchyItem[] | nullwie folgt definiert
export interface TypeHierarchyItem {
/**
* 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`](#TypeHierarchyItem.range).
*/
selectionRange: Range;
/**
* A data entry field that is preserved between a type hierarchy prepare and
* supertypes or subtypes requests. It could also be used to identify the
* type hierarchy in the server, helping improve the performance on
* resolving supertypes and subtypes.
*/
data?: LSPAny;
}
- Fehler: Code und Nachricht werden gesetzt, wenn während der Anfrage ‘textDocument/prepareTypeHierarchy’ eine Ausnahme auftritt.
Typenhierarchie-Obertypen ()
Seit Version 3.17.0
Die Anfrage wird vom Client an den Server gesendet, um die Obertypen für ein gegebenes Typenhierarchie-Element aufzulösen. Gibt null zurück, wenn der Server keine gültige Typinferenz aus item in den Parametern vornehmen konnte. Die Anfrage definiert keine eigenen Client- und Serverfähigkeiten. Sie wird nur ausgegeben, wenn ein Server sich für die Anfrage textDocument/prepareTypeHierarchy registriert.
Anfrage:
- Methode: ‘typeHierarchy/supertypes’
- Parameter:
TypeHierarchySupertypesParamswie folgt definiert
export interface TypeHierarchySupertypesParams extends
WorkDoneProgressParams, PartialResultParams {
item: TypeHierarchyItem;
}
Antwort:
- Ergebnis:
TypeHierarchyItem[] | null - Teilergebnis:
TypeHierarchyItem[] - Fehler: Code und Nachricht werden gesetzt, wenn während der Anfrage ‘typeHierarchy/supertypes’ eine Ausnahme auftritt.
Typenhierarchie-Untertypen ()
Seit Version 3.17.0
Die Anfrage wird vom Client an den Server gesendet, um die Untertypen für ein gegebenes Typenhierarchie-Element aufzulösen. Gibt null zurück, wenn der Server keine gültige Typinferenz aus item in den Parametern vornehmen konnte. Die Anfrage definiert keine eigenen Client- und Serverfähigkeiten. Sie wird nur ausgegeben, wenn ein Server sich für die Anfrage textDocument/prepareTypeHierarchy registriert.
Anfrage:
- Methode: ‘typeHierarchy/subtypes’
- Parameter:
TypeHierarchySubtypesParamswie folgt definiert
export interface TypeHierarchySubtypesParams extends
WorkDoneProgressParams, PartialResultParams {
item: TypeHierarchyItem;
}
Antwort:
- Ergebnis:
TypeHierarchyItem[] | null - Teilergebnis:
TypeHierarchyItem[] - Fehler: Code und Nachricht werden gesetzt, wenn während der Anfrage ‘typeHierarchy/subtypes’ eine Ausnahme auftritt.
Dokument-Highlights-Anfrage ()
Die Anfrage zur Dokumenten-Hervorhebung wird vom Client an den Server gesendet, um Dokumenten-Hervorhebungen für eine gegebene Textdokumentposition aufzulösen. Für Programmiersprachen werden hier normalerweise alle Referenzen auf das Symbol innerhalb dieser Datei hervorgehoben. Wir haben jedoch ‘textDocument/documentHighlight’ und ‘textDocument/references’ als separate Anfragen belassen, da die erstere auch unscharfe Übereinstimmungen zulässt. Symbolübereinstimmungen haben normalerweise eine DocumentHighlightKind von Read oder Write, während unscharfe oder textuelle Übereinstimmungen Text als Art verwenden.
Client Capability:
- Eigenschaftsname (optional):
textDocument.documentHighlight - Eigenschaftstyp:
DocumentHighlightClientCapabilities, wie folgt definiert:
export interface DocumentHighlightClientCapabilities {
/**
* Whether document highlight supports dynamic registration.
*/
dynamicRegistration?: boolean;
}
Server-Fähigkeit:
- Eigenschaftsname (optional):
documentHighlightProvider - Eigenschaftstyp:
boolean | DocumentHighlightOptions, wobeiDocumentHighlightOptionswie folgt definiert ist:
export interface DocumentHighlightOptions extends WorkDoneProgressOptions {
}
Registrierungsoptionen: DocumentHighlightRegistrationOptions, wie folgt definiert:
export interface DocumentHighlightRegistrationOptions extends
TextDocumentRegistrationOptions, DocumentHighlightOptions {
}
Anfrage:
- Methode:
textDocument/documentHighlight - Parameter:
DocumentHighlightParams, wie folgt definiert:
export interface DocumentHighlightParams extends TextDocumentPositionParams,
WorkDoneProgressParams, PartialResultParams {
}
Antwort:
- Ergebnis:
DocumentHighlight[]|null, wie folgt definiert:
/**
* 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;
}
/**
* 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;
- Teilergebnis:
DocumentHighlight[] - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Dokument-Highlight-Anfrage auftritt.
Dokument-Link-Anfrage ()
Die Dokument-Link-Anfrage wird vom Client an den Server gesendet, um die Position von Links in einem Dokument anzufordern.
Client Capability:
- Eigenschaftsname (optional):
textDocument.documentLink - Eigenschaftstyp:
DocumentLinkClientCapabilities, wie folgt definiert:
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-Fähigkeit:
- Eigenschaftsname (optional):
documentLinkProvider - Eigenschaftstyp:
DocumentLinkOptions, wie folgt definiert:
export interface DocumentLinkOptions extends WorkDoneProgressOptions {
/**
* Document links have a resolve provider as well.
*/
resolveProvider?: boolean;
}
Registrierungsoptionen: DocumentLinkRegistrationOptions, wie folgt definiert:
export interface DocumentLinkRegistrationOptions extends
TextDocumentRegistrationOptions, DocumentLinkOptions {
}
Anfrage:
- Methode:
textDocument/documentLink - Parameter:
DocumentLinkParams, wie folgt definiert:
interface DocumentLinkParams extends WorkDoneProgressParams,
PartialResultParams {
/**
* The document to provide document links for.
*/
textDocument: TextDocumentIdentifier;
}
Antwort:
- Ergebnis:
DocumentLink[]|null.
/**
* 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?: URI;
/**
* 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;
}
- Teilergebnis:
DocumentLink[] - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Dokument-Link-Anfrage auftritt.
Dokument-Link-Auflösungsanfrage ()
Die Dokument-Link-Auflösungsanfrage wird vom Client an den Server gesendet, um das Ziel eines gegebenen Dokument-Links aufzulösen.
Anfrage:
- Methode:
documentLink/resolve - Parameter:
DocumentLink
Antwort:
- Ergebnis:
DocumentLink - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Dokument-Link-Auflösungsanfrage auftritt.
Hover Request ()
Die Hover-Anfrage wird vom Client an den Server gesendet, um Hover-Informationen an einer gegebenen Textdokumentposition anzufordern.
Client Capability:
- Eigenschaftsname (optional):
textDocument.hover - Eigenschaftstyp:
HoverClientCapabilitieswie folgt definiert
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-Fähigkeit:
- Eigenschaftsname (optional):
hoverProvider - Eigenschaftstyp:
boolean | HoverOptions, wobeiHoverOptionswie folgt definiert ist
export interface HoverOptions extends WorkDoneProgressOptions {
}
Registrierungsoptionen: HoverRegistrationOptions wie folgt definiert
export interface HoverRegistrationOptions
extends TextDocumentRegistrationOptions, HoverOptions {
}
Anfrage:
- Methode:
textDocument/hover - parameter:
HoverParamswie folgt definiert
export interface HoverParams extends TextDocumentPositionParams,
WorkDoneProgressParams {
}
Antwort:
- ergebnis:
Hover|nullwie folgt definiert
/**
* 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;
}
Wobei MarkedString wie folgt definiert ist
/**
* 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 };
- Fehler: Code und Nachricht werden gesetzt, wenn während der Hover-Anfrage eine Ausnahme auftritt.
Code-Lens-Anfrage ()
Die Code-Lens-Anfrage wird vom Client an den Server gesendet, um Code-Lenses für ein gegebenes Textdokument zu berechnen.
Client Capability:
- Eigenschaftsname (optional):
textDocument.codeLens - Eigenschaftstyp:
CodeLensClientCapabilities, wie folgt definiert:
export interface CodeLensClientCapabilities {
/**
* Whether code lens supports dynamic registration.
*/
dynamicRegistration?: boolean;
}
Server-Fähigkeit:
- Eigenschaftsname (optional):
codeLensProvider - Eigenschaftstyp:
CodeLensOptions, wie folgt definiert:
export interface CodeLensOptions extends WorkDoneProgressOptions {
/**
* Code lens has a resolve provider as well.
*/
resolveProvider?: boolean;
}
Registrierungsoptionen: CodeLensRegistrationOptions, wie folgt definiert:
export interface CodeLensRegistrationOptions extends
TextDocumentRegistrationOptions, CodeLensOptions {
}
Anfrage:
- Methode:
textDocument/codeLens - Parameter:
CodeLensParams, wie folgt definiert:
interface CodeLensParams extends WorkDoneProgressParams, PartialResultParams {
/**
* The document to request code lens for.
*/
textDocument: TextDocumentIdentifier;
}
Antwort:
- Ergebnis:
CodeLens[]|null, wie folgt definiert:
/**
* 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;
}
- Teilergebnis:
CodeLens[] - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Code-Lens-Anfrage auftritt.
Code-Lens-Auflösungsanfrage ()
Die Code-Lens-Auflösungsanfrage wird vom Client an den Server gesendet, um den Befehl für ein gegebenes Code-Lens-Element aufzulösen.
Anfrage:
- Methode:
codeLens/resolve - Parameter:
CodeLens
Antwort:
- Ergebnis:
CodeLens - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Code-Lens-Auflösungsanfrage auftritt.
Code-Lens-Aktualisierungsanfrage ()
Seit Version 3.16.0
Die Anfrage workspace/codeLens/refresh wird vom Server an den Client gesendet. Server können sie verwenden, um Clients aufzufordern, die aktuell in Editoren angezeigten Code-Lenses zu aktualisieren. Als Ergebnis sollte der Client den Server auffordern, die Code-Lenses für diese Editoren neu zu berechnen. Dies ist nützlich, wenn ein Server eine Konfigurationsänderung erkennt, die eine Neuberechnung aller Code-Lenses erfordert. Beachten Sie, dass der Client weiterhin die Freiheit hat, die Neuberechnung der Code-Lenses zu verzögern, wenn beispielsweise ein Editor derzeit nicht sichtbar ist.
Client Capability:
- Eigenschaftsname (optional):
workspace.codeLens - Eigenschaftstyp:
CodeLensWorkspaceClientCapabilities, wie folgt definiert:
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;
}
Anfrage:
- Methode:
workspace/codeLens/refresh - params: none
Antwort:
- result: void
- Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der `workspace/codeLens/refresh`-Anfrage auftritt.
Faltungsbereichsanfrage ()
Seit Version 3.10.0
Die Faltungsbereichsanfrage wird vom Client an den Server gesendet, um alle Faltungsbereiche in einem gegebenen Textdokument zurückzugeben.
Client Capability:
- Eigenschaftsname (optional):
textDocument.foldingRange - Eigenschaftstyp:
FoldingRangeClientCapabilities, wie folgt definiert:
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;
/**
* Specific options for the folding range kind.
*
* @since 3.17.0
*/
foldingRangeKind? : {
/**
* The folding range 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?: FoldingRangeKind[];
};
/**
* Specific options for the folding range.
* @since 3.17.0
*/
foldingRange?: {
/**
* If set, the client signals that it supports setting collapsedText on
* folding ranges to display custom labels instead of the default text.
*
* @since 3.17.0
*/
collapsedText?: boolean;
};
}
Server-Fähigkeit:
- Eigenschaftsname (optional):
foldingRangeProvider - Eigenschaftstyp:
boolean | FoldingRangeOptions | FoldingRangeRegistrationOptions, wobeiFoldingRangeOptionswie folgt definiert ist:
export interface FoldingRangeOptions extends WorkDoneProgressOptions {
}
Registrierungsoptionen: FoldingRangeRegistrationOptions, wie folgt definiert:
export interface FoldingRangeRegistrationOptions extends
TextDocumentRegistrationOptions, FoldingRangeOptions,
StaticRegistrationOptions {
}
Anfrage:
- Methode:
textDocument/foldingRange - Parameter:
FoldingRangeParams, wie folgt definiert:
export interface FoldingRangeParams extends WorkDoneProgressParams,
PartialResultParams {
/**
* The text document.
*/
textDocument: TextDocumentIdentifier;
}
Antwort:
- Ergebnis:
FoldingRange[] | null, wie folgt definiert:
/**
* A set of predefined range kinds.
*/
export namespace FoldingRangeKind {
/**
* Folding range for a comment
*/
export const Comment = 'comment';
/**
* Folding range for imports or includes
*/
export const Imports = 'imports';
/**
* Folding range for a region (e.g. `#region`)
*/
export const Region = 'region';
}
/**
* The type is a string since the value set is extensible
*/
export type FoldingRangeKind = string;
/**
* 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?: FoldingRangeKind;
/**
* The text that the client should show when the specified range is
* collapsed. If not defined or not supported by the client, a default
* will be chosen by the client.
*
* @since 3.17.0 - proposed
*/
collapsedText?: string;
}
- Teilergebnis:
FoldingRange[] - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der `textDocument/foldingRange`-Anfrage auftritt.
Auswahlbereichsanfrage ()
Seit Version 3.15.0
Die Auswahlbereichsanfrage wird vom Client an den Server gesendet, um vorgeschlagene Auswahlbereiche an einer oder mehreren gegebenen Positionen zurückzugeben. Ein Auswahlbereich ist ein Bereich um die Cursorposition, an dem der Benutzer möglicherweise interessiert ist, ihn auszuwählen.
Ein Auswahlbereich im Rückgabe-Array ist für die Position im bereitgestellten Parameter am selben Index bestimmt. Daher muss positions[i] in result[i].range enthalten sein. Um Ergebnisse zu ermöglichen, bei denen einige Positionen Auswahlbereiche haben und andere nicht, darf result[i].range der leere Bereich an positions[i] sein.
Typischerweise, aber nicht notwendigerweise, entsprechen Auswahlbereiche den Knoten des Syntaxbaums.
Client Capability:
- Eigenschaftsname (optional):
textDocument.selectionRange - Eigenschaftstyp:
SelectionRangeClientCapabilities, wie folgt definiert:
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-Fähigkeit:
- Eigenschaftsname (optional):
selectionRangeProvider - Eigenschaftstyp:
boolean | SelectionRangeOptions | SelectionRangeRegistrationOptions, wobeiSelectionRangeOptionswie folgt definiert ist:
export interface SelectionRangeOptions extends WorkDoneProgressOptions {
}
Registrierungsoptionen: SelectionRangeRegistrationOptions, wie folgt definiert:
export interface SelectionRangeRegistrationOptions extends
SelectionRangeOptions, TextDocumentRegistrationOptions,
StaticRegistrationOptions {
}
Anfrage:
- Methode:
textDocument/selectionRange - Parameter:
SelectionRangeParams, wie folgt definiert:
export interface SelectionRangeParams extends WorkDoneProgressParams,
PartialResultParams {
/**
* The text document.
*/
textDocument: TextDocumentIdentifier;
/**
* The positions inside the text document.
*/
positions: Position[];
}
Antwort:
- Ergebnis:
SelectionRange[] | null, wie folgt definiert:
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;
}
- Teilergebnis:
SelectionRange[] - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der `textDocument/selectionRange`-Anfrage auftritt.
Dokument-Symbole-Anfrage ()
Die Dokument-Symbole-Anfrage wird vom Client an den Server gesendet. Das zurückgegebene Ergebnis ist entweder
-
SymbolInformation[], eine flache Liste aller in einem gegebenen Textdokument gefundenen Symbole. Dann sollten weder der Standortbereich noch der Containername des Symbols verwendet werden, um eine Hierarchie abzuleiten. -
DocumentSymbol[], eine Hierarchie von Symbolen, die in einem gegebenen Textdokument gefunden wurden.
Server sollten, wann immer möglich, DocumentSymbol zurückgeben, da dies die reichhaltigere Datenstruktur ist.
Client Capability:
- Eigenschaftsname (optional):
textDocument.documentSymbol - Eigenschaftstyp:
DocumentSymbolClientCapabilities, wie folgt definiert:
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-Fähigkeit:
- Eigenschaftsname (optional):
documentSymbolProvider - Eigenschaftstyp:
boolean | DocumentSymbolOptions, wobeiDocumentSymbolOptionswie folgt definiert ist:
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;
}
Registrierungsoptionen: DocumentSymbolRegistrationOptions, wie folgt definiert:
export interface DocumentSymbolRegistrationOptions extends
TextDocumentRegistrationOptions, DocumentSymbolOptions {
}
Anfrage:
- Methode:
textDocument/documentSymbol - Parameter:
DocumentSymbolParams, wie folgt definiert:
export interface DocumentSymbolParams extends WorkDoneProgressParams,
PartialResultParams {
/**
* The text document.
*/
textDocument: TextDocumentIdentifier;
}
Antwort:
- Ergebnis:
DocumentSymbol[]|SymbolInformation[]|null, wie folgt definiert:
/**
* 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;
}
export type SymbolKind = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26;
/**
* 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;
/**
* 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 it 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[];
}
/**
* 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 an 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;
}
- Teilergebnis:
DocumentSymbol[]|SymbolInformation[].DocumentSymbol[]undSymbolInformation[]können nicht gemischt werden. Das bedeutet, dass der erste Block den Typ aller anderen Blöcke definiert. - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Dokument-Symbole-Anfrage auftritt.
Semantic Tokens ()
Seit Version 3.16.0
Die Anfrage wird vom Client an den Server gesendet, um semantische Token für eine gegebene Datei aufzulösen. Semantische Token werden verwendet, um einer Datei zusätzliche Farbinformationen hinzuzufügen, die von sprachspezifischen Symbolinformationen abhängen. Eine Anfrage für semantische Token erzeugt normalerweise ein großes Ergebnis. Das Protokoll unterstützt daher die Kodierung von Token mit Zahlen. Optional ist auch eine Unterstützung für Deltas verfügbar.
Allgemeine Konzepte
Token werden durch einen Token-Typ kombiniert mit n Token-Modifikatoren dargestellt. Ein Token-Typ ist etwas wie class oder function und Token-Modifikatoren sind wie static oder async. Das Protokoll definiert eine Reihe von Token-Typen und -Modifikatoren, aber Clients dürfen diese erweitern und die unterstützten Werte in der entsprechenden Client-Fähigkeit ankündigen. Die vordefinierten Werte sind:
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',
/**
* @since 3.17.0
*/
decorator = 'decorator'
}
export enum SemanticTokenModifiers {
declaration = 'declaration',
definition = 'definition',
readonly = 'readonly',
static = 'static',
deprecated = 'deprecated',
abstract = 'abstract',
async = 'async',
modification = 'modification',
documentation = 'documentation',
defaultLibrary = 'defaultLibrary'
}
Das Protokoll definiert eine zusätzliche Fähigkeit für das Token-Format, um zukünftige Erweiterungen des Formats zu ermöglichen. Das einzige derzeit spezifizierte Format ist relative, das angibt, dass die Token mit relativen Positionen beschrieben werden (siehe Integer-Kodierung für Token unten).
export namespace TokenFormat {
export const Relative: 'relative' = 'relative';
}
export type TokenFormat = 'relative';
Integer Encoding für Token
Auf der Ebene der Fähigkeiten werden Typen und Modifikatoren durch Strings definiert. Die eigentliche Kodierung erfolgt jedoch mit Zahlen. Der Server muss dem Client daher mitteilen, welche Zahlen er für welche Typen und Modifikatoren verwendet. Dies geschieht über eine Legende, die wie folgt definiert ist:
export interface SemanticTokensLegend {
/**
* The token types a server uses.
*/
tokenTypes: string[];
/**
* The token modifiers a server uses.
*/
tokenModifiers: string[];
}
Token-Typen werden nach Index gesucht, sodass ein Wert von tokenType 1 tokenTypes[1] bedeutet. Da ein Token-Typ n Modifikatoren haben kann, können mehrere Token-Modifikatoren durch bitweise Flags gesetzt werden. Ein Wert von tokenModifier 3 wird zuerst als Binärzahl 0b00000011 betrachtet, was [tokenModifiers[0], tokenModifiers[1]] bedeutet, da die Bits 0 und 1 gesetzt sind.
Es gibt verschiedene Möglichkeiten, wie die Position eines Tokens in einer Datei ausgedrückt werden kann. Absolute Positionen oder relative Positionen. Das Protokoll für das Token-Format relative verwendet relative Positionen, da die meisten Token im Verhältnis zueinander stabil bleiben, wenn Bearbeitungen an einer Datei vorgenommen werden. Dies vereinfacht die Berechnung eines Deltas, wenn ein Server dies unterstützt. Jedes Token wird also mit 5 ganzen Zahlen dargestellt. Ein bestimmtes Token i in der Datei besteht aus folgenden Array-Indizes:
- Index
5*i-deltaLine: Zeilennummer des Tokens, relativ zum Beginn des vorherigen Tokens - Index
5*i+1-deltaStart: Startzeichen des Tokens, relativ zum Beginn des vorherigen Tokens (relativ zu 0 oder zum Start des vorherigen Tokens, wenn sie sich in derselben Zeile befinden) - at index
5*i+2-length: die Länge des Tokens. - at index
5*i+3-tokenType: wird inSemanticTokensLegend.tokenTypesnachgeschlagen. Wir bitten derzeit, dasstokenType< 65536 ist. - Index
5*i+4-tokenModifiers: jedes gesetzte Bit wird inSemanticTokensLegend.tokenModifiersnachgeschlagen
Die Werte deltaStart und length müssen mit der Kodierung kodiert werden, auf die sich Client und Server während der initialize-Anfrage geeinigt haben (siehe auch TextDocuments). Ob ein Token mehrere Zeilen umfassen kann, wird durch die Client-Fähigkeit multilineTokenSupport bestimmt. Wenn mehrzeilige Token nicht unterstützt werden und die Länge eines Tokens über das Ende der Zeile hinausgeht, sollte dies so behandelt werden, als würde das Token am Ende der Zeile enden und nicht in die nächste Zeile umbrechen.
Die Client-Capability overlappingTokenSupport definiert, ob sich Token überlappen können.
Betrachten wir ein konkretes Beispiel mit einzeiligen Token ohne Überlappungen, um eine Datei mit 3 Token in einem Zahlenarray zu kodieren. Wir beginnen mit absoluten Positionen, um zu zeigen, wie sie leicht in relative Positionen umgewandelt werden können.
{ 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: [] }
Zunächst muss eine Legende erstellt werden. Diese Legende muss bei der Registrierung im Voraus bereitgestellt werden und alle möglichen Token-Typen und -Modifikatoren erfassen. Für das Beispiel verwenden wir diese Legende:
{
tokenTypes: ['property', 'type', 'class'],
tokenModifiers: ['private', 'static']
}
Der erste Transformationsschritt besteht darin, tokenType und tokenModifiers mithilfe der Legende als Ganzzahlen zu kodieren. Wie gesagt, Token-Typen werden nach Index nachgeschlagen, sodass ein tokenType-Wert von 1 tokenTypes[1] bedeutet. Mehrere Token-Modifikatoren können durch Verwendung von Bit-Flags gesetzt werden, sodass ein tokenModifier-Wert von 3 zuerst als Binärzahl 0b00000011 betrachtet wird, was [tokenModifiers[0], tokenModifiers[1]] bedeutet, da die Bits 0 und 1 gesetzt sind. Mithilfe dieser Legende sind die Token nun
{ 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 }
Der nächste Schritt besteht darin, jedes Token relativ zum vorherigen Token in der Datei darzustellen. In diesem Fall befindet sich das zweite Token auf derselben Zeile wie das erste Token, sodass der startChar des zweiten Tokens relativ zum startChar des ersten Tokens gemacht wird, also 10 - 5. Das dritte Token befindet sich auf einer anderen Zeile als das zweite Token, daher wird der startChar des dritten Tokens nicht geändert
{ 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 }
Schließlich besteht der letzte Schritt darin, jedes der 5 Felder für ein Token in einem einzigen Array zusammenzufassen, was eine speichereffiziente Darstellung ist
// 1st token, 2nd token, 3rd token
[ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ]
Nehmen wir nun an, der Benutzer tippt eine neue leere Zeile am Anfang der Datei ein, was zu den folgenden Token in der Datei führt
{ 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: [] }
Die Ausführung derselben Transformationen wie oben führt zu folgendem Zahlenarray
// 1st token, 2nd token, 3rd token
[ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0]
Die Differenz wird nun in diesen Zahlenarrays ausgedrückt, ohne jegliche Interpretation dessen, was diese Zahlen bedeuten. Dies ist vergleichbar mit den Textdokument-Änderungen, die vom Server an den Client gesendet werden, um den Inhalt einer Datei zu ändern. Diese sind zeichenbasiert und machen keine Annahmen über die Bedeutung der Zeichen. Also kann [ 2,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0 ] in [ 3,5,3,0,3, 0,5,4,1,0, 3,2,7,2,0] umgewandelt werden, indem die folgende Bearbeitungsbeschreibung verwendet wird: { start: 0, deleteCount: 1, data: [3] }, die dem Client mitteilt, die erste Zahl (z. B. 2) im Array einfach durch 3 zu ersetzen.
Semantische Token-Bearbeitungen verhalten sich konzeptionell wie Textbearbeitungen an Dokumenten: Wenn eine Bearbeitungsbeschreibung aus n Bearbeitungen besteht, basieren alle n Bearbeitungen auf demselben Zustand Sm des Zahlenarrays. Sie verschieben das Zahlenarray vom Zustand Sm zu Sm+1. Ein Client, der die Bearbeitungen anwendet, darf nicht davon ausgehen, dass sie sortiert sind. Ein einfacher Algorithmus zur Anwendung auf das Zahlenarray besteht darin, die Bearbeitungen zu sortieren und sie vom Ende zum Anfang des Zahlenarrays anzuwenden.
Client Capability:
Die folgenden Client-Capabilities werden für semantische Token-Anfragen definiert, die vom Client an den Server gesendet werden
- property name (optional):
textDocument.semanticTokens - property type:
SemanticTokensClientCapabilitiesdefiniert wie folgt
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-Fähigkeit:
Die folgenden Server-Capabilities werden für semantische Token definiert
- property name (optional):
semanticTokensProvider - property type:
SemanticTokensOptions | SemanticTokensRegistrationOptionswobeiSemanticTokensOptionswie folgt definiert ist
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 definiert wie folgt
export interface SemanticTokensRegistrationOptions extends
TextDocumentRegistrationOptions, SemanticTokensOptions,
StaticRegistrationOptions {
}
Da die Registrierungsoption Bereiche, vollständige und Delta-Anfragen abdeckt, ist die Methode zur Registrierung für semantische Token-Anfragen textDocument/semanticTokens und nicht eine der unten beschriebenen spezifischen Methoden.
Anfordern semantischer Token für eine ganze Datei
Anfrage:
- method:
textDocument/semanticTokens/full - params:
SemanticTokensParamsdefiniert wie folgt
export interface SemanticTokensParams extends WorkDoneProgressParams,
PartialResultParams {
/**
* The text document.
*/
textDocument: TextDocumentIdentifier;
}
Antwort:
- result:
SemanticTokens | nullwobeiSemanticTokenswie folgt definiert ist
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:
SemanticTokensPartialResultdefiniert wie folgt
export interface SemanticTokensPartialResult {
data: uinteger[];
}
- error: code und message gesetzt im Falle eines Exceptions während der ‘textDocument/semanticTokens/full’ Anfrage
Anfordern eines semantischen Token-Deltas für eine ganze Datei
Anfrage:
- method:
textDocument/semanticTokens/full/delta - params:
SemanticTokensDeltaParamsdefiniert wie folgt
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;
}
Antwort:
- result:
SemanticTokens | SemanticTokensDelta | nullwobeiSemanticTokensDeltawie folgt definiert ist
export interface SemanticTokensDelta {
readonly resultId?: string;
/**
* The semantic token edits to transform a previous result into a new
* result.
*/
edits: SemanticTokensEdit[];
}
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:
SemanticTokensDeltaPartialResultdefiniert wie folgt
export interface SemanticTokensDeltaPartialResult {
edits: SemanticTokensEdit[];
}
- error: code und message gesetzt im Falle eines Exceptions während der ‘textDocument/semanticTokens/full/delta’ Anfrage
Anfordern semantischer Token für einen Bereich
Es gibt zwei Anwendungsfälle, bei denen es vorteilhaft sein kann, semantische Token nur für einen sichtbaren Bereich zu berechnen
- für schnellere Darstellung der Token in der Benutzeroberfläche, wenn ein Benutzer eine Datei öffnet. In diesen Anwendungsfällen sollten Server auch die Anfrage
textDocument/semanticTokens/fullimplementieren, um ein flackerfreies Scrollen und semantische Hervorhebung einer Minimap zu ermöglichen. - Wenn die Berechnung semantischer Token für ein vollständiges Dokument zu teuer ist, können Server nur einen Bereichsabruf bereitstellen. In diesem Fall kann es sein, dass der Client eine Minimap nicht korrekt rendert oder sogar beschließt, überhaupt keine semantischen Token anzuzeigen.
Ein Server darf die semantischen Token für einen größeren Bereich als vom Client angefordert berechnen. Wenn der Server dies tut, müssen die semantischen Token für den größeren Bereich vollständig und korrekt sein. Wenn ein Token am Anfang oder Ende nur teilweise mit dem angeforderten Bereich überlappt, sollte der Server diese Token in die Antwort aufnehmen.
Anfrage:
- method:
textDocument/semanticTokens/range - params:
SemanticTokensRangeParamsdefiniert wie folgt
export interface SemanticTokensRangeParams extends WorkDoneProgressParams,
PartialResultParams {
/**
* The text document.
*/
textDocument: TextDocumentIdentifier;
/**
* The range the semantic tokens are requested for.
*/
range: Range;
}
Antwort:
- result:
SemanticTokens | null - partial result:
SemanticTokensPartialResult - error: code und message gesetzt im Falle eines Exceptions während der ‘textDocument/semanticTokens/range’ Anfrage
Anfordern einer Aktualisierung aller semantischen Token
Die Anfrage workspace/semanticTokens/refresh wird vom Server an den Client gesendet. Server können sie verwenden, um Clients aufzufordern, die Editoren zu aktualisieren, für die dieser Server semantische Token bereitstellt. Als Ergebnis sollte der Client den Server auffordern, die semantischen Token für diese Editoren neu zu berechnen. Dies ist nützlich, wenn ein Server eine projektweite Konfigurationsänderung erkennt, die eine Neuberechnung aller semantischen Token erfordert. Beachten Sie, dass der Client weiterhin die Freiheit hat, die Neuberechnung der semantischen Token zu verzögern, wenn beispielsweise ein Editor derzeit nicht sichtbar ist.
Client Capability:
- property name (optional):
workspace.semanticTokens - property type:
SemanticTokensWorkspaceClientCapabilitiesdefiniert wie folgt
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;
}
Anfrage:
- method:
workspace/semanticTokens/refresh - params: none
Antwort:
- result: void
- error: code und message gesetzt im Falle eines Exceptions während der ‘workspace/semanticTokens/refresh’ Anfrage
Anfrage zu Inlay-Hinweisen ()
Seit Version 3.17.0
Die Anfrage zu Inlay-Hinweisen wird vom Client an den Server gesendet, um Inlay-Hinweise für ein gegebenes Tupel [Textdokument, Bereich] zu berechnen, die im Editor direkt neben anderem Text gerendert werden können.
Client Capability:
- Eigenschaftsname (optional):
textDocument.inlayHint - Eigenschaftstyp:
InlayHintClientCapabilitieswie folgt definiert
/**
* Inlay hint client capabilities.
*
* @since 3.17.0
*/
export interface InlayHintClientCapabilities {
/**
* Whether inlay hints support dynamic registration.
*/
dynamicRegistration?: boolean;
/**
* Indicates which properties a client can resolve lazily on an inlay
* hint.
*/
resolveSupport?: {
/**
* The properties that a client can resolve lazily.
*/
properties: string[];
};
}
Server-Fähigkeit:
- Eigenschaftsname (optional):
inlayHintProvider - Eigenschaftstyp:
InlayHintOptionswie folgt definiert
/**
* Inlay hint options used during static registration.
*
* @since 3.17.0
*/
export interface InlayHintOptions extends WorkDoneProgressOptions {
/**
* The server provides support to resolve additional
* information for an inlay hint item.
*/
resolveProvider?: boolean;
}
Registrierungsoptionen: InlayHintRegistrationOptions wie folgt definiert
/**
* Inlay hint options used during static or dynamic registration.
*
* @since 3.17.0
*/
export interface InlayHintRegistrationOptions extends InlayHintOptions,
TextDocumentRegistrationOptions, StaticRegistrationOptions {
}
Anfrage:
- Methode:
textDocument/inlayHint - Parameter:
InlayHintParamswie folgt definiert
/**
* A parameter literal used in inlay hint requests.
*
* @since 3.17.0
*/
export interface InlayHintParams extends WorkDoneProgressParams {
/**
* The text document.
*/
textDocument: TextDocumentIdentifier;
/**
* The visible document range for which inlay hints should be computed.
*/
range: Range;
}
Antwort:
- Ergebnis:
InlayHint[]|nullwie folgt definiert
/**
* Inlay hint information.
*
* @since 3.17.0
*/
export interface InlayHint {
/**
* The position of this hint.
*
* If multiple hints have the same position, they will be shown in the order
* they appear in the response.
*/
position: Position;
/**
* The label of this hint. A human readable string or an array of
* InlayHintLabelPart label parts.
*
* *Note* that neither the string nor the label part can be empty.
*/
label: string | InlayHintLabelPart[];
/**
* The kind of this hint. Can be omitted in which case the client
* should fall back to a reasonable default.
*/
kind?: InlayHintKind;
/**
* Optional text edits that are performed when accepting this inlay hint.
*
* *Note* that edits are expected to change the document so that the inlay
* hint (or its nearest variant) is now part of the document and the inlay
* hint itself is now obsolete.
*
* Depending on the client capability `inlayHint.resolveSupport` clients
* might resolve this property late using the resolve request.
*/
textEdits?: TextEdit[];
/**
* The tooltip text when you hover over this item.
*
* Depending on the client capability `inlayHint.resolveSupport` clients
* might resolve this property late using the resolve request.
*/
tooltip?: string | MarkupContent;
/**
* Render padding before the hint.
*
* Note: Padding should use the editor's background color, not the
* background color of the hint itself. That means padding can be used
* to visually align/separate an inlay hint.
*/
paddingLeft?: boolean;
/**
* Render padding after the hint.
*
* Note: Padding should use the editor's background color, not the
* background color of the hint itself. That means padding can be used
* to visually align/separate an inlay hint.
*/
paddingRight?: boolean;
/**
* A data entry field that is preserved on an inlay hint between
* a `textDocument/inlayHint` and a `inlayHint/resolve` request.
*/
data?: LSPAny;
}
/**
* An inlay hint label part allows for interactive and composite labels
* of inlay hints.
*
* @since 3.17.0
*/
export interface InlayHintLabelPart {
/**
* The value of this label part.
*/
value: string;
/**
* The tooltip text when you hover over this label part. Depending on
* the client capability `inlayHint.resolveSupport` clients might resolve
* this property late using the resolve request.
*/
tooltip?: string | MarkupContent;
/**
* An optional source code location that represents this
* label part.
*
* The editor will use this location for the hover and for code navigation
* features: This part will become a clickable link that resolves to the
* definition of the symbol at the given location (not necessarily the
* location itself), it shows the hover that shows at the given location,
* and it shows a context menu with further code navigation commands.
*
* Depending on the client capability `inlayHint.resolveSupport` clients
* might resolve this property late using the resolve request.
*/
location?: Location;
/**
* An optional command for this label part.
*
* Depending on the client capability `inlayHint.resolveSupport` clients
* might resolve this property late using the resolve request.
*/
command?: Command;
}
/**
* Inlay hint kinds.
*
* @since 3.17.0
*/
export namespace InlayHintKind {
/**
* An inlay hint that for a type annotation.
*/
export const Type = 1;
/**
* An inlay hint that is for a parameter.
*/
export const Parameter = 2;
}
export type InlayHintKind = 1 | 2;
- Fehler: Code und Nachricht werden gesetzt, wenn während der Anfrage zu Inlay-Hinweisen eine Ausnahme auftritt.
Anfrage zur Auflösung von Inlay-Hinweisen ()
Seit Version 3.17.0
Die Anfrage wird vom Client an den Server gesendet, um zusätzliche Informationen für einen gegebenen Inlay-Hinweis aufzulösen. Dies wird normalerweise verwendet, um die Eigenschaften tooltip, location oder command eines Inlay-Hinweis-Labels zu berechnen, um deren unnötige Berechnung während der Anfrage textDocument/inlayHint zu vermeiden.
Betrachten Sie, dass der Client die Eigenschaft label.location als eine Eigenschaft ankündigt, die mit der Client-Fähigkeit verzögert aufgelöst werden kann
textDocument.inlayHint.resolveSupport = { properties: ['label.location'] };
dann muss ein Inlay-Hinweis mit einem Label-Teil ohne Standort über die Anfrage inlayHint/resolve aufgelöst werden, bevor er verwendet werden kann.
Client Capability:
- Eigenschaftsname (optional):
textDocument.inlayHint.resolveSupport - Eigenschaftstyp:
{ properties: string[]; }
Anfrage:
- Methode:
inlayHint/resolve - Parameter:
InlayHint
Antwort:
- Ergebnis:
InlayHint - Fehler: Code und Nachricht werden gesetzt, wenn während der Vervollständigungsauflösungsanfrage eine Ausnahme auftritt.
Anfrage zur Aktualisierung von Inlay-Hinweisen ()
Seit Version 3.17.0
Die Anfrage workspace/inlayHint/refresh wird vom Server an den Client gesendet. Server können sie verwenden, um Clients aufzufordern, die aktuell in Editoren angezeigten Inlay-Hinweise zu aktualisieren. Als Ergebnis sollte der Client den Server auffordern, die Inlay-Hinweise für diese Editoren neu zu berechnen. Dies ist nützlich, wenn ein Server eine Konfigurationsänderung erkennt, die eine Neuberechnung aller Inlay-Hinweise erfordert. Beachten Sie, dass der Client weiterhin die Freiheit hat, die Neuberechnung der Inlay-Hinweise zu verzögern, wenn beispielsweise ein Editor derzeit nicht sichtbar ist.
Client Capability:
- Eigenschaftsname (optional):
workspace.inlayHint - Eigenschaftstyp:
InlayHintWorkspaceClientCapabilitieswie folgt definiert
/**
* Client workspace capabilities specific to inlay hints.
*
* @since 3.17.0
*/
export interface InlayHintWorkspaceClientCapabilities {
/**
* 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
* inlay hints currently shown. It should be used with absolute care and
* is useful for situation where a server for example detects a project wide
* change that requires such a calculation.
*/
refreshSupport?: boolean;
}
Anfrage:
- Methode:
workspace/inlayHint/refresh - params: none
Antwort:
- result: void
- Fehler: Code und Nachricht werden gesetzt, wenn während der Anfrage ‘workspace/inlayHint/refresh’ eine Ausnahme auftritt.
Anfrage zu Inline-Werten ()
Seit Version 3.17.0
Die Anfrage zu Inline-Werten wird vom Client an den Server gesendet, um Inline-Werte für ein gegebenes Textdokument zu berechnen, die am Ende von Zeilen im Editor gerendert werden können.
Client Capability:
- Eigenschaftsname (optional):
textDocument.inlineValue - Eigenschaftstyp:
InlineValueClientCapabilitieswie folgt definiert
/**
* Client capabilities specific to inline values.
*
* @since 3.17.0
*/
export interface InlineValueClientCapabilities {
/**
* Whether implementation supports dynamic registration for inline
* value providers.
*/
dynamicRegistration?: boolean;
}
Server-Fähigkeit:
- Eigenschaftsname (optional):
inlineValueProvider - Eigenschaftstyp:
InlineValueOptionswie folgt definiert
/**
* Inline value options used during static registration.
*
* @since 3.17.0
*/
export interface InlineValueOptions extends WorkDoneProgressOptions {
}
Registrierungsoptionen: InlineValueRegistrationOptions wie folgt definiert
/**
* Inline value options used during static or dynamic registration.
*
* @since 3.17.0
*/
export interface InlineValueRegistrationOptions extends InlineValueOptions,
TextDocumentRegistrationOptions, StaticRegistrationOptions {
}
Anfrage:
- Methode:
textDocument/inlineValue - Parameter:
InlineValueParamswie folgt definiert
/**
* A parameter literal used in inline value requests.
*
* @since 3.17.0
*/
export interface InlineValueParams extends WorkDoneProgressParams {
/**
* The text document.
*/
textDocument: TextDocumentIdentifier;
/**
* The document range for which inline values should be computed.
*/
range: Range;
/**
* Additional information about the context in which inline values were
* requested.
*/
context: InlineValueContext;
}
/**
* @since 3.17.0
*/
export interface InlineValueContext {
/**
* The stack frame (as a DAP Id) where the execution has stopped.
*/
frameId: integer;
/**
* The document range where execution has stopped.
* Typically the end position of the range denotes the line where the
* inline values are shown.
*/
stoppedLocation: Range;
}
Antwort:
- Ergebnis:
InlineValue[]|nullwie folgt definiert
/**
* Provide inline value as text.
*
* @since 3.17.0
*/
export interface InlineValueText {
/**
* The document range for which the inline value applies.
*/
range: Range;
/**
* The text of the inline value.
*/
text: string;
}
/**
* Provide inline value through a variable lookup.
*
* If only a range is specified, the variable name will be extracted from
* the underlying document.
*
* An optional variable name can be used to override the extracted name.
*
* @since 3.17.0
*/
export interface InlineValueVariableLookup {
/**
* The document range for which the inline value applies.
* The range is used to extract the variable name from the underlying
* document.
*/
range: Range;
/**
* If specified the name of the variable to look up.
*/
variableName?: string;
/**
* How to perform the lookup.
*/
caseSensitiveLookup: boolean;
}
/**
* Provide an inline value through an expression evaluation.
*
* If only a range is specified, the expression will be extracted from the
* underlying document.
*
* An optional expression can be used to override the extracted expression.
*
* @since 3.17.0
*/
export interface InlineValueEvaluatableExpression {
/**
* The document range for which the inline value applies.
* The range is used to extract the evaluatable expression from the
* underlying document.
*/
range: Range;
/**
* If specified the expression overrides the extracted expression.
*/
expression?: string;
}
/**
* Inline value information can be provided by different means:
* - directly as a text value (class InlineValueText).
* - as a name to use for a variable lookup (class InlineValueVariableLookup)
* - as an evaluatable expression (class InlineValueEvaluatableExpression)
* The InlineValue types combines all inline value types into one type.
*
* @since 3.17.0
*/
export type InlineValue = InlineValueText | InlineValueVariableLookup
| InlineValueEvaluatableExpression;
- Fehler: Code und Nachricht werden gesetzt, wenn während der Anfrage zu Inline-Werten eine Ausnahme auftritt.
Anfrage zur Aktualisierung von Inline-Werten ()
Seit Version 3.17.0
Die Anfrage workspace/inlineValue/refresh wird vom Server an den Client gesendet. Server können sie verwenden, um Clients aufzufordern, die aktuell in Editoren angezeigten Inline-Werte zu aktualisieren. Als Ergebnis sollte der Client den Server auffordern, die Inline-Werte für diese Editoren neu zu berechnen. Dies ist nützlich, wenn ein Server eine Konfigurationsänderung erkennt, die eine Neuberechnung aller Inline-Werte erfordert. Beachten Sie, dass der Client weiterhin die Freiheit hat, die Neuberechnung der Inline-Werte zu verzögern, wenn beispielsweise ein Editor derzeit nicht sichtbar ist.
Client Capability:
- Eigenschaftsname (optional):
workspace.inlineValue - Eigenschaftstyp:
InlineValueWorkspaceClientCapabilitieswie folgt definiert
/**
* Client workspace capabilities specific to inline values.
*
* @since 3.17.0
*/
export interface InlineValueWorkspaceClientCapabilities {
/**
* 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
* inline values 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;
}
Anfrage:
- Methode:
workspace/inlineValue/refresh - params: none
Antwort:
- result: void
- Fehler: Code und Nachricht werden gesetzt, wenn während der Anfrage ‘workspace/inlineValue/refresh’ eine Ausnahme auftritt.
Monikers ()
Seit Version 3.16.0
Das Language Server Index Format (LSIF) hat das Konzept von Symbol-Monikern eingeführt, um Symbole über verschiedene Indizes hinweg zu verknüpfen. Diese Anfrage fügt die Fähigkeit für LSP-Server-Implementierungen hinzu, dieselbe Symbol-Moniker-Information für eine Textdokumentposition bereitzustellen. Clients können diese Methode verwenden, um den Moniker an der aktuellen Position in einer bearbeiteten Datei zu erhalten und weitere Code-Navigationsabfragen in anderen Diensten durchzuführen, die LSIF-Indizes verwenden und Symbole verknüpfen.
Die textDocument/moniker-Anfrage wird vom Client an den Server gesendet, um die Symbol-Moniker für eine gegebene Textdokumentposition zu erhalten. Ein Array von Moniker-Typen wird als Antwort zurückgegeben, um mögliche Moniker an der gegebenen Stelle anzuzeigen. Wenn keine Moniker berechnet werden können, sollte ein leeres Array oder null zurückgegeben werden.
Client Capabilities:
- property name (optional):
textDocument.moniker - property type:
MonikerClientCapabilitiesdefiniert wie folgt
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-Fähigkeit:
- property name (optional):
monikerProvider - property type:
boolean | MonikerOptions | MonikerRegistrationOptionsist wie folgt definiert
export interface MonikerOptions extends WorkDoneProgressOptions {
}
Registration Options: MonikerRegistrationOptions definiert wie folgt
export interface MonikerRegistrationOptions extends
TextDocumentRegistrationOptions, MonikerOptions {
}
Anfrage:
- method:
textDocument/moniker - params:
MonikerParamsdefiniert wie folgt
export interface MonikerParams extends TextDocumentPositionParams,
WorkDoneProgressParams, PartialResultParams {
}
Antwort:
- result:
Moniker[] | null - partial result:
Moniker[] - error: code und message gesetzt im Falle eines Exceptions während der ‘textDocument/moniker’ Anfrage
Moniker ist wie folgt definiert
/**
* 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'
}
/**
* 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'
}
/**
* 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;
}
Hinweise
Server-Implementierungen dieser Methode sollten sicherstellen, dass die Moniker-Berechnung mit der entsprechenden LSIF-Implementierung übereinstimmt, um sicherzustellen, dass Symbole über IDE-Sitzungen und LSIF-Indizes hinweg korrekt zugeordnet werden können.
Completion Request ()
Die Vervollständigungsanfrage wird vom Client an den Server gesendet, um Vervollständigungselemente an einer gegebenen Cursorposition zu berechnen. Vervollständigungselemente werden in der IntelliSense-Benutzeroberfläche angezeigt. Wenn die Berechnung vollständiger Vervollständigungselemente teuer ist, können Server zusätzlich einen Handler für die Anfrage zur Auflösung von Vervollständigungselementen ('completionItem/resolve') bereitstellen. Diese Anfrage wird gesendet, wenn ein Vervollständigungselement in der Benutzeroberfläche ausgewählt wird. Ein typischer Anwendungsfall ist beispielsweise: Die Anfrage textDocument/completion füllt die Eigenschaft documentation für zurückgegebene Vervollständigungselemente nicht aus, da ihre Berechnung teuer ist. Wenn das Element in der Benutzeroberfläche ausgewählt wird, wird eine Anfrage 'completionItem/resolve' mit dem ausgewählten Vervollständigungselement als Parameter gesendet. Das zurückgegebene Vervollständigungselement sollte die Eigenschaft documentation ausgefüllt haben. Standardmäßig kann die Anfrage nur die Berechnung der Eigenschaften detail und documentation verzögern. Seit 3.16.0 kann der Client signalisieren, dass er weitere Eigenschaften verzögert auflösen kann. Dies geschieht über die Client-Fähigkeit completionItem#resolveSupport, die alle Eigenschaften auflistet, die während einer Anfrage 'completionItem/resolve' ausgefüllt werden können. Alle anderen Eigenschaften (normalerweise sortText, filterText, insertText und textEdit) müssen in der Antwort auf textDocument/completion bereitgestellt und dürfen während der Auflösung nicht geändert werden.
Das Language Server Protocol verwendet das folgende Modell für Vervollständigungen:
- um Konsistenz zwischen Sprachen zu erreichen und unterschiedliche Clients zu berücksichtigen, ist normalerweise der Client für das Filtern und Sortieren zuständig. Dies hat auch den Vorteil, dass der Client mit verschiedenen Filter- und Sortiermodellen experimentieren kann. Server können jedoch unterschiedliche Verhaltensweisen erzwingen, indem sie einen
filterText/sortTextsetzen. - Für die Geschwindigkeit sollten Clients eine bereits empfangene Vervollständigungsliste filtern können, wenn der Benutzer weiter tippt. Server können dies mit einer
CompletionListablehnen und sie alsisIncompletemarkieren.
Ein Vervollständigungselement bietet zusätzliche Möglichkeiten, das Filtern und Sortieren zu beeinflussen. Dies wird ausgedrückt, indem entweder ein CompletionItem mit einem insertText oder einem textEdit erstellt wird. Die beiden Modi unterscheiden sich wie folgt:
-
Das Vervollständigungselement bietet einen insertText / label ohne textEdit: im Modell sollte der Client gegen das filtern, was der Benutzer bereits mit den Wortgrenzenregeln der Sprache (z. B. Auflösung des Wortes unter der Cursorposition) eingegeben hat. Der Grund für diesen Modus ist, dass es für einen Server sehr einfach ist, eine grundlegende Vervollständigungsliste zu implementieren und sie auf dem Client filtern zu lassen.
-
Vervollständigungselement mit Textbearbeitungen: In diesem Modus teilt der Server dem Client mit, dass er tatsächlich weiß, was er tut. Wenn Sie ein Vervollständigungselement mit einer Textbearbeitung an der aktuellen Cursorposition erstellen, findet keine Wortraterei statt und es sollte keine automatische Filterung (wie bei einem
insertText) erfolgen. Dieser Modus kann mit einem Sortiertext und einem Filtertext kombiniert werden, um zwei Dinge anzupassen. Wenn die Textbearbeitung eine Ersetzungsbearbeitung ist, bezeichnet der Bereich das Wort, das für die Filterung verwendet wird. Wenn die Ersetzung den Text ändert, ist es höchstwahrscheinlich sinnvoll, einen Filtertext anzugeben.
Client Capability:
- Eigenschaftsname (optional):
textDocument.completion - Eigenschaftstyp:
CompletionClientCapabilitieswie folgt definiert
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
*/
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
*/
insertTextMode?: InsertTextMode;
/**
* The client supports the following `CompletionList` specific
* capabilities.
*
* @since 3.17.0
*/
completionList?: {
/**
* The client supports 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
*/
itemDefaults?: string[];
}
}
Server-Fähigkeit:
- Eigenschaftsname (optional):
completionProvider - Eigenschaftstyp:
CompletionOptionswie folgt definiert
/**
* Completion options.
*/
export interface CompletionOptions extends WorkDoneProgressOptions {
/**
* The additional characters, beyond the defaults provided by the client (typically
* [a-zA-Z]), that should automatically trigger a completion request. For example
* `.` in JavaScript represents the beginning of an object property or method and is
* thus a good candidate for triggering a completion request.
*
* Most tools trigger a 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.
*/
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
*/
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
*/
labelDetailsSupport?: boolean;
}
}
Registrierungsoptionen: CompletionRegistrationOptions Optionen wie folgt definiert
export interface CompletionRegistrationOptions
extends TextDocumentRegistrationOptions, CompletionOptions {
}
Anfrage:
- Methode:
textDocument/completion - parameter:
CompletionParamswie folgt definiert
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;
}
/**
* 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;
/**
* 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;
}
Antwort:
- ergebnis:
CompletionItem[]|CompletionList|null. Wenn einCompletionItem[]bereitgestellt wird, wird es als vollständig interpretiert. Es ist also dasselbe wie{ isIncomplete: false, items }
/**
* 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
*/
itemDefaults?: {
/**
* A default commit character set.
*
* @since 3.17.0
*/
commitCharacters?: string[];
/**
* A default edit range
*
* @since 3.17.0
*/
editRange?: Range | {
insert: Range;
replace: Range;
};
/**
* A default insert text format
*
* @since 3.17.0
*/
insertTextFormat?: InsertTextFormat;
/**
* A default insert text mode
*
* @since 3.17.0
*/
insertTextMode?: InsertTextMode;
/**
* A default data value.
*
* @since 3.17.0
*/
data?: LSPAny;
}
/**
* The completion items.
*/
items: CompletionItem[];
}
/**
* 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;
/**
* 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;
/**
* 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;
}
/**
* 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><cursor><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;
/**
* Additional details for a completion item label.
*
* @since 3.17.0
*/
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;
}
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
*/
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 omitted 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 omitted 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 omitted 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<cursor position>` 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;
/**
* The edit text used if the completion item is part of a CompletionList and
* CompletionList defines an item default for the text edit range.
*
* Clients will only honor this property if they opt into completion list
* item defaults using the capability `completionList.itemDefaults`.
*
* If not provided and a list's default range is provided the label
* property is used as a text.
*
* @since 3.17.0
*/
textEditText?: string;
/**
* 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;
}
/**
* 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;
}
export type CompletionItemKind = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25;
- Teilergebnis:
CompletionItem[]oderCompletionListgefolgt vonCompletionItem[]. Wenn das erste bereitgestellte Ergebnis einCompletionList-Typ ist, werden nachfolgende Teilergebnisse vonCompletionItem[]zuritems-Eigenschaft derCompletionListhinzugefügt. - Fehler: Code und Nachricht werden gesetzt, wenn während der Vervollständigungsanfrage eine Ausnahme auftritt.
Vervollständigungselemente unterstützen Snippets (siehe InsertTextFormat.Snippet). Das Snippet-Format ist wie folgt:
Snippet-Syntax
Der body eines Snippets kann spezielle Konstrukte verwenden, um Cursors und den eingefügten Text zu steuern. Die folgenden Funktionen und ihre Syntax werden unterstützt:
Tab-Stopps
Mit Tab-Stopps können Sie den Editor-Cursor innerhalb eines Snippets bewegen. Verwenden Sie $1, $2, um Cursorpositionen anzugeben. Die Zahl ist die Reihenfolge, in der die Tab-Stopps besucht werden, während $0 die endgültige Cursorposition bezeichnet. Mehrere Tab-Stopps sind verknüpft und werden synchron aktualisiert.
Platzhalter
Platzhalter sind Tab-Stopps mit Werten, wie ${1:foo}. Der Platzhaltertext wird eingefügt und ausgewählt, sodass er leicht geändert werden kann. Platzhalter können verschachtelt sein, wie ${1:another ${2:placeholder}}.
Auswahl
Platzhalter können Auswahlmöglichkeiten als Werte haben. Die Syntax ist eine kommagetrennte Aufzählung von Werten, eingeschlossen in das Pipe-Zeichen, z.B. ${1|one,two,three|}. Wenn das Snippet eingefügt und der Platzhalter ausgewählt wird, werden dem Benutzer Auswahlmöglichkeiten angezeigt, um einen der Werte auszuwählen.
Variablen
Mit $name oder ${name:default} können Sie den Wert einer Variablen einfügen. Wenn eine Variable nicht gesetzt ist, wird ihr Standardwert oder eine leere Zeichenkette eingefügt. Wenn eine Variable unbekannt ist (d. h. ihr Name ist nicht definiert), wird der Name der Variablen eingefügt und sie wird in einen Platzhalter umgewandelt.
Die folgenden Variablen können verwendet werden:
-
TM_SELECTED_TEXTDer aktuell ausgewählte Text oder die leere Zeichenkette -
TM_CURRENT_LINEDer Inhalt der aktuellen Zeile -
TM_CURRENT_WORDDer Inhalt des Wortes unter dem Cursor oder die leere Zeichenkette -
TM_LINE_INDEXDie nullbasierte Zeilennummer -
TM_LINE_NUMBERDie einbasierte Zeilennummer -
TM_FILENAMEDer Dateiname des aktuellen Dokuments -
TM_FILENAME_BASEDer Dateiname des aktuellen Dokuments ohne seine Erweiterungen -
TM_DIRECTORYDas Verzeichnis des aktuellen Dokuments -
TM_FILEPATHDer vollständige Dateipfad des aktuellen Dokuments
Variablentransformationen
Transformationen ermöglichen es Ihnen, den Wert einer Variablen zu ändern, bevor sie eingefügt wird. Die Definition einer Transformation besteht aus drei Teilen:
- Ein regulärer Ausdruck, der mit dem Wert einer Variablen oder einer leeren Zeichenkette übereinstimmt, wenn die Variable nicht aufgelöst werden kann.
- Eine „Formatzeichenkette“, die das Referenzieren von Übereinstimmungsgruppen aus dem regulären Ausdruck ermöglicht. Die Formatzeichenkette ermöglicht bedingte Einfügungen und einfache Modifikationen.
- Optionen, die an den regulären Ausdruck übergeben werden.
Das folgende Beispiel fügt den Namen der aktuellen Datei ohne Endung ein, also aus foo.txt wird 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
Grammatik
Unten ist die EBNF (erweiterte Backus-Naur-Form) für Snippets. Mit \ (Backslash) können Sie $, } und \ maskieren. Innerhalb von Auswahl-Elementen maskiert der Backslash auch Komma- und Pipe-Zeichen.
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 ::= .*
if ::= text
else ::= text
Completion Item Resolve Request ()
Die Anfrage wird vom Client an den Server gesendet, um zusätzliche Informationen für ein gegebenes Vervollständigungselement aufzulösen.
Anfrage:
- Methode:
completionItem/resolve - parameter:
CompletionItem
Antwort:
- ergebnis:
CompletionItem - Fehler: Code und Nachricht werden gesetzt, wenn während der Vervollständigungsauflösungsanfrage eine Ausnahme auftritt.
PublishDiagnostics Notification ()
Diagnostikbenachrichtigungen werden vom Server an den Client gesendet, um die Ergebnisse von Validierungsläufen zu signalisieren.
Diagnosen werden vom Server „besessen“, sodass es die Verantwortung des Servers ist, sie bei Bedarf zu löschen. Die folgende Regel wird für VS Code-Server verwendet, die Diagnosen generieren:
- Wenn eine Sprache nur aus Einzelfalldateien besteht (z. B. HTML), werden Diagnostiken vom Server gelöscht, wenn die Datei geschlossen wird. Bitte beachten Sie, dass Öffnungs-/Schließungsereignisse nicht unbedingt das widerspiegeln, was der Benutzer in der Benutzeroberfläche sieht. Diese Ereignisse sind Eigentumsereignisse. Mit der aktuellen Version der Spezifikation ist es möglich, dass Probleme nicht gelöscht werden, obwohl die Datei in der Benutzeroberfläche nicht sichtbar ist, da der Client die Datei noch nicht geschlossen hat.
- Wenn eine Sprache ein Projektsystem hat (z. B. C#), werden die Diagnosen beim Schließen einer Datei nicht gelöscht. Wenn ein Projekt geöffnet wird, werden alle Diagnosen für alle Dateien neu berechnet (oder aus einem Cache gelesen).
Wenn sich eine Datei ändert, liegt es in der Verantwortung des Servers, Diagnosen neu zu berechnen und an den Client zu senden. Wenn die berechnete Menge leer ist, muss er ein leeres Array senden, um frühere Diagnosen zu löschen. Neu gesendete Diagnosen ersetzen immer zuvor gesendete Diagnosen. Es findet kein Zusammenführen auf der Clientseite statt.
Siehe auch den Abschnitt Diagnostic.
Client Capability:
- Eigenschaftsname (optional):
textDocument.publishDiagnostics - Eigenschaftstyp:
PublishDiagnosticsClientCapabilitieswie folgt definiert
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;
}
Benachrichtigung:
- Methode:
textDocument/publishDiagnostics - parameter:
PublishDiagnosticsParamswie folgt definiert
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[];
}
Diagnosen abfragen
Diagnostiken werden derzeit vom Server über eine Benachrichtigung an den Client gesendet. Dieses Modell hat den Vorteil, dass der Server für projektsweite Diagnostiken die Freiheit hat, sie zu einem vom Server bevorzugten Zeitpunkt zu berechnen. Auf der anderen Seite hat der Ansatz den Nachteil, dass der Server die Berechnung für die Datei, in der der Benutzer tippt oder die im Editor sichtbar ist, nicht priorisieren kann. Das Ableiten des UI-Zustands des Clients aus den Benachrichtigungen textDocument/didOpen und textDocument/didChange kann zu falsch positiven Ergebnissen führen, da diese Benachrichtigungen Eigentumsübertragungsbenachrichtigungen sind.
Die Spezifikation führt daher das Konzept von Diagnostic-Pull-Anfragen ein, um dem Client mehr Kontrolle über die Dokumente zu geben, für die Diagnostiken berechnet werden sollen und zu welchem Zeitpunkt.
Client Capability:
- Eigenschaftsname (optional):
textDocument.diagnostic - Eigenschaftstyp:
DiagnosticClientCapabilitieswie folgt definiert
/**
* Client capabilities specific to diagnostic pull requests.
*
* @since 3.17.0
*/
export interface DiagnosticClientCapabilities {
/**
* 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;
/**
* Whether the clients supports related documents for document diagnostic
* pulls.
*/
relatedDocumentSupport?: boolean;
}
Server-Fähigkeit:
- Eigenschaftsname (optional):
diagnosticProvider - Eigenschaftstyp:
DiagnosticOptionswie folgt definiert
/**
* Diagnostic options.
*
* @since 3.17.0
*/
export interface DiagnosticOptions extends WorkDoneProgressOptions {
/**
* An optional identifier under which the diagnostics are
* managed by the client.
*/
identifier?: string;
/**
* Whether the language has inter file dependencies meaning that
* editing code in one file can result in a different diagnostic
* set in another file. Inter file dependencies are common for
* most programming languages and typically uncommon for linters.
*/
interFileDependencies: boolean;
/**
* The server provides support for workspace diagnostics as well.
*/
workspaceDiagnostics: boolean;
}
Registrierungsoptionen: DiagnosticRegistrationOptions Optionen wie folgt definiert
/**
* Diagnostic registration options.
*
* @since 3.17.0
*/
export interface DiagnosticRegistrationOptions extends
TextDocumentRegistrationOptions, DiagnosticOptions,
StaticRegistrationOptions {
}
Dokumentdiagnostik ()
Die Anfrage zur Dokumentendiagnostik wird vom Client an den Server gesendet, um den Server aufzufordern, die Diagnostiken für ein bestimmtes Dokument zu berechnen. Wie bei anderen Pull-Anfragen wird der Server aufgefordert, die Diagnostiken für die aktuell synchronisierte Version des Dokuments zu berechnen.
Anfrage:
- Methode:
textDocument/diagnostic. - Parameter:
DocumentDiagnosticParamswie folgt definiert
/**
* Parameters of the document diagnostic request.
*
* @since 3.17.0
*/
export interface DocumentDiagnosticParams extends WorkDoneProgressParams,
PartialResultParams {
/**
* The text document.
*/
textDocument: TextDocumentIdentifier;
/**
* The additional identifier provided during registration.
*/
identifier?: string;
/**
* The result id of a previous response if provided.
*/
previousResultId?: string;
}
Antwort:
- Ergebnis:
DocumentDiagnosticReportwie folgt definiert
/**
* The result of a document diagnostic pull request. A report can
* either be a full report containing all diagnostics for the
* requested document or a unchanged report indicating that nothing
* has changed in terms of diagnostics in comparison to the last
* pull request.
*
* @since 3.17.0
*/
export type DocumentDiagnosticReport = RelatedFullDocumentDiagnosticReport
| RelatedUnchangedDocumentDiagnosticReport;
/**
* The document diagnostic report kinds.
*
* @since 3.17.0
*/
export namespace DocumentDiagnosticReportKind {
/**
* A diagnostic report with a full
* set of problems.
*/
export const Full = 'full';
/**
* A report indicating that the last
* returned report is still accurate.
*/
export const Unchanged = 'unchanged';
}
export type DocumentDiagnosticReportKind = 'full' | 'unchanged';
/**
* A diagnostic report with a full set of problems.
*
* @since 3.17.0
*/
export interface FullDocumentDiagnosticReport {
/**
* A full document diagnostic report.
*/
kind: DocumentDiagnosticReportKind.Full;
/**
* An optional result id. If provided it will
* be sent on the next diagnostic request for the
* same document.
*/
resultId?: string;
/**
* The actual items.
*/
items: Diagnostic[];
}
/**
* A diagnostic report indicating that the last returned
* report is still accurate.
*
* @since 3.17.0
*/
export interface UnchangedDocumentDiagnosticReport {
/**
* A document diagnostic report indicating
* no changes to the last result. A server can
* only return `unchanged` if result ids are
* provided.
*/
kind: DocumentDiagnosticReportKind.Unchanged;
/**
* A result id which will be sent on the next
* diagnostic request for the same document.
*/
resultId: string;
}
/**
* A full diagnostic report with a set of related documents.
*
* @since 3.17.0
*/
export interface RelatedFullDocumentDiagnosticReport extends
FullDocumentDiagnosticReport {
/**
* Diagnostics of related documents. This information is useful
* in programming languages where code in a file A can generate
* diagnostics in a file B which A depends on. An example of
* such a language is C/C++ where macro definitions in a file
* a.cpp and result in errors in a header file b.hpp.
*
* @since 3.17.0
*/
relatedDocuments?: {
[uri: string /** DocumentUri */]:
FullDocumentDiagnosticReport | UnchangedDocumentDiagnosticReport;
};
}
/**
* An unchanged diagnostic report with a set of related documents.
*
* @since 3.17.0
*/
export interface RelatedUnchangedDocumentDiagnosticReport extends
UnchangedDocumentDiagnosticReport {
/**
* Diagnostics of related documents. This information is useful
* in programming languages where code in a file A can generate
* diagnostics in a file B which A depends on. An example of
* such a language is C/C++ where macro definitions in a file
* a.cpp and result in errors in a header file b.hpp.
*
* @since 3.17.0
*/
relatedDocuments?: {
[uri: string /** DocumentUri */]:
FullDocumentDiagnosticReport | UnchangedDocumentDiagnosticReport;
};
}
- Teilergebnis: Das erste gesendete Literal muss ein
DocumentDiagnosticReportsein, gefolgt von nDocumentDiagnosticReportPartialResultLiteralen wie folgt definiert
/**
* A partial result for a document diagnostic report.
*
* @since 3.17.0
*/
export interface DocumentDiagnosticReportPartialResult {
relatedDocuments: {
[uri: string /** DocumentUri */]:
FullDocumentDiagnosticReport | UnchangedDocumentDiagnosticReport;
};
}
- Fehler: Code und Nachricht werden gesetzt, wenn während der Diagnostikanfrage eine Ausnahme auftritt. Ein Server darf auch einen Fehler mit dem Code
ServerCancelledzurückgeben, um anzuzeigen, dass der Server das Ergebnis derzeit nicht berechnen kann. Ein Server kannDiagnosticServerCancellationDataals Daten zurückgeben, um anzugeben, ob der Client die Anfrage erneut auslösen soll. Wenn keine Daten bereitgestellt werden, wird standardmäßig{ retriggerRequest: true }verwendet.
/**
* Cancellation data returned from a diagnostic request.
*
* @since 3.17.0
*/
export interface DiagnosticServerCancellationData {
retriggerRequest: boolean;
}
Workspace-Diagnostik ()
Die Workspace-Diagnoseanfrage wird vom Client an den Server gesendet, um den Server zu bitten, quellbereichsweite Diagnosen zu berechnen, die zuvor vom Server an den Client gesendet wurden. Im Gegensatz zur Dokument-Diagnoseanfrage kann die Workspace-Anfrage langwierig sein und ist nicht an einen bestimmten Zustand des Workspace oder Dokuments gebunden. Wenn der Client das Streamen für das Abrufen von Workspace-Diagnosen unterstützt, ist es zulässig, mehrere Dokument-Diagnoseberichte für dieselbe Dokument-URI bereitzustellen. Der zuletzt gemeldete Bericht hat Vorrang vor früheren Berichten.
Wenn ein Client einen Diagnosebericht für ein Dokument in einer Workspace-Diagnoseanfrage erhält, für die der Client auch einzelne Dokument-Diagnose-Abrufanfragen ausgibt, muss der Client entscheiden, welche Diagnosen Vorrang haben und angezeigt werden sollen. Allgemein gilt:
- Diagnosen für eine höhere Dokumentenversion sollten Vorrang vor denen aus einer niedrigeren Dokumentenversion haben (z. B. beachten Sie, dass Dokumentenversionen stetig steigen).
- Diagnosen aus einem Dokumentabruf sollten Vorrang vor Diagnosen aus einem Workspace-Abruf haben.
Anfrage:
- Methode:
workspace/diagnostic. - Parameter:
WorkspaceDiagnosticParams, wie folgt definiert:
/**
* Parameters of the workspace diagnostic request.
*
* @since 3.17.0
*/
export interface WorkspaceDiagnosticParams extends WorkDoneProgressParams,
PartialResultParams {
/**
* The additional identifier provided during registration.
*/
identifier?: string;
/**
* The currently known diagnostic reports with their
* previous result ids.
*/
previousResultIds: PreviousResultId[];
}
/**
* A previous result id in a workspace pull request.
*
* @since 3.17.0
*/
export interface PreviousResultId {
/**
* The URI for which the client knows a
* result id.
*/
uri: DocumentUri;
/**
* The value of the previous result id.
*/
value: string;
}
Antwort:
- Ergebnis:
WorkspaceDiagnosticReport, wie folgt definiert:
/**
* A workspace diagnostic report.
*
* @since 3.17.0
*/
export interface WorkspaceDiagnosticReport {
items: WorkspaceDocumentDiagnosticReport[];
}
/**
* A full document diagnostic report for a workspace diagnostic result.
*
* @since 3.17.0
*/
export interface WorkspaceFullDocumentDiagnosticReport extends
FullDocumentDiagnosticReport {
/**
* The URI for which diagnostic information is reported.
*/
uri: DocumentUri;
/**
* The version number for which the diagnostics are reported.
* If the document is not marked as open `null` can be provided.
*/
version: integer | null;
}
/**
* An unchanged document diagnostic report for a workspace diagnostic result.
*
* @since 3.17.0
*/
export interface WorkspaceUnchangedDocumentDiagnosticReport extends
UnchangedDocumentDiagnosticReport {
/**
* The URI for which diagnostic information is reported.
*/
uri: DocumentUri;
/**
* The version number for which the diagnostics are reported.
* If the document is not marked as open `null` can be provided.
*/
version: integer | null;
};
/**
* A workspace diagnostic document report.
*
* @since 3.17.0
*/
export type WorkspaceDocumentDiagnosticReport =
WorkspaceFullDocumentDiagnosticReport
| WorkspaceUnchangedDocumentDiagnosticReport;
- Teilergebnis: Der erste gesendete Literal muss ein
WorkspaceDiagnosticReportsein, gefolgt von nWorkspaceDiagnosticReportPartialResult-Literalen, wie folgt definiert:
/**
* A partial result for a workspace diagnostic report.
*
* @since 3.17.0
*/
export interface WorkspaceDiagnosticReportPartialResult {
items: WorkspaceDocumentDiagnosticReport[];
}
- Fehler: Code und Nachricht werden gesetzt, wenn während der Diagnoseanfrage eine Ausnahme auftritt. Ein Server darf auch einen Fehler mit dem Code
ServerCancelledzurückgeben, was bedeutet, dass der Server das Ergebnis derzeit nicht berechnen kann. Ein Server kann eineDiagnosticServerCancellationDatazurückgeben, um anzugeben, ob der Client die Anfrage erneut auslösen soll. Wenn keine Daten bereitgestellt werden, wird standardmäßig{ retriggerRequest: true }verwendet.
Diagnosen aktualisieren ()
Die Anfrage workspace/diagnostic/refresh wird vom Server an den Client gesendet. Server können sie verwenden, um Clients aufzufordern, alle erforderlichen Dokument- und Workspace-Diagnosen zu aktualisieren. Dies ist nützlich, wenn ein Server eine projektweite Konfigurationsänderung erkennt, die eine Neuberechnung aller Diagnosen erfordert.
Client Capability:
- Eigenschaftsname (optional):
workspace.diagnostics - Eigenschaftstyp:
DiagnosticWorkspaceClientCapabilities, wie folgt definiert:
/**
* Workspace client capabilities specific to diagnostic pull requests.
*
* @since 3.17.0
*/
export interface DiagnosticWorkspaceClientCapabilities {
/**
* 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
* pulled diagnostics currently shown. It should be used with absolute care
* and is useful for situation where a server for example detects a project
* wide change that requires such a calculation.
*/
refreshSupport?: boolean;
}
Anfrage:
- Methode:
workspace/diagnostic/refresh - params: none
Antwort:
- result: void
- Fehler: Code und Nachricht werden gesetzt, wenn während der Anfrage
workspace/diagnostic/refresheine Ausnahme auftritt.
Implementierungsüberlegungen
Im Allgemeinen erzwingt die Language Server-Spezifikation keine spezifische Client-Implementierung, da diese normalerweise davon abhängt, wie die Client-Benutzeroberfläche funktioniert. Da Diagnosen jedoch auf Dokumenten- und Workspace-Ebene bereitgestellt werden können, hier einige Tipps:
- Ein Client sollte aktiv nach dem Dokument suchen, in das der Benutzer tippt.
- Wenn der Server dateiübergreifende Abhängigkeiten signalisiert, sollte ein Client auch nach sichtbaren Dokumenten suchen, um genaue Diagnosen zu gewährleisten. Die Abfrage sollte jedoch seltener erfolgen.
- Wenn der Server die Unterstützung für Workspace-Abfragen signalisiert, sollte ein Client auch Workspace-Diagnosen abfragen. Es wird empfohlen, dass Clients Teilergebnis-Fortschritt für die Workspace-Abfrage implementieren, damit Server die Anfrage lange offen halten können. Wenn ein Server eine Workspace-Diagnoseabfrage schließt, sollte der Client die Anfrage erneut auslösen.
Signature Help Request ()
Die Signaturhilfe-Anfrage wird vom Client an den Server gesendet, um Signaturinformationen an einer gegebenen Cursorposition anzufordern.
Client Capability:
- Eigenschaftsname (optional):
textDocument.signatureHelp - Eigenschaftstyp:
SignatureHelpClientCapabilitieswie folgt definiert
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-Fähigkeit:
- Eigenschaftsname (optional):
signatureHelpProvider - Eigenschaftstyp:
SignatureHelpOptionswie folgt definiert
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[];
}
Registrierungsoptionen: SignatureHelpRegistrationOptions wie folgt definiert
export interface SignatureHelpRegistrationOptions
extends TextDocumentRegistrationOptions, SignatureHelpOptions {
}
Anfrage:
- Methode:
textDocument/signatureHelp - parameter:
SignatureHelpParamswie folgt definiert
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;
}
/**
* 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;
/**
* 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;
}
Antwort:
- ergebnis:
SignatureHelp|nullwie folgt definiert
/**
* 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;
}
/**
* 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;
}
/**
* 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;
}
- Fehler: Code und Nachricht werden gesetzt, wenn während der Signaturhilfe-Anfrage eine Ausnahme auftritt.
Code-Aktion-Anfrage ()
Die Code-Aktionsanfrage wird vom Client an den Server gesendet, um Befehle für ein bestimmtes Textdokument und einen bestimmten Bereich zu berechnen. Diese Befehle sind typischerweise Code-Korrekturen, um Probleme zu beheben oder Code zu verschönern/refaktorieren. Das Ergebnis einer textDocument/codeAction-Anfrage ist ein Array von Command-Literalen, die typischerweise in der Benutzeroberfläche angezeigt werden. Um sicherzustellen, dass ein Server in vielen Clients nützlich ist, sollten die in einer Code-Aktion angegebenen Befehle vom Server und nicht vom Client verarbeitet werden (siehe workspace/executeCommand und ServerCapabilities.executeCommandProvider). Wenn der Client die Bereitstellung von Bearbeitungen mit einer Code-Aktion unterstützt, sollte dieser Modus verwendet werden.
Seit Version 3.16.0: Ein Client kann einem Server anbieten, die Berechnung von Code-Aktions-Eigenschaften während einer `textDocument/codeAction`-Anfrage zu verzögern.
Dies ist nützlich für Fälle, in denen die Berechnung des Wertes einer Eigenschaft aufwendig ist (z. B. die edit-Eigenschaft). Clients signalisieren dies über die codeAction.resolveSupport-Fähigkeit, die alle Eigenschaften auflistet, die ein Client verzögert auflösen kann. Die Serverfähigkeit codeActionProvider.resolveProvider signalisiert, dass ein Server eine codeAction/resolve-Route anbietet. Um Servern zu helfen, eine Code-Aktion in der Resolve-Anfrage eindeutig zu identifizieren, kann ein Code-Aktion-Literal optional eine Daten-Eigenschaft tragen. Dies wird ebenfalls durch eine zusätzliche Client-Fähigkeit codeAction.dataSupport geschützt. Im Allgemeinen sollte ein Client Datenunterstützung anbieten, wenn er Resolve-Unterstützung anbietet. Es sollte auch beachtet werden, dass Server bestehende Attribute einer Code-Aktion in einer codeAction/resolve-Anfrage nicht ändern sollten.
Seit Version 3.8.0: Unterstützung für CodeAction-Literale zur Ermöglichung der folgenden Szenarien:
- die Möglichkeit, eine Workspace-Änderung direkt von der Code-Aktions-Anfrage zurückzugeben. Dies vermeidet einen weiteren Server-Roundtrip zur Ausführung einer tatsächlichen Code-Aktion. Serveranbieter sollten sich jedoch bewusst sein, dass es immer noch vorteilhaft sein kann, wenn das Ergebnis einfach ein Befehl ist und die tatsächliche Änderung nur bei Bedarf berechnet wird, wenn die Code-Aktion teuer zu berechnen ist oder die Änderungen sehr groß sind.
- die Möglichkeit, Code-Aktionen mithilfe einer Art zu gruppieren. Clients dürfen diese Informationen ignorieren. Sie ermöglicht es ihnen jedoch, Code-Aktionen besser zu gruppieren, z. B. in entsprechende Menüs (z. B. alle Refactor-Code-Aktionen in ein Refactor-Menü).
Clients müssen ihre Unterstützung für Code-Aktions-Literale (z. B. Literale vom Typ CodeAction) und Code-Aktions-Arten über die entsprechende Client-Fähigkeit codeAction.codeActionLiteralSupport ankündigen.
Client Capability:
- Eigenschaftsname (optional):
textDocument.codeAction - Eigenschaftstyp:
CodeActionClientCapabilities, wie folgt definiert:
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-Fähigkeit:
- Eigenschaftsname (optional):
codeActionProvider - Eigenschaftstyp:
boolean | CodeActionOptions, wobeiCodeActionOptionswie folgt definiert ist:
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;
}
Registrierungsoptionen: CodeActionRegistrationOptions, wie folgt definiert:
export interface CodeActionRegistrationOptions extends
TextDocumentRegistrationOptions, CodeActionOptions {
}
Anfrage:
- Methode:
textDocument/codeAction - Parameter:
CodeActionParams, wie folgt definiert:
/**
* 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;
}
/**
* 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';
}
/**
* 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;
}
/**
* The reason why code actions were requested.
*
* @since 3.17.0
*/
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;
Antwort:
- Ergebnis:
(Command | CodeAction)[]|null, wobeiCodeActionwie folgt definiert ist:
/**
* 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;
}
- Teilergebnis:
(Command | CodeAction)[] - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Code-Aktion-Anfrage auftritt.
Code-Aktion-Auflösungsanfrage ()
Seit Version 3.16.0
Die Anfrage wird vom Client an den Server gesendet, um zusätzliche Informationen für eine gegebene Code-Aktion aufzulösen. Dies wird normalerweise verwendet, um die `edit`-Eigenschaft einer Code-Aktion zu berechnen, um deren unnötige Berechnung während der `textDocument/codeAction`-Anfrage zu vermeiden.
Betrachten Sie, wie der Client die `edit`-Eigenschaft als eine Eigenschaft ankündigt, die über die Client-Fähigkeit verzögert aufgelöst werden kann
textDocument.codeAction.resolveSupport = { properties: ['edit'] };
dann muss eine Code-Aktion
{
"title": "Do Foo"
}
mithilfe der `codeAction/resolve`-Anfrage aufgelöst werden, bevor sie angewendet werden kann.
Client Capability:
- Eigenschaftsname (optional):
textDocument.codeAction.resolveSupport - Eigenschaftstyp:
{ properties: string[]; }
Anfrage:
- Methode:
codeAction/resolve - Parameter:
CodeAction
Antwort:
- Ergebnis:
CodeAction - Fehler: Code und Nachricht werden gesetzt, wenn während der Code-Aktions-Resolve-Anfrage eine Ausnahme auftritt.
Dokument-Farbanfrage ()
Seit Version 3.6.0
Die Dokument-Farbanfrage wird vom Client an den Server gesendet, um alle Farbverweise in einem gegebenen Textdokument aufzulisten. Zusammen mit dem Bereich wird ein Farbwert in RGB zurückgegeben.
Clients können das Ergebnis verwenden, um Farbverweise in einem Editor zu dekorieren. Zum Beispiel:
- Farbkästen, die die tatsächliche Farbe neben dem Verweis anzeigen
- Farbwähler anzeigen, wenn ein Farbverweis bearbeitet wird
Client Capability:
- Eigenschaftsname (optional):
textDocument.colorProvider - Eigenschaftstyp:
DocumentColorClientCapabilities, wie folgt definiert:
export interface DocumentColorClientCapabilities {
/**
* Whether document color supports dynamic registration.
*/
dynamicRegistration?: boolean;
}
Server-Fähigkeit:
- Eigenschaftsname (optional):
colorProvider - Eigenschaftstyp:
boolean | DocumentColorOptions | DocumentColorRegistrationOptions, wobeiDocumentColorOptionswie folgt definiert ist:
export interface DocumentColorOptions extends WorkDoneProgressOptions {
}
Registrierungsoptionen: DocumentColorRegistrationOptions, wie folgt definiert:
export interface DocumentColorRegistrationOptions extends
TextDocumentRegistrationOptions, StaticRegistrationOptions,
DocumentColorOptions {
}
Anfrage:
- Methode:
textDocument/documentColor - Parameter:
DocumentColorParams, wie folgt definiert:
interface DocumentColorParams extends WorkDoneProgressParams,
PartialResultParams {
/**
* The text document.
*/
textDocument: TextDocumentIdentifier;
}
Antwort:
- Ergebnis:
ColorInformation[], wie folgt definiert:
interface ColorInformation {
/**
* The range in the document where this color appears.
*/
range: Range;
/**
* The actual color value for this color range.
*/
color: Color;
}
/**
* 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;
}
- Teilergebnis:
ColorInformation[] - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der `textDocument/documentColor`-Anfrage auftritt.
Farbpräsentationsanfrage ()
Seit Version 3.6.0
Die Farbpräsentationsanfrage wird vom Client an den Server gesendet, um eine Liste von Präsentationen für einen Farbwert an einem gegebenen Ort zu erhalten. Clients können das Ergebnis verwenden, um
- einen Farbverweis zu ändern.
- in einem Farbwähler anzuzeigen und Benutzern die Auswahl einer der Präsentationen zu ermöglichen
Diese Anfrage hat keine speziellen Fähigkeiten und Registrierungsoptionen, da sie als Auflösungsanfrage für die `textDocument/documentColor`-Anfrage gesendet wird.
Anfrage:
- Methode:
textDocument/colorPresentation - Parameter:
ColorPresentationParams, wie folgt definiert:
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;
}
Antwort:
- Ergebnis:
ColorPresentation[], wie folgt definiert:
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 omitted 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[];
}
- Teilergebnis:
ColorPresentation[] - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der `textDocument/colorPresentation`-Anfrage auftritt.
Dokumentformatierungsanfrage ()
Die Dokumentformatierungsanfrage wird vom Client an den Server gesendet, um ein ganzes Dokument zu formatieren.
Client Capability:
- Eigenschaftsname (optional):
textDocument.formatting - Eigenschaftstyp:
DocumentFormattingClientCapabilities, wie folgt definiert:
export interface DocumentFormattingClientCapabilities {
/**
* Whether formatting supports dynamic registration.
*/
dynamicRegistration?: boolean;
}
Server-Fähigkeit:
- Eigenschaftsname (optional):
documentFormattingProvider - Eigenschaftstyp:
boolean | DocumentFormattingOptions, wobeiDocumentFormattingOptionswie folgt definiert ist:
export interface DocumentFormattingOptions extends WorkDoneProgressOptions {
}
Registrierungsoptionen: DocumentFormattingRegistrationOptions, wie folgt definiert:
export interface DocumentFormattingRegistrationOptions extends
TextDocumentRegistrationOptions, DocumentFormattingOptions {
}
Anfrage:
- Methode:
textDocument/formatting - Parameter:
DocumentFormattingParams, wie folgt definiert:
interface DocumentFormattingParams extends WorkDoneProgressParams {
/**
* The document to format.
*/
textDocument: TextDocumentIdentifier;
/**
* The format options.
*/
options: FormattingOptions;
}
/**
* 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;
}
Antwort:
- Ergebnis:
TextEdit[]|null, beschreibt die Änderung am zu formatierenden Dokument. - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Formatierungsanfrage auftritt.
Dokument-Bereichsformatierungsanfrage ()
Die Dokument-Bereichsformatierungsanfrage wird vom Client an den Server gesendet, um einen gegebenen Bereich in einem Dokument zu formatieren.
Client Capability:
- Eigenschaftsname (optional):
textDocument.rangeFormatting - Eigenschaftstyp:
DocumentRangeFormattingClientCapabilities, wie folgt definiert:
export interface DocumentRangeFormattingClientCapabilities {
/**
* Whether formatting supports dynamic registration.
*/
dynamicRegistration?: boolean;
}
Server-Fähigkeit:
- Eigenschaftsname (optional):
documentRangeFormattingProvider - Eigenschaftstyp:
boolean | DocumentRangeFormattingOptions, wobeiDocumentRangeFormattingOptionswie folgt definiert ist:
export interface DocumentRangeFormattingOptions extends
WorkDoneProgressOptions {
}
Registrierungsoptionen: DocumentFormattingRegistrationOptions, wie folgt definiert:
export interface DocumentRangeFormattingRegistrationOptions extends
TextDocumentRegistrationOptions, DocumentRangeFormattingOptions {
}
Anfrage:
- Methode:
textDocument/rangeFormatting, - Parameter:
DocumentRangeFormattingParams, wie folgt definiert:
interface DocumentRangeFormattingParams extends WorkDoneProgressParams {
/**
* The document to format.
*/
textDocument: TextDocumentIdentifier;
/**
* The range to format
*/
range: Range;
/**
* The format options
*/
options: FormattingOptions;
}
Antwort:
- Ergebnis:
TextEdit[]|null, beschreibt die Änderung am zu formatierenden Dokument. - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Bereichsformatierungsanfrage auftritt.
Dokument-Formatierungsanfrage bei Tippen ()
Die Dokument-Formatierungsanfrage bei Tippen wird vom Client an den Server gesendet, um Teile des Dokuments während des Tippens zu formatieren.
Client Capability:
- Eigenschaftsname (optional):
textDocument.onTypeFormatting - Eigenschaftstyp:
DocumentOnTypeFormattingClientCapabilities, wie folgt definiert:
export interface DocumentOnTypeFormattingClientCapabilities {
/**
* Whether on type formatting supports dynamic registration.
*/
dynamicRegistration?: boolean;
}
Server-Fähigkeit:
- Eigenschaftsname (optional):
documentOnTypeFormattingProvider - Eigenschaftstyp:
DocumentOnTypeFormattingOptions, wie folgt definiert:
export interface DocumentOnTypeFormattingOptions {
/**
* A character on which formatting should be triggered, like `{`.
*/
firstTriggerCharacter: string;
/**
* More trigger characters.
*/
moreTriggerCharacter?: string[];
}
Registrierungsoptionen: DocumentOnTypeFormattingRegistrationOptions, wie folgt definiert:
export interface DocumentOnTypeFormattingRegistrationOptions extends
TextDocumentRegistrationOptions, DocumentOnTypeFormattingOptions {
}
Anfrage:
- Methode:
textDocument/onTypeFormatting - Parameter:
DocumentOnTypeFormattingParams, wie folgt definiert:
interface DocumentOnTypeFormattingParams {
/**
* The document to format.
*/
textDocument: TextDocumentIdentifier;
/**
* The position around which the on type formatting should happen.
* This is not necessarily the exact position where the character denoted
* by the property `ch` got typed.
*/
position: Position;
/**
* The character that has been typed that triggered the formatting
* on type request. That is not necessarily the last character that
* got inserted into the document since the client could auto insert
* characters as well (e.g. like automatic brace completion).
*/
ch: string;
/**
* The formatting options.
*/
options: FormattingOptions;
}
Antwort:
- Ergebnis:
TextEdit[]|null, beschreibt die Änderung am Dokument. - Fehler: Code und Nachricht werden gesetzt, falls eine Ausnahme während der Bereichsformatierungsanfrage auftritt.
Umbenennungsanfrage ()
Die Umbenennungsanfrage wird vom Client an den Server gesendet, um den Server aufzufordern, eine Workspace-Änderung zu berechnen, damit der Client eine projektweite Umbenennung eines Symbols durchführen kann.
Client Capability:
- Eigenschaftsname (optional):
textDocument.rename - Eigenschaftstyp:
RenameClientCapabilities, wie folgt definiert:
export namespace PrepareSupportDefaultBehavior {
/**
* The client's default behavior is to select the identifier
* according to the language's syntax rule.
*/
export const Identifier: 1 = 1;
}
export type PrepareSupportDefaultBehavior = 1;
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 the 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-Fähigkeit:
- Eigenschaftsname (optional):
renameProvider - Eigenschaftstyp:
boolean | RenameOptions, wobeiRenameOptionswie folgt definiert ist:
RenameOptions kann nur angegeben werden, wenn der Client im Rahmen seiner ersten `initialize`-Anfrage prepareSupport angibt.
export interface RenameOptions extends WorkDoneProgressOptions {
/**
* Renames should be checked and tested before being executed.
*/
prepareProvider?: boolean;
}
Registrierungsoptionen: RenameRegistrationOptions, wie folgt definiert:
export interface RenameRegistrationOptions extends
TextDocumentRegistrationOptions, RenameOptions {
}
Anfrage:
- Methode:
textDocument/rename - Parameter:
RenameParams, wie folgt definiert:
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;
}
Antwort:
- Ergebnis:
WorkspaceEdit|null, das die Änderung am Workspace beschreibt.nullsollte genauso behandelt werden wie einWorkspaceEditohne Änderungen (es war keine Änderung erforderlich). - Fehler: Code und Nachricht werden gesetzt, wenn die Umbenennung aus irgendeinem Grund nicht durchgeführt werden konnte. Beispiele hierfür sind: Es gibt nichts an der angegebenen
position, das umbenannt werden kann (wie ein Leerzeichen), das gegebene Symbol unterstützt das Umbenennen durch den Server nicht oder der Code ist ungültig (z. B. kompiliert nicht).
Umbenennung vorbereiten Anfrage ()
Seit Version 3.12.0
Die Umbenennung vorbereiten Anfrage wird vom Client an den Server gesendet, um eine Umbenennungsoperation an einer gegebenen Position vorzubereiten und deren Gültigkeit zu prüfen.
Anfrage:
- Methode:
textDocument/prepareRename - Parameter:
PrepareRenameParams, wie folgt definiert:
export interface PrepareRenameParams extends TextDocumentPositionParams, WorkDoneProgressParams {
}
Antwort:
- Ergebnis:
Range | { range: Range, placeholder: string } | { defaultBehavior: boolean } | null, das einenRangedes umzubenennenden Strings und optional einen Platzhaltertext für den umzubenennenden String-Inhalt beschreibt. Wenn{ defaultBehavior: boolean }zurückgegeben wird (seit 3.16), ist die Umbenennungsposition gültig und der Client sollte sein Standardverhalten verwenden, um den Umbenennungsbereich zu berechnen. Wennnullzurückgegeben wird, gilt einetextDocument/rename-Anfrage an der gegebenen Position als ungültig. - Fehler: Code und Nachricht werden gesetzt, falls das Element nicht umbenannt werden kann. Clients sollten die Informationen in ihrer Benutzeroberfläche anzeigen.
Linked Editing Range()
Seit Version 3.16.0
Die Linked Editing-Anfrage wird vom Client an den Server gesendet, um für eine gegebene Position in einem Dokument den Bereich des Symbols an der Position und alle Bereiche mit demselben Inhalt zurückzugeben. Optional kann ein Wortmuster zurückgegeben werden, um gültige Inhalte zu beschreiben. Eine Umbenennung in einen der Bereiche kann auf alle anderen Bereiche angewendet werden, wenn der neue Inhalt gültig ist. Wenn kein ergebnisspezifisches Wortmuster angegeben wird, wird das Wortmuster aus der Sprachkonfiguration des Clients verwendet.
Client Capabilities:
- property name (optional):
textDocument.linkedEditingRange - property type:
LinkedEditingRangeClientCapabilitiesdefiniert wie folgt
export interface LinkedEditingRangeClientCapabilities {
/**
* Whether the 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-Fähigkeit:
- property name (optional):
linkedEditingRangeProvider - property type:
boolean|LinkedEditingRangeOptions|LinkedEditingRangeRegistrationOptionsdefiniert wie folgt
export interface LinkedEditingRangeOptions extends WorkDoneProgressOptions {
}
Registration Options: LinkedEditingRangeRegistrationOptions definiert wie folgt
export interface LinkedEditingRangeRegistrationOptions extends
TextDocumentRegistrationOptions, LinkedEditingRangeOptions,
StaticRegistrationOptions {
}
Anfrage:
- method:
textDocument/linkedEditingRange - params:
LinkedEditingRangeParamsdefiniert wie folgt
export interface LinkedEditingRangeParams extends TextDocumentPositionParams,
WorkDoneProgressParams {
}
Antwort:
- result:
LinkedEditingRanges|nulldefiniert wie folgt
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 und message gesetzt im Falle eines Exceptions während der ‘textDocument/linkedEditingRange’ Anfrage
Arbeitsbereichsfunktionen
Workspace-Symbole-Anfrage ()
Die Workspace-Symbolanfrage wird vom Client an den Server gesendet, um projektweite Symbole aufzulisten, die mit der Abfragezeichenfolge übereinstimmen. Seit 3.17.0 können Server auch einen Handler für workspaceSymbol/resolve-Anfragen bereitstellen. Dies ermöglicht es Servern, Workspace-Symbole ohne Bereich für eine workspace/symbol-Anfrage zurückzugeben. Clients müssen dann den Bereich bei Bedarf über die workspaceSymbol/resolve-Anfrage auflösen. Server können dieses neue Modell nur verwenden, wenn Clients dies über die workspace.symbol.resolveSupport-Fähigkeit ankündigen.
Client Capability:
- property path (optional):
workspace.symbol - property type:
WorkspaceSymbolClientCapabilities, wie folgt definiert
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-Fähigkeit:
- property path (optional):
workspaceSymbolProvider - property type:
boolean | WorkspaceSymbolOptions, wobeiWorkspaceSymbolOptionswie folgt definiert ist
export interface WorkspaceSymbolOptions extends WorkDoneProgressOptions {
/**
* The server provides support to resolve additional
* information for a workspace symbol.
*
* @since 3.17.0
*/
resolveProvider?: boolean;
}
Registrierungsoptionen: WorkspaceSymbolRegistrationOptions wie folgt definiert
export interface WorkspaceSymbolRegistrationOptions
extends WorkspaceSymbolOptions {
}
Anfrage:
- methode: „workspace/symbol“
- parameter:
WorkspaceSymbolParamswie folgt definiert
/**
* 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;
}
Antwort:
- Ergebnis:
SymbolInformation[]|WorkspaceSymbol[]|null. Siehe oben für die Definition vonSymbolInformation. Es wird empfohlen, das neueWorkspaceSymbolzu verwenden. Ob das Workspace-Symbol jedoch einen Speicherort ohne Bereich zurückgeben kann, hängt von der Client-Fähigkeitworkspace.symbol.resolveSupportab.WorkspaceSymbol, das wie folgt definiert ist:
/**
* A special workspace symbol that supports locations without a range
*
* @since 3.17.0
*/
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 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;
/**
* The location of this symbol. Whether a server is allowed to
* return a location without a range depends on the client
* capability `workspace.symbol.resolveSupport`.
*
* See also `SymbolInformation.location`.
*/
location: Location | { uri: DocumentUri };
/**
* A data entry field that is preserved on a workspace symbol between a
* workspace symbol request and a workspace symbol resolve request.
*/
data?: LSPAny;
}
- Teilergebnis:
SymbolInformation[]|WorkspaceSymbol[]wie oben definiert. - Fehler: Code und Nachricht werden gesetzt, wenn während der Workspace-Symbolanfrage eine Ausnahme auftritt.
Workspace Symbol Resolve Request ()
Die Anfrage wird vom Client an den Server gesendet, um zusätzliche Informationen für ein gegebenes Workspace-Symbol aufzulösen.
Anfrage:
- Methode:
workspaceSymbol/resolve - Parameter:
WorkspaceSymbol
Antwort:
- Ergebnis:
WorkspaceSymbol - Fehler: Code und Nachricht werden gesetzt, wenn während der Workspace-Symbol-Resolve-Anfrage eine Ausnahme auftritt.
Konfigurationsanfrage ()
Seit Version 3.6.0
Die workspace/configuration-Anfrage wird vom Server an den Client gesendet, um Konfigurationseinstellungen vom Client abzurufen. Die Anfrage kann mehrere Konfigurationseinstellungen in einem einzigen Roundtrip abrufen. Die Reihenfolge der zurückgegebenen Konfigurationseinstellungen entspricht der Reihenfolge der übergebenen ConfigurationItems (z. B. ist das erste Element in der Antwort das Ergebnis für das erste Konfigurationselement in den Parametern).
Ein ConfigurationItem besteht aus dem zu erfragenden Konfigurationsabschnitt und einer zusätzlichen Bereichs-URI. Der abgefragte Konfigurationsabschnitt wird vom Server definiert und muss nicht unbedingt dem vom Client verwendeten Konfigurationsspeicher entsprechen. So könnte ein Server nach einer Konfiguration cpp.formatterOptions fragen, der Client speichert die Konfiguration jedoch anders in einem XML-Speicherlayout. Es liegt am Client, die notwendige Konvertierung durchzuführen. Wenn eine Bereichs-URI angegeben ist, sollte der Client die Einstellung für die angegebene Ressource zurückgeben. Wenn der Client beispielsweise EditorConfig zur Verwaltung seiner Einstellungen verwendet, sollte die Konfiguration für die angegebene Ressourcen-URI zurückgegeben werden. Wenn der Client keine Konfigurationseinstellung für einen bestimmten Bereich bereitstellen kann, muss null im zurückgegebenen Array vorhanden sein.
Dieses Pull-Modell ersetzt das alte Push-Modell, bei dem der Client eine Konfigurationsänderung über ein Ereignis signalisierte. Wenn der Server immer noch auf Konfigurationsänderungen reagieren muss (da der Server das Ergebnis von workspace/configuration-Anfragen zwischenspeichert), sollte der Server sich für eine leere Konfigurationsänderung mit dem folgenden Registrierungsmuster registrieren:
connection.client.register(DidChangeConfigurationNotification.type, undefined);
Client Capability:
- property path (optional):
workspace.configuration - property type:
boolean
Anfrage:
- method: ‘workspace/configuration’
- params:
ConfigurationParams, wie folgt definiert
export interface ConfigurationParams {
items: ConfigurationItem[];
}
export interface ConfigurationItem {
/**
* The scope to get the configuration section for.
*/
scopeUri?: URI;
/**
* The configuration section asked for.
*/
section?: string;
}
Antwort:
- Ergebnis:
LSPAny[] - error: code und message werden gesetzt, wenn während der
workspace/configuration-Anfrage ein Fehler auftritt
DidChangeConfiguration-Benachrichtigung ()
Eine Benachrichtigung, die vom Client an den Server gesendet wird, um die Änderung von Konfigurationseinstellungen zu signalisieren.
Client Capability:
- property path (optional):
workspace.didChangeConfiguration - property type:
DidChangeConfigurationClientCapabilities, wie folgt definiert
export interface DidChangeConfigurationClientCapabilities {
/**
* Did change configuration notification supports dynamic registration.
*
* @since 3.6.0 to support the new pull model.
*/
dynamicRegistration?: boolean;
}
Benachrichtigung:
- method: ‘workspace/didChangeConfiguration’,
- params:
DidChangeConfigurationParams, wie folgt definiert
interface DidChangeConfigurationParams {
/**
* The actual changed settings
*/
settings: LSPAny;
}
Workspace-Ordner-Anfrage ()
Seit Version 3.6.0
Viele Tools unterstützen mehr als einen Stammordner pro Workspace. Beispiele hierfür sind die Multi-Root-Unterstützung von VS Code, die Projektordner-Unterstützung von Atom oder die Projektunterstützung von Sublime. Wenn ein Client-Workspace aus mehreren Wurzeln besteht, muss ein Server dies normalerweise wissen. Das Protokoll geht bisher von einem Stammordner aus, der dem Server über die rootUri-Eigenschaft der InitializeParams mitgeteilt wird. Wenn der Client Workspace-Ordner unterstützt und diese über die entsprechende workspaceFolders-Client-Fähigkeit ankündigt, enthalten die InitializeParams eine zusätzliche Eigenschaft workspaceFolders mit den konfigurierten Workspace-Ordnern beim Start des Servers.
Die workspace/workspaceFolders-Anfrage wird vom Server an den Client gesendet, um die aktuell offene Liste der Workspace-Ordner abzurufen. Gibt null in der Antwort zurück, wenn nur eine einzelne Datei im Tool geöffnet ist. Gibt ein leeres Array zurück, wenn ein Workspace geöffnet ist, aber keine Ordner konfiguriert sind.
Client Capability:
- property path (optional):
workspace.workspaceFolders - property type:
boolean
Server-Fähigkeit:
- property path (optional):
workspace.workspaceFolders - property type:
WorkspaceFoldersServerCapabilities, wie folgt definiert
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;
}
Anfrage:
- Methode:
workspace/workspaceFolders - params: none
Antwort:
- result:
WorkspaceFolder[] | null, wie folgt definiert
export interface WorkspaceFolder {
/**
* The associated URI for this workspace folder.
*/
uri: URI;
/**
* The name of the workspace folder. Used to refer to this
* workspace folder in the user interface.
*/
name: string;
}
- error: code und message werden gesetzt, wenn während der
workspace/workspaceFolders-Anfrage ein Fehler auftritt
DidChangeWorkspaceFolders-Benachrichtigung ()
Seit Version 3.6.0
Die Benachrichtigung workspace/didChangeWorkspaceFolders wird vom Client an den Server gesendet, um den Server über Änderungen an der Workspace-Ordnerkonfiguration zu informieren. Ein Server kann sich für diese Benachrichtigung registrieren, indem er entweder die *Serverfähigkeit* workspace.workspaceFolders.changeNotifications verwendet oder den Mechanismus zur dynamischen Registrierung von Fähigkeiten nutzt. Um sich dynamisch für workspace/didChangeWorkspaceFolders zu registrieren, senden Sie eine client/registerCapability-Anfrage vom Server an den Client. Der Registrierungsparameter muss ein registrations-Element der folgenden Form enthalten, wobei id eine eindeutige ID ist, die zur Abmeldung der Fähigkeit verwendet wird (das Beispiel verwendet eine UUID):
{
id: "28c6150c-bd7b-11e7-abc4-cec278b6b50a",
method: "workspace/didChangeWorkspaceFolders"
}
Benachrichtigung:
- method: ‘workspace/didChangeWorkspaceFolders’
- params:
DidChangeWorkspaceFoldersParams, wie folgt definiert
export interface DidChangeWorkspaceFoldersParams {
/**
* The actual workspace folder change event.
*/
event: WorkspaceFoldersChangeEvent;
}
/**
* 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[];
}
WillCreateFiles Request ()
Die will create files-Anfrage wird vom Client an den Server gesendet, bevor Dateien tatsächlich erstellt werden, solange die Erstellung vom Client aus entweder durch eine Benutzeraktion oder durch Anwendung einer Workspace-Bearbeitung ausgelöst wird. Die Anfrage kann ein WorkspaceEdit zurückgeben, das vor der Erstellung der Dateien im Workspace angewendet wird. Daher kann das WorkspaceEdit nicht den Inhalt der zu erstellenden Dateien manipulieren. Bitte beachten Sie, dass Clients Ergebnisse verwerfen können, wenn die Berechnung der Bearbeitung zu lange dauert oder wenn ein Server bei dieser Anfrage ständig fehlschlägt. Dies geschieht, um Erstellungen schnell und zuverlässig zu halten.
Client Capability:
- Eigenschaftsname (optional):
workspace.fileOperations.willCreate - property type:
boolean
Die Fähigkeit zeigt an, dass der Client das Senden von workspace/willCreateFiles-Anfragen unterstützt.
Server-Fähigkeit:
- Eigenschaftsname (optional):
workspace.fileOperations.willCreate - Eigenschaftstyp:
FileOperationRegistrationOptions, wobeiFileOperationRegistrationOptionswie folgt definiert ist
/**
* The options to register for file operations.
*
* @since 3.16.0
*/
interface FileOperationRegistrationOptions {
/**
* The actual filters.
*/
filters: FileOperationFilter[];
}
/**
* 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';
/**
* Matching options for the file operation pattern.
*
* @since 3.16.0
*/
export interface FileOperationPatternOptions {
/**
* The pattern should be matched ignoring casing.
*/
ignoreCase?: boolean;
}
/**
* 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 zero 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;
}
/**
* 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;
}
Die Fähigkeit zeigt an, dass der Server daran interessiert ist, workspace/willCreateFiles-Anfragen zu erhalten.
Registrierungsoptionen: keine
Anfrage:
- methode: „workspace/willCreateFiles“
- parameter:
CreateFilesParamswie folgt definiert
/**
* 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[];
}
/**
* 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;
}
Antwort:
- Ergebnis:
WorkspaceEdit|null - Fehler: Code und Nachricht werden gesetzt, wenn während der
willCreateFiles-Anfrage eine Ausnahme auftritt.
DidCreateFiles Notification ()
Die `did create files`-Benachrichtigung wird vom Client an den Server gesendet, wenn Dateien vom Client aus erstellt wurden.
Client Capability:
- Eigenschaftsname (optional):
workspace.fileOperations.didCreate - property type:
boolean
Die Fähigkeit zeigt an, dass der Client das Senden von workspace/didCreateFiles-Benachrichtigungen unterstützt.
Server-Fähigkeit:
- Eigenschaftsname (optional):
workspace.fileOperations.didCreate - Eigenschaftstyp:
FileOperationRegistrationOptions
Die Fähigkeit zeigt an, dass der Server daran interessiert ist, workspace/didCreateFiles-Benachrichtigungen zu erhalten.
Benachrichtigung:
- methode: „workspace/didCreateFiles“
- parameter:
CreateFilesParams
WillRenameFiles Request ()
Die will rename files-Anfrage wird vom Client an den Server gesendet, bevor Dateien tatsächlich umbenannt werden, solange die Umbenennung vom Client aus entweder durch eine Benutzeraktion oder durch Anwendung einer Workspace-Bearbeitung ausgelöst wird. Die Anfrage kann ein WorkspaceEdit zurückgeben, das vor der Umbenennung der Dateien im Workspace angewendet wird. Bitte beachten Sie, dass Clients Ergebnisse verwerfen können, wenn die Berechnung der Bearbeitung zu lange dauert oder wenn ein Server bei dieser Anfrage ständig fehlschlägt. Dies geschieht, um Umbenennungen schnell und zuverlässig zu halten.
Client Capability:
- Eigenschaftsname (optional):
workspace.fileOperations.willRename - property type:
boolean
Die Fähigkeit zeigt an, dass der Client das Senden von workspace/willRenameFiles-Anfragen unterstützt.
Server-Fähigkeit:
- Eigenschaftsname (optional):
workspace.fileOperations.willRename - Eigenschaftstyp:
FileOperationRegistrationOptions
Die Fähigkeit zeigt an, dass der Server daran interessiert ist, workspace/willRenameFiles-Anfragen zu erhalten.
Registrierungsoptionen: keine
Anfrage:
- methode: „workspace/willRenameFiles“
- parameter:
RenameFilesParamswie folgt definiert
/**
* 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[];
}
/**
* 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;
}
Antwort:
- Ergebnis:
WorkspaceEdit|null - Fehler: Code und Nachricht werden gesetzt, wenn während der Anfrage
workspace/willRenameFileseine Ausnahme auftritt.
DidRenameFiles Notification ()
Die `did rename files`-Benachrichtigung wird vom Client an den Server gesendet, wenn Dateien vom Client aus umbenannt wurden.
Client Capability:
- Eigenschaftsname (optional):
workspace.fileOperations.didRename - property type:
boolean
Die Fähigkeit zeigt an, dass der Client das Senden von workspace/didRenameFiles-Benachrichtigungen unterstützt.
Server-Fähigkeit:
- Eigenschaftsname (optional):
workspace.fileOperations.didRename - Eigenschaftstyp:
FileOperationRegistrationOptions
Die Fähigkeit zeigt an, dass der Server daran interessiert ist, workspace/didRenameFiles-Benachrichtigungen zu erhalten.
Benachrichtigung:
- methode: „workspace/didRenameFiles“
- parameter:
RenameFilesParams
WillDeleteFiles Request ()
Die will delete files-Anfrage wird vom Client an den Server gesendet, bevor Dateien tatsächlich gelöscht werden, solange die Löschung vom Client aus entweder durch eine Benutzeraktion oder durch Anwendung einer Workspace-Bearbeitung ausgelöst wird. Die Anfrage kann ein WorkspaceEdit zurückgeben, das vor der Löschung der Dateien im Workspace angewendet wird. Bitte beachten Sie, dass Clients Ergebnisse verwerfen können, wenn die Berechnung der Bearbeitung zu lange dauert oder wenn ein Server bei dieser Anfrage ständig fehlschlägt. Dies geschieht, um Löschungen schnell und zuverlässig zu halten.
Client Capability:
- Eigenschaftsname (optional):
workspace.fileOperations.willDelete - property type:
boolean
Die Fähigkeit zeigt an, dass der Client das Senden von workspace/willDeleteFiles-Anfragen unterstützt.
Server-Fähigkeit:
- Eigenschaftsname (optional):
workspace.fileOperations.willDelete - Eigenschaftstyp:
FileOperationRegistrationOptions
Die Fähigkeit zeigt an, dass der Server daran interessiert ist, workspace/willDeleteFiles-Anfragen zu erhalten.
Registrierungsoptionen: keine
Anfrage:
- Methode:
workspace/willDeleteFiles - parameter:
DeleteFilesParamswie folgt definiert
/**
* 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[];
}
/**
* 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;
}
Antwort:
- Ergebnis:
WorkspaceEdit|null - Fehler: Code und Nachricht werden gesetzt, wenn während der Anfrage
workspace/willDeleteFileseine Ausnahme auftritt.
DidDeleteFiles Notification ()
Die `did delete files`-Benachrichtigung wird vom Client an den Server gesendet, wenn Dateien vom Client aus gelöscht wurden.
Client Capability:
- Eigenschaftsname (optional):
workspace.fileOperations.didDelete - property type:
boolean
Die Fähigkeit zeigt an, dass der Client das Senden von workspace/didDeleteFiles-Benachrichtigungen unterstützt.
Server-Fähigkeit:
- Eigenschaftsname (optional):
workspace.fileOperations.didDelete - Eigenschaftstyp:
FileOperationRegistrationOptions
Die Fähigkeit zeigt an, dass der Server daran interessiert ist, workspace/didDeleteFiles-Benachrichtigungen zu erhalten.
Benachrichtigung:
- methode: „workspace/didDeleteFiles“
- parameter:
DeleteFilesParams
DidChangeWatchedFiles-Benachrichtigung ()
Die Benachrichtigung watched files wird vom Client an den Server gesendet, wenn der Client Änderungen an Dateien und Ordnern erkennt, die vom Sprachclient überwacht werden (beachten Sie, dass der Name zwar vermuten lässt, dass nur Datei-Ereignisse gesendet werden, es sich jedoch um Dateisystem-Ereignisse handelt, die auch Ordner einschließen). Es wird empfohlen, dass sich Server für diese Dateisystem-Ereignisse über den Registrierungsmechanismus registrieren. In früheren Implementierungen haben Clients Datei-Ereignisse gesendet, ohne dass der Server aktiv danach gefragt hat.
Server dürfen ihre eigenen Mechanismen zur Überwachung von Dateisystemen ausführen und sich nicht auf Clients verlassen, um Dateisystem-Ereignisse bereitzustellen. Dies wird jedoch aus folgenden Gründen nicht empfohlen:
- Nach unserer Erfahrung ist es schwierig, die Überwachung von Dateisystemen auf der Festplatte richtig zu implementieren, insbesondere wenn sie auf mehreren Betriebssystemen unterstützt werden muss.
- Die Überwachung von Dateisystemen ist nicht kostenlos, insbesondere wenn die Implementierung eine Art Abfrage verwendet und einen Dateisystembaum im Speicher hält, um Zeitstempel zu vergleichen (wie es beispielsweise einige Node-Module tun).
- Ein Client startet normalerweise mehr als einen Server. Wenn jeder Server seine eigene Dateisystemüberwachung ausführt, kann dies zu CPU- oder Speicherproblemen führen.
- Im Allgemeinen gibt es mehr Server- als Clientimplementierungen. Dieses Problem ist daher auf der Clientseite besser gelöst.
Client Capability:
- property path (optional):
workspace.didChangeWatchedFiles - property type:
DidChangeWatchedFilesClientCapabilities, wie folgt definiert
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;
/**
* Whether the client has support for relative patterns
* or not.
*
* @since 3.17.0
*/
relativePatternSupport?: boolean;
}
Registrierungsoptionen: DidChangeWatchedFilesRegistrationOptions, wie folgt definiert
/**
* Describe options to be used when registering for file system change events.
*/
export interface DidChangeWatchedFilesRegistrationOptions {
/**
* The watchers to register.
*/
watchers: FileSystemWatcher[];
}
/**
* The glob pattern to watch relative to the base path. Glob patterns can have
* the following syntax:
* - `*` to match zero 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 conditions (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`)
*
* @since 3.17.0
*/
export type Pattern = string;
/**
* A relative pattern is a helper to construct glob patterns that are matched
* relatively to a base URI. The common value for a `baseUri` is a workspace
* folder root, but it can be another absolute URI as well.
*
* @since 3.17.0
*/
export interface RelativePattern {
/**
* A workspace folder or a base URI to which this pattern will be matched
* against relatively.
*/
baseUri: WorkspaceFolder | URI;
/**
* The actual glob pattern;
*/
pattern: Pattern;
}
/**
* The glob pattern. Either a string pattern or a relative pattern.
*
* @since 3.17.0
*/
export type GlobPattern = Pattern | RelativePattern;
export interface FileSystemWatcher {
/**
* The glob pattern to watch. See {@link GlobPattern glob pattern}
* for more detail.
*
* @since 3.17.0 support for relative patterns.
*/
globPattern: GlobPattern;
/**
* The kind of events of interest. If omitted it defaults
* to WatchKind.Create | WatchKind.Change | WatchKind.Delete
* which is 7.
*/
kind?: WatchKind;
}
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;
}
export type WatchKind = uinteger;
Benachrichtigung:
- method: ‘workspace/didChangeWatchedFiles’
- params:
DidChangeWatchedFilesParams, wie folgt definiert
interface DidChangeWatchedFilesParams {
/**
* The actual file events.
*/
changes: FileEvent[];
}
Dabei sind FileEvents wie folgt beschrieben
/**
* An event describing a file change.
*/
interface FileEvent {
/**
* The file's URI.
*/
uri: DocumentUri;
/**
* The change type.
*/
type: FileChangeType;
}
/**
* 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;
}
export type FileChangeType = 1 | 2 | 3;
Führe einen Befehl aus ()
Die Anfrage workspace/executeCommand wird vom Client an den Server gesendet, um die Befehlsausführung auf dem Server auszulösen. In den meisten Fällen erstellt der Server eine WorkspaceEdit-Struktur und wendet die Änderungen auf den Workspace mithilfe der Anfrage workspace/applyEdit an, die vom Server an den Client gesendet wird.
Client Capability:
- Eigenschaftspfad (optional):
workspace.executeCommand - Eigenschaftstyp:
ExecuteCommandClientCapabilitieswie folgt definiert
export interface ExecuteCommandClientCapabilities {
/**
* Execute command supports dynamic registration.
*/
dynamicRegistration?: boolean;
}
Server-Fähigkeit:
- Eigenschaftspfad (optional):
executeCommandProvider - Eigenschaftstyp:
ExecuteCommandOptionswie folgt definiert
export interface ExecuteCommandOptions extends WorkDoneProgressOptions {
/**
* The commands to be executed on the server
*/
commands: string[];
}
Registrierungsoptionen: ExecuteCommandRegistrationOptions wie folgt definiert
/**
* Execute command registration options.
*/
export interface ExecuteCommandRegistrationOptions
extends ExecuteCommandOptions {
}
Anfrage:
- methode: „workspace/executeCommand“
- parameter:
ExecuteCommandParamswie folgt definiert
export interface ExecuteCommandParams extends WorkDoneProgressParams {
/**
* The identifier of the actual command handler.
*/
command: string;
/**
* Arguments that the command should be invoked with.
*/
arguments?: LSPAny[];
}
Die Argumente werden typischerweise angegeben, wenn ein Befehl vom Server an den Client zurückgegeben wird. Beispielanfragen, die einen Befehl zurückgeben, sind textDocument/codeAction oder textDocument/codeLens.
Antwort:
- Ergebnis:
LSPAny - error: code und message werden gesetzt, wenn während der Anfrage ein Fehler auftritt.
Wendet einen WorkspaceEdit an ()
Die Anfrage workspace/applyEdit wird vom Server an den Client gesendet, um Ressourcen auf der Clientseite zu ändern.
Client Capability:
- Eigenschaftspfad (optional):
workspace.applyEdit - property type:
boolean
Siehe auch die WorkspaceEditClientCapabilities für die unterstützten Fähigkeiten eines Workspace-Edits.
Anfrage:
- methode: „workspace/applyEdit“
- parameter:
ApplyWorkspaceEditParamswie folgt definiert
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;
}
Antwort:
- Ergebnis:
ApplyWorkspaceEditResult, wie folgt definiert:
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 und message werden gesetzt, wenn während der Anfrage ein Fehler auftritt.
Fensterfunktionen
ShowMessage-Benachrichtigung ()
Die show message-Benachrichtigung wird von einem Server an einen Client gesendet, um den Client aufzufordern, eine bestimmte Nachricht in der Benutzeroberfläche anzuzeigen.
Benachrichtigung:
- method: ‘window/showMessage’
- params:
ShowMessageParams, wie folgt definiert
interface ShowMessageParams {
/**
* The message type. See {@link MessageType}.
*/
type: MessageType;
/**
* The actual message.
*/
message: string;
}
Dabei ist der Typ wie folgt definiert
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;
/**
* A debug message.
*
* @since 3.18.0
* @proposed
*/
export const Debug = 5;
}
export type MessageType = 1 | 2 | 3 | 4 | 5;
ShowMessage-Anfrage ()
Die show message request-Anfrage wird von einem Server an einen Client gesendet, um den Client aufzufordern, eine bestimmte Nachricht in der Benutzeroberfläche anzuzeigen. Neben der show message-Benachrichtigung ermöglicht die Anfrage, Aktionen zu übergeben und auf eine Antwort vom Client zu warten.
Client Capability:
- property path (optional):
window.showMessage - property type:
ShowMessageRequestClientCapabilities, wie folgt definiert
/**
* 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;
};
}
Anfrage:
- method: ‘window/showMessageRequest’
- params:
ShowMessageRequestParams, wie folgt definiert
interface ShowMessageRequestParams {
/**
* The message type. See {@link MessageType}
*/
type: MessageType;
/**
* The actual message
*/
message: string;
/**
* The message action items to present.
*/
actions?: MessageActionItem[];
}
Dabei ist das MessageActionItem wie folgt definiert
interface MessageActionItem {
/**
* A short title like 'Retry', 'Open Log' etc.
*/
title: string;
}
Antwort:
- result: das ausgewählte
MessageActionItem|null, wenn keines ausgewählt wurde. - error: code und message werden gesetzt, wenn während der Anzeige einer Nachricht ein Fehler auftritt.
ShowDocument-Anfrage ()
Neu ab Version 3.16.0
Die show document-Anfrage wird von einem Server an einen Client gesendet, um den Client aufzufordern, eine bestimmte Ressource, die durch eine URI referenziert wird, in der Benutzeroberfläche anzuzeigen.
Client Capability:
- property path (optional):
window.showDocument - property type:
ShowDocumentClientCapabilities, wie folgt definiert
/**
* 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;
}
Anfrage:
- method: ‘window/showDocument’
- params:
ShowDocumentParams, wie folgt definiert
/**
* Params to show a resource.
*
* @since 3.16.0
*/
export interface ShowDocumentParams {
/**
* The uri to show.
*/
uri: URI;
/**
* Indicates to show the resource in an external program.
* To show, for example, `https://visualstudiocode.de/`
* 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;
}
Antwort:
- result:
ShowDocumentResult, wie folgt definiert
/**
* 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 und message werden gesetzt, wenn während der Anzeige eines Dokuments ein Fehler auftritt.
LogMessage-Benachrichtigung ()
Die log message-Benachrichtigung wird vom Server an den Client gesendet, um den Client aufzufordern, eine bestimmte Nachricht zu protokollieren.
Benachrichtigung:
- method: ‘window/logMessage’
- params:
LogMessageParams, wie folgt definiert
interface LogMessageParams {
/**
* The message type. See {@link MessageType}
*/
type: MessageType;
/**
* The actual message
*/
message: string;
}
Fortschritt bei der Arbeit erstellen ()
Die window/workDoneProgress/create-Anfrage wird vom Server an den Client gesendet, um den Client aufzufordern, einen Work Done-Fortschritt zu erstellen.
Client Capability:
- Eigenschaftsname (optional):
window.workDoneProgress - property type:
boolean
Anfrage:
- method: ‘window/workDoneProgress/create’
- params:
WorkDoneProgressCreateParams, wie folgt definiert
export interface WorkDoneProgressCreateParams {
/**
* The token to be used to report progress.
*/
token: ProgressToken;
}
Antwort:
- result: void
- error: code und message werden gesetzt, wenn während der
window/workDoneProgress/create-Anfrage ein Fehler auftritt. Bei einem Fehler darf der Server keine Fortschrittsbenachrichtigung mit dem inWorkDoneProgressCreateParamsbereitgestellten Token senden.
Fortschritt bei der Arbeit abbrechen ()
Die Benachrichtigung window/workDoneProgress/cancel wird vom Client an den Server gesendet, um einen auf Serverseite mit window/workDoneProgress/create initiierten Fortschritt abzubrechen. Der Fortschritt muss nicht als cancellable markiert sein, um abgebrochen zu werden, und ein Client kann einen Fortschritt aus beliebigen Gründen abbrechen: bei einem Fehler, beim Neuladen eines Workspaces usw.
Benachrichtigung:
- method: ‘window/workDoneProgress/cancel’
- params:
WorkDoneProgressCancelParams, wie folgt definiert
export interface WorkDoneProgressCancelParams {
/**
* The token to be used to report progress.
*/
token: ProgressToken;
}
Telemetry-Benachrichtigung ()
Die telemetry-Benachrichtigung wird vom Server an den Client gesendet, um den Client aufzufordern, ein Telemetrieereignis zu protokollieren. Das Protokoll spezifiziert die Nutzlast nicht, da keine Interpretation der Daten im Protokoll stattfindet. Die meisten Clients verarbeiten das Ereignis nicht direkt, sondern leiten es an die Erweiterungen weiter, denen der entsprechende Server gehört, der das Ereignis auslöst.
Benachrichtigung:
- method: ‘telemetry/event’
- Parameter:
object | array;
Sonstiges
Implementierungsüberlegungen
Sprachserver laufen normalerweise in einem separaten Prozess und Clients kommunizieren asynchron mit ihnen. Darüber hinaus erlauben Clients Benutzern normalerweise, mit dem Quellcode zu interagieren, auch wenn Anforderungsergebnisse ausstehen. Wir empfehlen das folgende Implementierungsmuster, um zu vermeiden, dass Clients veraltete Antwortresultate anwenden
- Wenn ein Client eine Anfrage an den Server sendet und sich der Client-Zustand auf eine Weise ändert, die die Antwort ungültig macht, sollte er Folgendes tun:
- die Serveranfrage abbrechen und das Ergebnis ignorieren, wenn das Ergebnis für den Client nicht mehr nützlich ist. Bei Bedarf sollte der Client die Anfrage erneut senden.
- die Anfrage weiterlaufen lassen, wenn der Client das Ergebnis noch nutzen kann, z. B. indem er es in ein neues Ergebnis umwandelt, indem er die Zustandsänderung auf das Ergebnis anwendet.
- Server sollten daher nicht eigenmächtig entscheiden, Anfragen abzubrechen, nur weil eine Benachrichtigung über eine Zustandsänderung in der Warteschlange erkannt wird. Wie gesagt, das Ergebnis könnte für den Client immer noch nützlich sein.
- Wenn ein Server eine interne Zustandsänderung erkennt (z. B. ein Projektkontext hat sich geändert), die das Ergebnis einer laufenden Anfrage ungültig macht, kann der Server diese Anfragen mit
ContentModifiedablehnen. Wenn Clients einenContentModified-Fehler erhalten, sollten sie ihn im Allgemeinen nicht für den Endbenutzer in der Benutzeroberfläche anzeigen. Clients können die Anfrage erneut senden, wenn sie wissen, wie das geht. Es ist zu beachten, dass es für alle positionsbasierten Anfragen für Clients besonders schwierig sein kann, eine Anfrage neu zu gestalten. - Ein Client sollte keine Resolve-Anfragen für veraltete Objekte (z. B. Code-Lenses, ...) senden. Wenn ein Server eine Resolve-Anfrage für ein veraltetes Objekt erhält, kann der Server diese Anfragen mit
ContentModifiedablehnen. - Wenn ein Client feststellt, dass ein Server unerwartet beendet wird, sollte er versuchen, den Server neu zu starten. Clients sollten jedoch vorsichtig sein, einen abstürzenden Server nicht endlos neu zu starten. VS Code startet beispielsweise keinen Server neu, der 5 Mal in den letzten 180 Sekunden abgestürzt ist.
Server unterstützen normalerweise verschiedene Kommunikationskanäle (z. B. stdio, Pipes, ...). Um die Verwendung von Servern in verschiedenen Clients zu erleichtern, wird dringend empfohlen, dass eine Serverimplementierung die folgenden Kommandozeilenargumente unterstützt, um den Kommunikationskanal auszuwählen:
- stdio: verwendet stdio als Kommunikationskanal.
-
pipe: verwendet Pipes (Windows) oder Socket-Dateien (Linux, Mac) als Kommunikationskanal. Der Pipe-/Socket-Dateiname wird als nächstes Argument oder mit
--pipe=übergeben. -
socket: verwendet einen Socket als Kommunikationskanal. Der Port wird als nächstes Argument oder mit
--port=übergeben. - node-ipc: verwendet Node IPC-Kommunikation zwischen Client und Server. Dies wird nur unterstützt, wenn Client und Server unter Node laufen.
Um den Fall zu unterstützen, dass der Editor, der einen Server startet, abstürzt, sollte der Editor auch seine Prozess-ID an den Server übergeben. Dies ermöglicht es dem Server, den Editorprozess zu überwachen und sich selbst herunterzufahren, wenn der Editorprozess abstirbt. Die übergebene Prozess-ID auf der Kommandozeile sollte dieselbe sein wie die in den Initialisierungsparametern übergebene. Das zu verwendende Kommandozeilenargument ist --clientProcessId.
Meta-Modell
Seit 3.17 gibt es ein Metamodell, das das LSP-Protokoll beschreibt:
- metaModel.json: Das eigentliche Metamodell für die LSP 3.17-Spezifikation
- metaModel.ts: Eine TypeScript-Datei, die die Datentypen definiert, aus denen das Metamodell besteht.
- metaModel.schema.json: Eine JSON-Schema-Datei, die die Datentypen definiert, aus denen das Metamodell besteht. Kann verwendet werden, um Code zum Lesen der Metamodell-JSON-Datei zu generieren.
Änderungsprotokoll
3.17.0 (05/10/2022)
- Geben Sie an, wie Clients veraltete Anfragen behandeln.
- Unterstützung für Details zur Bezeichnung von Vervollständigungselementen hinzufügen.
- Unterstützung für die Auflösung von Workspace-Symbolen hinzufügen.
- Unterstützung für Bezeichnungsdetails und Einfügetextmodus für Vervollständigungselemente hinzufügen.
- Unterstützung für gemeinsame Werte in CompletionItemList hinzufügen.
- Unterstützung für HTML-Tags in Markdown hinzufügen.
- Unterstützung für zusammengeklappten Text beim Falten hinzufügen.
- Unterstützung für Trigger-Arten bei Code-Aktionsanfragen hinzufügen.
- Fügen Sie der semantischen Token-Unterstützung Folgendes hinzu:
- serverseitig abbrechbar
- Erweiterung von Syntax-Token
- Unterstützung für die Aushandlung der Positionskodierung hinzufügen.
- Unterstützung für relative Muster in Dateibewachern hinzufügen.
- Unterstützung für Typenhierarchien hinzufügen
- Unterstützung für Inline-Werte hinzufügen.
- Unterstützung für Inlay-Hinweise hinzufügen.
- Unterstützung für Notebook-Dokumente hinzufügen.
- Unterstützung für das Diagnose-Pull-Modell hinzufügen.
3.16.0 (12/14/2020)
- Unterstützung für Tracing hinzufügen.
- Unterstützung für semantische Token hinzufügen.
- Unterstützung für Aufrufhierarchien hinzufügen.
- Client-Fähigkeit zum Auflösen von Textbearbeitungen für Vervollständigungselemente hinzufügen.
- Unterstützung für clientseitiges Standardverhalten bei Umbenennungen hinzufügen.
- Unterstützung für Einfüge- und Ersetzungsbereiche in
CompletionItemhinzufügen. - Unterstützung für Diagnose-Codebeschreibungen hinzufügen.
- Unterstützung für Bezeichnungen von Dokument-Symbol-Providern hinzufügen.
- Unterstützung für Tags in
SymbolInformationundDocumentSymbolhinzufügen. - Unterstützung für die Moniker-Anfragemethode hinzufügen.
- Unterstützung für die
data-Eigenschaft von Code-Aktionen hinzufügen. - Unterstützung für die
disabled-Eigenschaft von Code-Aktionen hinzufügen. - Unterstützung für Code-Aktions-Resolve-Anfragen hinzufügen.
- Unterstützung für die
data-Eigenschaft von Diagnosen hinzufügen. - Unterstützung für die
activeParameter-Eigenschaft von Signaturinformationen hinzufügen. - Unterstützung für
workspace/didCreateFiles-Benachrichtigungen undworkspace/willCreateFiles-Anfragen hinzufügen. - Unterstützung für
workspace/didRenameFiles-Benachrichtigungen undworkspace/willRenameFiles-Anfragen hinzufügen. - Unterstützung für
workspace/didDeleteFiles-Benachrichtigungen undworkspace/willDeleteFiles-Anfragen hinzufügen. - Client-Fähigkeit hinzufügen, um zu signalisieren, ob der Client Zeilenumbrüche normalisiert.
- Unterstützung zum Beibehalten zusätzlicher Attribute in
MessageActionItemhinzufügen. - Unterstützung zur Bereitstellung der Client-Lokalisierung im
initialize-Aufruf hinzufügen. - Unterstützung zum Öffnen und Anzeigen eines Dokuments in der Client-Benutzeroberfläche hinzufügen.
- Unterstützung für verknüpftes Bearbeiten hinzufügen.
- Unterstützung für Änderungsanmerkungen in Textbearbeitungen sowie bei Vorgängen zum Erstellen, Umbenennen und Löschen von Dateien hinzufügen.
3.15.0 (01/14/2020)
- Unterstützung für generisches Fortschrittsreporting hinzufügen.
- Unterstützung für spezifisches Work-Done-Fortschrittsreporting für Anfragen hinzufügen, wo zutreffend.
- Unterstützung für spezifisches Partials-Result-Fortschrittsreporting für Anfragen hinzufügen, wo zutreffend.
- Unterstützung für
textDocument/selectionRangehinzufügen. - Unterstützung für Server- und Client-Informationen hinzufügen.
- Hinzufügen des Signature Help Contexts.
- Erlangen und Elixir zur Liste der unterstützten Programmiersprachen hinzufügen
- Hinzufügen von
versionzuPublishDiagnosticsParams - Unterstützung für
CodeAction#isPreferredhinzufügen. - Unterstützung für
CompletionItem#taghinzufügen. - Unterstützung für
Diagnostic#taghinzufügen. - Unterstützung für
DocumentLink#tooltiphinzufügen. - Hinzufügen von
trimTrailingWhitespace,insertFinalNewlineundtrimFinalNewlineszuFormattingOptions. - Klärung des Parameters
WorkspaceSymbolParams#query.
3.14.0 (12/13/2018)
- Unterstützung für Signature-Label-Offsets hinzufügen.
- Unterstützung für Location Links hinzufügen.
- Unterstützung für die
textDocument/declaration-Anfrage hinzufügen.
3.13.0 (9/11/2018)
- Unterstützung für Datei- und Ordneroperationen (Erstellen, Umbenennen, Verschieben) zu Workspace-Edits hinzufügen.
3.12.0 (8/23/2018)
- Unterstützung für die
textDocument/prepareRename-Anfrage hinzufügen.
3.11.0 (8/21/2018)
- Unterstützung für
CodeActionOptionshinzufügen, damit ein Server eine Liste der unterstützten Code-Aktionen bereitstellen kann.
3.10.0 (7/23/2018)
- Unterstützung für hierarchische Dokumentensymbole als gültige Antwort auf eine
textDocument/documentSymbol-Anfrage hinzufügen. - Unterstützung für Faltenbereiche als gültige Antwort auf eine
textDocument/foldingRange-Anfrage hinzufügen.
3.9.0 (7/10/2018)
- Unterstützung für die
preselect-Eigenschaft inCompletionItemhinzufügen
3.8.0 (6/11/2018)
- Unterstützung für CodeAction-Literale für die
textDocument/codeAction-Anfrage hinzugefügt. - ColorServerCapabilities.colorProvider kann auch ein Boolean sein
- ColorPresentationParams.colorInfo korrigiert zu color (wie in der
d.tsund in Implementierungen)
3.7.0 (4/5/2018)
- Verwandte Informationen zu Diagnostics hinzugefügt.
3.6.0 (2/22/2018)
Zusammenführung des vorgeschlagenen Protokolls für Workspace-Ordner, Konfiguration, Go-to-Type-Definition, Go-to-Implementierung und Document-Color-Provider in den Hauptzweig der Spezifikation. Details siehe
- Workspace-Ordner abrufen
- DidChangeWorkspaceFolders Benachrichtigung
- Konfiguration abrufen
- Go to Type Definition
- Go to Implementation
- Document Color
- Color Presentation
Zusätzlich haben wir CompletionTriggerKind um einen neuen Wert TriggerForIncompleteCompletions: 3 = 3 erweitert, um zu signalisieren, dass eine Completion-Anfrage ausgelöst wurde, seit das letzte Ergebnis unvollständig war.
3.5.0
Entscheidung, diese Version zu überspringen, um die Protokollversionsnummer mit dem npm-Modul vscode-languageserver-protocol in Einklang zu bringen.
3.4.0 (11/27/2017)
3.3.0 (11/24/2017)
- Unterstützung für
CompletionContexthinzugefügt - Unterstützung für
MarkupContenthinzugefügt - Alte New- und Updated-Marker entfernt.
3.2.0 (09/26/2017)
- Optionales
commitCharacters-Property zurCompletionItemhinzugefügt
3.1.0 (02/28/2017)
- Die Änderungen an
WorkspaceEditrückwärtskompatibel gemacht. - Die Spezifikation aktualisiert, um die Breaking Changes von 2.x zu 3.x bezüglich
WorkspaceEditundTextDocumentEditkorrekt zu beschreiben.
3.0 Version
- Hinzufügen von Unterstützung für Client-Feature-Flags, damit Server sich an unterschiedliche Client-Capabilities anpassen können. Ein Beispiel ist die neue
textDocument/willSaveWaitUntil-Anfrage, die nicht alle Clients unterstützen können. Wenn das Feature in den Client-Capabilities, die bei der initialisieren-Anfrage gesendet werden, deaktiviert ist, kann sich der Server nicht darauf verlassen, die Anfrage zu erhalten. - Unterstützung für das Experimentieren mit neuen Features hinzufügen. Der neue Abschnitt
ClientCapabilities.experimentalzusammen mit Feature-Flags ermöglicht es Servern, experimentelle Features bereitzustellen, ohne dass ALLE Clients diese sofort annehmen müssen. - Server können dynamischer auf Client-Funktionen reagieren. Fähigkeiten können jetzt nach der initialisieren-Anfrage mit den neuen
client/registerCapabilityundclient/unregisterCapabilityregistriert und deregistriert werden. Dies ermöglicht es Servern beispielsweise, ohne Neustart auf Einstellungs- oder Konfigurationsänderungen zu reagieren. - Unterstützung für die Benachrichtigung
textDocument/willSaveund die AnfragetextDocument/willSaveWaitUntilhinzufügen. - Unterstützung für die Anfrage
textDocument/documentLinkhinzufügen. - Fügen Sie eine
rootUri-Eigenschaft zu den initializeParams hinzu, zugunsten derrootPath-Eigenschaft.