lspresso/lib.rs
1//! # lspresso
2//!
3//! Use existing test helpers and benchmarking tools to validate and performance and correctness!
4//!
5//! 
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;