Skip to main content

Crate lsp_lang

Crate lsp_lang 

Source
Expand description

§lsp_lang

Language Server Protocol scaffolding for the -lang family: everything a language server needs that is not about the language itself, on the family’s own stack. There are no third-party dependencies: the transport is rpc_io, the JSON is jsonx_lib, documents are reparsed by incremental_lang, and diagnostics come from diag_lang.

A language server spends most of its code on plumbing: framing JSON-RPC over stdio, the initialize/shutdown/exit handshake, keeping a copy of every open file in step with the editor, converting UTF-16 positions to byte offsets and back, and turning compiler diagnostics into protocol diagnostics. This crate does all of that, so a server built on it is a grammar and a handler:

  • an incremental_lang::Grammar, which parses each open document, and reparses only the node around each edit as the user types;
  • a Handler, which publishes diag_lang::Diagnostics as documents change and answers the requests the language supports. Each method has a default, so a handler implements only what it offers, and the capabilities the server advertises come from what the handler lists in Handler::features.

§The pieces

§Example

A server that reports every TODO in a document as a warning. The grammar here treats a whole document as one token; a real language supplies its own (see incremental_lang::Grammar).

use lsp_lang::incremental_lang::{Builder, Grammar, Span, Token, TokenKind};
use lsp_lang::diag_lang::{Label, Severity};
use lsp_lang::{Context, Diagnostic, Document, Handler, Server};

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
enum K { Root, Text }
impl TokenKind for K {}

#[derive(Clone)]
struct Plain;

impl Grammar for Plain {
    type Kind = K;
    const ROOT: K = K::Root;
    fn lex(&self, text: &str, tokens: &mut Vec<Token<K>>) {
        if !text.is_empty() {
            tokens.push(Token::new(K::Text, Span::new(0, text.len() as u32)));
        }
    }
    fn parse(&self, _: K, b: &mut Builder<'_, K>) {
        b.start(K::Root);
        while !b.at_end() { b.bump(); }
        b.finish();
    }
}

struct Todos;

impl Handler<Plain> for Todos {
    fn changed(&mut self, doc: &Document<Plain>, cx: &mut Context<'_, Plain>) {
        let found: Vec<Diagnostic> = doc
            .text()
            .match_indices("TODO")
            .map(|(at, _)| {
                let span = Span::new(at as u32, at as u32 + 4);
                Diagnostic::new(Severity::Warning, "unfinished work", Label::new(span, "here"))
            })
            .collect();
        cx.publish_diagnostics(doc, &found);
    }
}

// Drive one session from memory, as an editor would over stdio.
fn frame(json: &str) -> String {
    format!("Content-Length: {}\r\n\r\n{json}", json.len())
}
let input = [
    frame(r#"{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}"#),
    frame(r#"{"jsonrpc":"2.0","method":"textDocument/didOpen","params":{"textDocument":
        {"uri":"file:///notes.txt","languageId":"text","version":1,"text":"ship it\nTODO: tests"}}}"#),
    frame(r#"{"jsonrpc":"2.0","id":2,"method":"shutdown"}"#),
    frame(r#"{"jsonrpc":"2.0","method":"exit"}"#),
]
.concat();

let mut output = Vec::new();
Server::new(Plain, Todos).run(input.as_bytes(), &mut output)?;

let output = String::from_utf8_lossy(&output);
assert!(output.contains(r#""method":"textDocument/publishDiagnostics""#));
assert!(output.contains(r#""range":{"start":{"line":1,"character":0},"end":{"line":1,"character":4}}"#));

§Positions

The protocol counts columns in UTF-16 code units by default; the rest of the family counts byte offsets. Document converts between the two in the encoding negotiated at initialize: UTF-8 whenever the client offers it, since byte columns convert without scanning, and UTF-16 otherwise. Line breaks are \n, \r\n, and lone \r, as the protocol specifies. Out-of-range positions are clamped the way the protocol prescribes rather than rejected, and a column inside a character (between the halves of a surrogate pair) rounds down to its start.

§Diagnostics

Context::publish_diagnostics takes diag_lang diagnostics as any stage of a -lang front end produces them (their spans are byte offsets into the document) and writes textDocument/publishDiagnostics directly:

diag-langProtocol
primary label’s spanrange
Error, Warning, Note, Helpseverity 1, 2, 3, 4
message, primary label, notes, helpmessage, one part per line (note: …, help: …)
secondary labelsrelatedInformation in the same document

§Cancellation

$/cancelRequest cancels a request that has been received and not yet started. The transport answers it with REQUEST_CANCELLED the moment the cancellation is read, and the handler is never called for it. The server runs queued requests only when its input has nothing more buffered, so a cancellation that arrives with, or just behind, the request it names is read first. A handler that is already running is not interrupted (see Server).

§Performance

Each incoming message is decoded once, in place, by rpc-io and jsonx-lib (the envelope is read without building a value tree, and parameters are parsed only when the server needs them). Outgoing results are written directly into a reused string: diagnostics, semantic tokens, and outlines with no value tree, and everything sent during one message or one job reaches the client in a single write. An edit converts its range with a binary search over line starts, reparses only the innermost reparsable node around it, and patches the line index in place; the work that stays linear in the file (moving the text after the edit, shifting later line starts) is a memmove and a pass over integers. Publishing diagnostics converts all their spans in one ascending pass.

§Stability

The public surface is the 2.0 contract: it follows Semantic Versioning, with no breaking changes before 3.0. See docs/API.md for the surface, the protocol behaviour that is part of the contract, and what is not promised.

Re-exports§

pub use diag_lang;
pub use incremental_lang;
pub use jsonx_lib;
pub use rpc_io;

Macros§

json
Builds a Value from JSON-like syntax.

Structs§

CompletionItem
One suggestion in a completion list.
Context
A handler’s view of the session for the duration of one call.
Diagnostic
One thing a compiler stage has to say about the source: a Severity, a headline message, a primary Label pointing at the span it concerns, and optionally secondary labels for related locations and trailing note/help lines. Since 1.1.0 it can also carry a Code naming its kind and fix-it Suggestions.
Document
A document the client has open, kept in step with the editor.
DocumentSymbol
One entry of a document’s outline, with the entries nested inside it.
Features
The typed features a Handler implements.
Hover
The answer to textDocument/hover: text for the user, optionally with the range it describes.
Location
A place in a file: a document URI and a range in it.
Position
A place in a document as the protocol spells it: a zero-based line and a zero-based column within that line.
Range
A stretch of a document between two Positions: start inclusive, end exclusive, as in the protocol.
ResponseError
A JSON-RPC error: the failed outcome of a request, sent back to the client in place of a result.
SemanticTokens
A document’s semantic tokens, delta-encoded as the protocol sends them.
SemanticTokensBuilder
Collects tokens by byte span and encodes them for the protocol.
SemanticTokensLegend
The token types and modifiers a server uses, sent once in the initialize result. Tokens refer to them by index.
Server
A language server: the protocol engine around a Handler.
TextEdit
A replacement of a range of text, as completion items and code actions carry them.

Enums§

CompletionItemKind
What a completion item is, which clients show as an icon.
Encoding
The unit a Position’s column is counted in.
Error
Something went wrong in the server itself, as opposed to a request that failed, which is a ResponseError sent to the client.
MarkupKind
How a block of text is to be read: plain or Markdown.
MessageType
How serious a message shown or logged by the client is (MessageType in the protocol).
SymbolKind
What a symbol is, which clients show as an icon in the outline.
Value
A JSON value, borrowing from the text it was parsed from.

Traits§

Handler
A language server’s behaviour: the part of a server that is about the language, as opposed to the protocol.

Functions§

serve_stdio
Serves one session on the process’s standard input and output, as an editor starts a language server: the one-call entry point.