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
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
//! # 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::Diagnostic`]s 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
//!
//! - [`Server`] and [`serve_stdio`]: the protocol engine. Reads messages from
//! any `Read`, writes to any `Write`, 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 open
//! [`Document`]s 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 negotiated [`Encoding`].
//! - The protocol types the features speak, each with hand-written JSON:
//! [`Position`], [`Range`], [`Location`], [`Hover`], [`CompletionItem`],
//! [`DocumentSymbol`], [`SemanticTokens`] with its [`SemanticTokensBuilder`]
//! and [`SemanticTokensLegend`], and [`TextEdit`].
//! - [`ResponseError`] and [`Error`]: 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}}"#));
//! # Ok::<(), lsp_lang::Error>(())
//! ```
//!
//! ## 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`](https://github.com/jamesgober/lsp-lang/blob/main/docs/API.md#stability)
//! for the surface, the protocol behaviour that is part of the contract, and
//! what is not promised.
pub use ;
pub use ;
pub use Document;
pub use Error;
pub use Features;
pub use Handler;
pub use ;
pub use ResponseError;
pub use ;
pub use ;
pub use ;
pub use ;
// The crates whose types appear in this crate's API, re-exported so a server
// names them through one dependency and the versions always match: a grammar is
// written against `incremental_lang`, diagnostics are built with `diag_lang`,
// parameters and custom results are `jsonx_lib` values, and the transport's
// types (`Json`, `Raw`, `FrameError`) are `rpc_io`'s.
pub use diag_lang;
pub use incremental_lang;
pub use jsonx_lib;
pub use rpc_io;
pub use Diagnostic;
pub use ;
/// Compiles and runs the `rust` code blocks in `README.md` and `docs/API.md` as
/// part of `cargo test`, so the published examples cannot drift from the API.
///
/// Present only while collecting doctests (`#[cfg(doctest)]`); it is not part of
/// the public surface and does not appear in the built library or its docs.
;