This document describes LSP extensions used by rust-analyzer. It's a best effort document, when in doubt, consult the source (and send a PR with clarification ;-) ). We aim to upstream all non Rust-specific extensions to the protocol, but this is not a top priority. All capabilities are enabled via experimental
field of ClientCapabilities
or ServerCapabilities
. Requests which we hope to upstream live under experimental/
namespace. Requests, which are likely to always remain specific to rust-analyzer
are under rust-analyzer/
namespace.
If you want to be notified about the changes to this document, subscribe to #4604.
rust-analyzer supports clangd's extension for opting into UTF-8 as the coordinate space for offsets (by default, LSP uses UTF-16 offsets).
https://clangd.llvm.org/extensions.html#utf-8-offsets
initializationOptions
For initializationOptions
, rust-analyzer
expects "rust-analyzer"
section of the configuration. That is, rust-analyzer
usually sends "workspace/configuration"
request with { "items": ["rust-analyzer"] }
payload. initializationOptions
should contain the same data that would be in the first item of the result. If a language client does not know about rust-analyzer
's configuration options it can get sensible defaults by doing any of the following:
initializationOptions
"initializationOptions": null
"initializationOptions": {}
TextEdit
Issue: https://github.com/microsoft/language-server-protocol/issues/724
Client Capability: { "snippetTextEdit": boolean }
If this capability is set, WorkspaceEdit
s returned from codeAction
requests might contain SnippetTextEdit
s instead of usual TextEdit
s:
interface SnippetTextEdit extends TextEdit { insertTextFormat?: InsertTextFormat; }
export interface TextDocumentEdit { textDocument: OptionalVersionedTextDocumentIdentifier; edits: (TextEdit | SnippetTextEdit)[]; }
When applying such code action, the editor should insert snippet, with tab stops and placeholder. At the moment, rust-analyzer guarantees that only a single edit will have InsertTextFormat.Snippet
.
“Add derive
” code action transforms struct S;
into #[derive($0)] struct S;
SnippetTextEdit
s allowed (only in code actions at the moment)?CodeAction
GroupsIssue: https://github.com/microsoft/language-server-protocol/issues/994
Client Capability: { "codeActionGroup": boolean }
If this capability is set, CodeAction
returned from the server contain an additional field, group
:
interface CodeAction { title: string; group?: string; ... }
All code-actions with the same group
should be grouped under single (extendable) entry in lightbulb menu. The set of actions [ { title: "foo" }, { group: "frobnicate", title: "bar" }, { group: "frobnicate", title: "baz" }]
should be rendered as
💡 +-------------+ | foo | +-------------+-----+ | frobnicate >| bar | +-------------+-----+ | baz | +-----+
Alternatively, selecting frobnicate
could present a user with an additional menu to choose between bar
and baz
.
fn main() { let x: Entry/*cursor here*/ = todo!(); }
Invoking code action at this position will yield two code actions for importing Entry
from either collections::HashMap
or collection::BTreeMap
, grouped under a single “import” group.
Issue: https://github.com/microsoft/language-server-protocol/issues/1002
Server Capability: { "parentModule": boolean }
This request is sent from client to server to handle “Goto Parent Module” editor action.
Method: experimental/parentModule
Request: TextDocumentPositionParams
Response: Location | Location[] | LocationLink[] | null
// src/main.rs mod foo; // src/foo.rs /* cursor here*/
experimental/parentModule
returns a single Link
to the mod foo;
declaration.
Issue: https://github.com/microsoft/language-server-protocol/issues/992
Server Capability: { "joinLines": boolean }
This request is sent from client to server to handle “Join Lines” editor action.
Method: experimental/joinLines
Request:
interface JoinLinesParams { textDocument: TextDocumentIdentifier, /// Currently active selections/cursor offsets. /// This is an array to support multiple cursors. ranges: Range[], }
Response: TextEdit[]
fn main() { /*cursor here*/let x = { 92 }; }
experimental/joinLines
yields (curly braces are automagically removed)
fn main() { let x = 92; }
joinLines
? Currently this is left to editor's discretion, but it might be useful to specify on the server via snippets. However, it then becomes unclear how it works with multi cursor.Issue: https://github.com/microsoft/language-server-protocol/issues/1001
Server Capability: { "onEnter": boolean }
This request is sent from client to server to handle Enter keypress.
Method: experimental/onEnter
Request:: TextDocumentPositionParams
Response:
SnippetTextEdit[]
fn main() { // Some /*cursor here*/ docs let x = 92; }
experimental/onEnter
returns the following snippet
fn main() { // Some // $0 docs let x = 92; }
The primary goal of onEnter
is to handle automatic indentation when opening a new line. This is not yet implemented. The secondary goal is to handle fixing up syntax, like continuing doc strings and comments, and escaping \n
in string literals.
As proper cursor positioning is raison-d'etat for onEnter
, it uses SnippetTextEdit
.
onEnter
?Server Capability: { "ssr": boolean }
This request is sent from client to server to handle structural search replace -- automated syntax tree based transformation of the source.
Method: experimental/ssr
Request:
interface SsrParams { /// Search query. /// The specific syntax is specified outside of the protocol. query: string, /// If true, only check the syntax of the query and don't compute the actual edit. parseOnly: bool, /// The current text document. This and `position` will be used to determine in what scope /// paths in `query` should be resolved. textDocument: lc.TextDocumentIdentifier; /// Position where SSR was invoked. position: lc.Position; }
Response:
WorkspaceEdit
SSR with query foo($a, $b) ==>> ($a).foo($b)
will transform, eg foo(y + 5, z)
into (y + 5).foo(z)
.
Issue: https://github.com/microsoft/language-server-protocol/issues/999
Server Capability: { "matchingBrace": boolean }
This request is sent from client to server to handle “Matching Brace” editor action.
Method: experimental/matchingBrace
Request:
interface MatchingBraceParams { textDocument: TextDocumentIdentifier, /// Position for each cursor positions: Position[], }
Response:
Position[]
fn main() { let x: Vec<()>/*cursor here*/ = vec![] }
experimental/matchingBrace
yields the position of <
. In many cases, matching braces can be handled by the editor. However, some cases (like disambiguating between generics and comparison operations) need a real parser. Moreover, it would be cool if editors didn't need to implement even basic language parsing
SelectionRange
request works.SelectionRange
s as being brace pairs?Issue: https://github.com/microsoft/language-server-protocol/issues/944
Server Capability: { "runnables": { "kinds": string[] } }
This request is sent from client to server to get the list of things that can be run (tests, binaries, cargo check -p
).
Method: experimental/runnables
Request:
interface RunnablesParams { textDocument: TextDocumentIdentifier; /// If null, compute runnables for the whole file. position?: Position; }
Response: Runnable[]
interface Runnable { label: string; /// If this Runnable is associated with a specific function/module, etc, the location of this item location?: LocationLink; /// Running things is necessary technology specific, `kind` needs to be advertised via server capabilities, // the type of `args` is specific to `kind`. The actual running is handled by the client. kind: string; args: any; }
rust-analyzer supports only one kind
, "cargo"
. The args
for "cargo"
look like this:
{ workspaceRoot?: string; cargoArgs: string[]; cargoExtraArgs: string[]; executableArgs: string[]; expectTest?: boolean; overrideCargo?: string; }
This request is sent from client to server to get a URL to documentation for the symbol under the cursor, if available.
Method experimental/externalDocs
Request:: TextDocumentPositionParams
Response string | null
Method: rust-analyzer/analyzerStatus
Request:
interface AnalyzerStatusParams { /// If specified, show dependencies of the current file. textDocument?: TextDocumentIdentifier; }
Response: string
Returns internal status message, mostly for debugging purposes.
Method: rust-analyzer/reloadWorkspace
Request: null
Response: null
Reloads project information (that is, re-executes cargo metadata
).
Client Capability: { "statusNotification": boolean }
Method: rust-analyzer/status
Notification:
interface StatusParams { status: "loading" | "readyPartial" | "ready" | "invalid" | "needsReload", }
This notification is sent from server to client. The client can use it to display persistent status to the user (in modline). For needsReload
state, the client can provide a context-menu action to run rust-analyzer/reloadWorkspace
request.
Method: rust-analyzer/syntaxTree
Request:
interface SyntaxTeeParams { textDocument: TextDocumentIdentifier, range?: Range, }
Response: string
Returns textual representation of a parse tree for the file/selected region. Primarily for debugging, but very useful for all people working on rust-analyzer itself.
Method: rust-analyzer/viewHir
Request: TextDocumentPositionParams
Response: string
Returns a textual representation of the HIR of the function containing the cursor. For debugging or when working on rust-analyzer itself.
Method: rust-analyzer/expandMacro
Request:
interface ExpandMacroParams { textDocument: TextDocumentIdentifier, position: Position, }
Response:
interface ExpandedMacro { name: string, expansion: string, }
Expands macro call at a given position.
Method: rust-analyzer/inlayHints
This request is sent from client to server to render “inlay hints” -- virtual text inserted into editor to show things like inferred types. Generally, the client should re-query inlay hints after every modification. Note that we plan to move this request to experimental/inlayHints
, as it is not really Rust-specific, but the current API is not necessary the right one. Upstream issue: https://github.com/microsoft/language-server-protocol/issues/956
Request:
interface InlayHintsParams { textDocument: TextDocumentIdentifier, }
Response: InlayHint[]
interface InlayHint { kind: "TypeHint" | "ParameterHint" | "ChainingHint", range: Range, label: string, }
Client Capability: { "hoverActions": boolean }
If this capability is set, Hover
request returned from the server might contain an additional field, actions
:
interface Hover { ... actions?: CommandLinkGroup[]; } interface CommandLink extends Command { /** * A tooltip for the command, when represented in the UI. */ tooltip?: string; } interface CommandLinkGroup { title?: string; commands: CommandLink[]; }
Such actions on the client side are appended to a hover bottom as command links:
+-----------------------------+ | Hover content | | | +-----------------------------+ | _Action1_ | _Action2_ | <- first group, no TITLE +-----------------------------+ | TITLE _Action1_ | _Action2_ | <- second group +-----------------------------+ ...
Issue: https://github.com/rust-analyzer/rust-analyzer/issues/6462
This request is sent from client to server to open the current project's Cargo.toml
Method: experimental/openCargoToml
Request: OpenCargoTomlParams
Response: Location | null
// Cargo.toml [package] // src/main.rs /* cursor here*/
experimental/openCargoToml
returns a single Link
to the start of the [package]
keyword.