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 publishesdiag_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 inHandler::features.
§The pieces
Serverandserve_stdio: the protocol engine. Reads messages from anyRead, writes to anyWrite, runs the lifecycle, synchronizes documents, and calls the handler.Handler: the trait a language implements, every method defaulted.Features: what the handler offers: hover, definition, completion, document symbols, semantic tokens.Context: what a handler reaches while it runs: the openDocuments and a channel back to the client (notifications, requests, log messages, diagnostics).Document: an open file: its text, its incrementally maintained syntax tree, and position conversions in the negotiatedEncoding.- The protocol types the features speak, each with hand-written JSON:
Position,Range,Location,Hover,CompletionItem,DocumentSymbol,SemanticTokenswith itsSemanticTokensBuilderandSemanticTokensLegend, andTextEdit. ResponseErrorandError: a request that failed, and what ends a session.
§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-lang | Protocol |
|---|---|
| primary label’s span | range |
Error, Warning, Note, Help | severity 1, 2, 3, 4 |
| message, primary label, notes, help | message, one part per line (note: …, help: …) |
| secondary labels | relatedInformation 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§
Structs§
- Completion
Item - 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 primaryLabelpointing 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 aCodenaming its kind and fix-itSuggestions. - Document
- A document the client has open, kept in step with the editor.
- Document
Symbol - One entry of a document’s outline, with the entries nested inside it.
- Features
- The typed features a
Handlerimplements. - 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:startinclusive,endexclusive, as in the protocol. - Response
Error - A JSON-RPC error: the failed outcome of a request, sent back to the client in place of a result.
- Semantic
Tokens - A document’s semantic tokens, delta-encoded as the protocol sends them.
- Semantic
Tokens Builder - Collects tokens by byte span and encodes them for the protocol.
- Semantic
Tokens Legend - The token types and modifiers a server uses, sent once in the
initializeresult. Tokens refer to them by index. - Server
- A language server: the protocol engine around a
Handler. - Text
Edit - A replacement of a range of text, as completion items and code actions carry them.
Enums§
- Completion
Item Kind - 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
ResponseErrorsent to the client. - Markup
Kind - How a block of text is to be read: plain or Markdown.
- Message
Type - How serious a message shown or logged by the client is
(
MessageTypein the protocol). - Symbol
Kind - 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.