lsp_lang/lib.rs
1//! # lsp_lang
2//!
3//! Language Server Protocol scaffolding for the `-lang` family: everything a
4//! language server needs that is not about the language itself, on the family's
5//! own stack. There are no third-party dependencies: the transport is
6//! [`rpc_io`], the JSON is [`jsonx_lib`], documents are reparsed by
7//! [`incremental_lang`], and diagnostics come from [`diag_lang`].
8//!
9//! A language server spends most of its code on plumbing: framing JSON-RPC over
10//! stdio, the `initialize`/`shutdown`/`exit` handshake, keeping a copy of every
11//! open file in step with the editor, converting UTF-16 positions to byte
12//! offsets and back, and turning compiler diagnostics into protocol
13//! diagnostics. This crate does all of that, so a server built on it is a
14//! grammar and a handler:
15//!
16//! - an [`incremental_lang::Grammar`], which parses each open document, and
17//! reparses only the node around each edit as the user types;
18//! - a [`Handler`], which publishes [`diag_lang::Diagnostic`]s as documents
19//! change and answers the requests the language supports. Each method has a
20//! default, so a handler implements only what it offers, and the capabilities
21//! the server advertises come from what the handler lists in
22//! [`Handler::features`].
23//!
24//! ## The pieces
25//!
26//! - [`Server`] and [`serve_stdio`]: the protocol engine. Reads messages from
27//! any `Read`, writes to any `Write`, runs the lifecycle, synchronizes
28//! documents, and calls the handler.
29//! - [`Handler`]: the trait a language implements, every method defaulted.
30//! - [`Features`]: what the handler offers: hover, definition, completion,
31//! document symbols, semantic tokens.
32//! - [`Context`]: what a handler reaches while it runs: the open
33//! [`Document`]s and a channel back to the client (notifications, requests,
34//! log messages, diagnostics).
35//! - [`Document`]: an open file: its text, its incrementally maintained syntax
36//! tree, and position conversions in the negotiated [`Encoding`].
37//! - The protocol types the features speak, each with hand-written JSON:
38//! [`Position`], [`Range`], [`Location`], [`Hover`], [`CompletionItem`],
39//! [`DocumentSymbol`], [`SemanticTokens`] with its [`SemanticTokensBuilder`]
40//! and [`SemanticTokensLegend`], and [`TextEdit`].
41//! - [`ResponseError`] and [`Error`]: a request that failed, and what ends a
42//! session.
43//!
44//! ## Example
45//!
46//! A server that reports every `TODO` in a document as a warning. The grammar
47//! here treats a whole document as one token; a real language supplies its own
48//! (see [`incremental_lang::Grammar`]).
49//!
50//! ```
51//! use lsp_lang::incremental_lang::{Builder, Grammar, Span, Token, TokenKind};
52//! use lsp_lang::diag_lang::{Label, Severity};
53//! use lsp_lang::{Context, Diagnostic, Document, Handler, Server};
54//!
55//! #[derive(Clone, Copy, Debug, PartialEq, Eq)]
56//! enum K { Root, Text }
57//! impl TokenKind for K {}
58//!
59//! #[derive(Clone)]
60//! struct Plain;
61//!
62//! impl Grammar for Plain {
63//! type Kind = K;
64//! const ROOT: K = K::Root;
65//! fn lex(&self, text: &str, tokens: &mut Vec<Token<K>>) {
66//! if !text.is_empty() {
67//! tokens.push(Token::new(K::Text, Span::new(0, text.len() as u32)));
68//! }
69//! }
70//! fn parse(&self, _: K, b: &mut Builder<'_, K>) {
71//! b.start(K::Root);
72//! while !b.at_end() { b.bump(); }
73//! b.finish();
74//! }
75//! }
76//!
77//! struct Todos;
78//!
79//! impl Handler<Plain> for Todos {
80//! fn changed(&mut self, doc: &Document<Plain>, cx: &mut Context<'_, Plain>) {
81//! let found: Vec<Diagnostic> = doc
82//! .text()
83//! .match_indices("TODO")
84//! .map(|(at, _)| {
85//! let span = Span::new(at as u32, at as u32 + 4);
86//! Diagnostic::new(Severity::Warning, "unfinished work", Label::new(span, "here"))
87//! })
88//! .collect();
89//! cx.publish_diagnostics(doc, &found);
90//! }
91//! }
92//!
93//! // Drive one session from memory, as an editor would over stdio.
94//! fn frame(json: &str) -> String {
95//! format!("Content-Length: {}\r\n\r\n{json}", json.len())
96//! }
97//! let input = [
98//! frame(r#"{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}"#),
99//! frame(r#"{"jsonrpc":"2.0","method":"textDocument/didOpen","params":{"textDocument":
100//! {"uri":"file:///notes.txt","languageId":"text","version":1,"text":"ship it\nTODO: tests"}}}"#),
101//! frame(r#"{"jsonrpc":"2.0","id":2,"method":"shutdown"}"#),
102//! frame(r#"{"jsonrpc":"2.0","method":"exit"}"#),
103//! ]
104//! .concat();
105//!
106//! let mut output = Vec::new();
107//! Server::new(Plain, Todos).run(input.as_bytes(), &mut output)?;
108//!
109//! let output = String::from_utf8_lossy(&output);
110//! assert!(output.contains(r#""method":"textDocument/publishDiagnostics""#));
111//! assert!(output.contains(r#""range":{"start":{"line":1,"character":0},"end":{"line":1,"character":4}}"#));
112//! # Ok::<(), lsp_lang::Error>(())
113//! ```
114//!
115//! ## Positions
116//!
117//! The protocol counts columns in UTF-16 code units by default; the rest of
118//! the family counts byte offsets. [`Document`] converts between the two in
119//! the encoding negotiated at `initialize`: UTF-8 whenever the client offers
120//! it, since byte columns convert without scanning, and UTF-16 otherwise. Line
121//! breaks are `\n`, `\r\n`, and lone `\r`, as the protocol specifies.
122//! Out-of-range positions are clamped the way the protocol prescribes rather
123//! than rejected, and a column inside a character (between the halves of a
124//! surrogate pair) rounds down to its start.
125//!
126//! ## Diagnostics
127//!
128//! [`Context::publish_diagnostics`] takes `diag_lang` diagnostics as any stage
129//! of a `-lang` front end produces them (their spans are byte offsets into the
130//! document) and writes `textDocument/publishDiagnostics` directly:
131//!
132//! | diag-lang | Protocol |
133//! |---|---|
134//! | primary label's span | `range` |
135//! | `Error`, `Warning`, `Note`, `Help` | `severity` 1, 2, 3, 4 |
136//! | message, primary label, notes, help | `message`, one part per line (`note: …`, `help: …`) |
137//! | secondary labels | `relatedInformation` in the same document |
138//!
139//! ## Cancellation
140//!
141//! `$/cancelRequest` cancels a request that has been received and not yet
142//! started. The transport answers it with `REQUEST_CANCELLED` the moment the
143//! cancellation is read, and the handler is never called for it. The server
144//! runs queued requests only when its input has nothing more buffered, so a
145//! cancellation that arrives with, or just behind, the request it names is read
146//! first. A handler that is already running is not interrupted (see
147//! [`Server`]).
148//!
149//! ## Performance
150//!
151//! Each incoming message is decoded once, in place, by `rpc-io` and `jsonx-lib`
152//! (the envelope is read without building a value tree, and parameters are
153//! parsed only when the server needs them). Outgoing results are written
154//! directly into a reused string: diagnostics, semantic tokens, and outlines
155//! with no value tree, and everything sent during one message or one job
156//! reaches the client in a single write. An edit converts its range with a
157//! binary search over line starts, reparses only the innermost reparsable node
158//! around it, and patches the line index in place; the work that stays linear
159//! in the file (moving the text after the edit, shifting later line starts) is
160//! a `memmove` and a pass over integers. Publishing diagnostics converts all
161//! their spans in one ascending pass.
162//!
163//! ## Stability
164//!
165//! The public surface is the `2.0` contract: it follows Semantic Versioning,
166//! with no breaking changes before `3.0`. See
167//! [`docs/API.md`](https://github.com/jamesgober/lsp-lang/blob/main/docs/API.md#stability)
168//! for the surface, the protocol behaviour that is part of the contract, and
169//! what is not promised.
170
171#![cfg_attr(docsrs, feature(doc_cfg))]
172#![forbid(unsafe_code)]
173#![deny(
174 warnings,
175 missing_docs,
176 unsafe_op_in_unsafe_fn,
177 unused_must_use,
178 unused_results,
179 clippy::unwrap_used,
180 clippy::expect_used,
181 clippy::panic,
182 clippy::todo,
183 clippy::unimplemented,
184 clippy::unreachable,
185 clippy::dbg_macro,
186 clippy::print_stdout,
187 clippy::print_stderr,
188 clippy::undocumented_unsafe_blocks
189)]
190
191mod completion;
192mod context;
193mod diagnostics;
194mod document;
195mod error;
196mod features;
197mod handler;
198mod jobs;
199mod json;
200mod lines;
201mod outbox;
202mod position;
203mod response;
204mod semantic;
205mod server;
206mod session;
207mod symbols;
208#[cfg(test)]
209mod testing;
210mod types;
211
212pub use completion::{CompletionItem, CompletionItemKind};
213pub use context::{Context, MessageType};
214pub use document::Document;
215pub use error::Error;
216pub use features::Features;
217pub use handler::Handler;
218pub use position::{Encoding, Position, Range};
219pub use response::ResponseError;
220pub use semantic::{SemanticTokens, SemanticTokensBuilder, SemanticTokensLegend};
221pub use server::{Server, serve_stdio};
222pub use symbols::{DocumentSymbol, SymbolKind};
223pub use types::{Hover, Location, MarkupKind, TextEdit};
224
225// The crates whose types appear in this crate's API, re-exported so a server
226// names them through one dependency and the versions always match: a grammar is
227// written against `incremental_lang`, diagnostics are built with `diag_lang`,
228// parameters and custom results are `jsonx_lib` values, and the transport's
229// types (`Json`, `Raw`, `FrameError`) are `rpc_io`'s.
230pub use diag_lang;
231pub use incremental_lang;
232pub use jsonx_lib;
233pub use rpc_io;
234
235pub use diag_lang::Diagnostic;
236pub use jsonx_lib::{Value, json};
237
238/// Compiles and runs the `rust` code blocks in `README.md` and `docs/API.md` as
239/// part of `cargo test`, so the published examples cannot drift from the API.
240///
241/// Present only while collecting doctests (`#[cfg(doctest)]`); it is not part of
242/// the public surface and does not appear in the built library or its docs.
243#[cfg(doctest)]
244#[doc = include_str!("../README.md")]
245#[doc = include_str!("../docs/API.md")]
246pub struct MarkdownDocTests;