Skip to main content

lspresso/
lib.rs

1//! # lspresso
2//!
3//! Use existing test helpers and benchmarking tools to validate and performance and correctness!
4//!
5//! ![an orange axolotl in a blue coffee cup falling over. coffee is spilling out and the axolotl looks distressed](https://raw.githubusercontent.com/20jasper/JJPWRGEM/main/crates/lspresso/lspresso.webp)
6//!
7//! ```no_run
8//! # use std::{process::Command, time::Duration};
9//! use lspresso::{Client, capabilities, gen_lsp_types::*};
10//!
11//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
12//! let mut client = Client::spawn_initialized(
13//!     Command::new("my-lsp"),
14//!     // use capabilities captured from real editors
15//!     // emacs, helix, neovim, and vscode are supported
16//!     capabilities::vscode::latest(),
17//! )?
18//! // default 15s, set to a reasonable upper bound so test timeouts are short
19//! .with_timeout(Duration::from_secs(15));
20//! let uri: Uri = "hi.json".parse()?;
21//!
22//! // convenience methods provide a simpler API
23//! client.did_open(uri.clone(), "{}", LanguageKind::JSON)?;
24//!
25//! // for example, `Client::diagnostics` pulls when the server supports it and
26//! // waits for pushed diagnostics otherwise
27//! let diags = client.diagnostics(&uri)?;
28//! assert_eq!(diags, vec![]);
29//!
30//! // if you need lower level control, import the `Protocol` trait
31//! // each method is prefixed with `protocol_` to differentiate from the
32//! // convenience layer
33//! use lspresso::Protocol as _;
34//!
35//! // pull diagnostics
36//! let diags = client.protocol_diagnostic(DocumentDiagnosticParams {
37//!     text_document: TextDocumentIdentifier { uri: uri.clone() },
38//!     identifier: Some("my-lsp".into()),
39//!     previous_result_id: Some("diagnostics-1".into()),
40//!     work_done_progress_params: WorkDoneProgressParams {
41//!         work_done_token: Some(ProgressToken::String("work-done-1".into())),
42//!     },
43//!     partial_result_params: PartialResultParams {
44//!         partial_result_token: Some(ProgressToken::String("partial-1".into())),
45//!     },
46//! })?;
47//!
48//! // push diagnostics wait for a notification or the timeout
49//! let published =
50//!     client.wait_for_notification_where::<PublishDiagnosticsNotification>(|p| p.uri == uri)?;
51//! assert!(published.diagnostics.is_empty());
52//!
53//! # Ok(())
54//! # }
55//! ```
56//!
57//! ## Benchmarking
58//!
59//! Use existing benchmarking tools like criterion with `Client::timings`.
60//! `Timings::server` is time spent in the language server. `request` and `response` are worth a look too since large messages take time
61//!
62//! ```no_run
63//! # use std::{process::Command, time::Duration};
64//! # use criterion::{Criterion, criterion_group, criterion_main};
65//! # use lspresso::{Client, capabilities, gen_lsp_types::*};
66//! fn bench_diagnostics(c: &mut Criterion) {
67//!     let mut client =
68//!         Client::spawn_initialized(Command::new("my-lsp"), capabilities::vscode::latest())
69//!             .unwrap();
70//!     let uri: Uri = "bench.json".parse().unwrap();
71//!     client
72//!         .did_open(uri.clone(), r#"{"a": [1, 2, 3]}"#, LanguageKind::JSON)
73//!         .unwrap();
74//!
75//!     c.bench_function("diagnostics", |b| {
76//!         b.iter_custom(|iters| {
77//!             let before = client.timings();
78//!             for _ in 0..iters {
79//!                 client.diagnostics(&uri).unwrap();
80//!             }
81//!             client.timings().since(before).server
82//!         });
83//!     });
84//!
85//!     // peak RSS over the session
86//!     let rss = client.rss_bytes().expect("the server is running");
87//!     println!("server RSS: {} MiB", rss / (1024 * 1024));
88//! }
89//!
90//! criterion_group!(benches, bench_diagnostics);
91//! criterion_main!(benches);
92//! ```
93//!
94//! ## limitations
95//!
96//! - server to client requests get a canned response. They could be scriptable and assertable
97//! - stdout is supported but not node ipc or tcp
98
99mod client;
100mod command;
101mod convenience;
102mod core;
103mod error;
104mod protocol;
105#[cfg(feature = "test-binaries")]
106#[doc(hidden)]
107pub mod scripted_server;
108
109pub use core::capabilities;
110
111pub use client::{Client, Initialize, Timings};
112pub use command::server_command;
113pub use error::{Awaited, Error, ErrorKind, Result};
114pub use gen_lsp_types;
115pub use protocol::Protocol;