Skip to content

Commit 3fbdd12

Browse files
gselzerclaude
andcommitted
code-lsp: rewrite the README around the module's purposes
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 35aba4e commit 3fbdd12

1 file changed

Lines changed: 86 additions & 48 deletions

File tree

‎code-lsp/README.md‎

Lines changed: 86 additions & 48 deletions
Original file line numberDiff line numberDiff line change
@@ -2,55 +2,93 @@
22

33
Code intelligence for SciJava scripts (completions, signature help, hover and
44
diagnostics), in the terms of the
5-
[Language Server Protocol](https://microsoft.github.io/language-server-protocol/),
6-
via [lsp4j](https://github.com/eclipse-lsp4j/lsp4j).
7-
8-
## Language servers
9-
10-
Every source of code intelligence is an lsp4j `LanguageServer`: in the
11-
SciJava process (e.g. Groovy's and Jython's, often built on
12-
`ScriptLanguageServer`), or a proxy to a server process (e.g.
13-
jedi-language-server, for Python run via Appose).
14-
15-
`LanguageServerPlugin`s offer servers per script language, and say where a
16-
script runs (an `Environment`: interpreter, search paths, classpath, and a
17-
running interpreter's state, if any). For each language, the
18-
`LanguageServerService` makes a `MergedLanguageServer` standing for all of
19-
its plugins' servers: it opens, changes and closes each document on every
20-
server for that script, and merges their answers.
21-
22-
Clients (e.g. the Script Editor, its REPL, or a tool checking scripts) ask
23-
about a script through a `ScriptSession` from the service: given a script's
24-
file, or text, or both, it keeps the servers' copy up to date, names it,
25-
takes offsets into its text, and reports the problems found in it. Clients
26-
that speak the protocol themselves (e.g. via JSON-RPC) use the merged server
27-
directly.
28-
Completions that take longer than a moment come later, as an
29-
`UpdatingCompletionList`'s update; signatures can be rated against the
30-
arguments typed (`RatedSignatureInformation`). Tools that ask once (e.g. to
31-
check a script) can call `LanguageServerService.diagnose`.
32-
33-
Servers see a script as plain code of its language (a `ScriptDocument`: its
34-
`#@` parameters declared with their run-time types, per a `ScriptDialect`);
35-
`TransformingLanguageServer` does this for servers that know the language but
36-
not SciJava, and maps positions back.
37-
38-
Server processes are started by `LspServers` (one per environment scripts run
39-
in), restarted if they stop, and stopped when idle; an `LspServerSpec` says
40-
how to start one, and `LspServerPlugin`s offer them per LSP language id
41-
(`LanguageServerService.launch`).
42-
43-
## Being a language server
44-
45-
`org.scijava.code.lsp.server.Main` runs a language server for SciJava
46-
scripts over standard input and output: the `LanguageServerService`'s
47-
servers, for every script language they support (by file extension). Editors
48-
outside SciJava can use it, e.g. VS Code via a generic language client
49-
extension, configured to run:
5+
[Language Server Protocol](https://microsoft.github.io/language-server-protocol/).
6+
7+
[lsp4j](https://github.com/eclipse-lsp4j/lsp4j) supplies the protocol: its
8+
types, the `LanguageServer` and `LanguageClient` interfaces, and JSON-RPC over
9+
a pair of streams. This module is the client side that lsp4j leaves to its
10+
users (deciding which servers answer for a script, keeping them in sync with
11+
it, and starting server processes), plus what is particular to SciJava
12+
scripts.
5013

5114
```
52-
java -cp "<Fiji>/jars/*;<Fiji>/plugins/*" org.scijava.code.lsp.server.Main
15+
client (e.g. Script Editor)
16+
│ ScriptSession: a script's text, and offsets into it
17+
▼
18+
LanguageServerService ──► the LanguageServerPlugins serving the language
19+
│ one server standing for all of them (merged answers)
20+
├──► in-process servers (e.g. Groovy, Jython), built on ScriptLanguageServer
21+
└──► server processes (e.g. jedi-language-server), via LspServerSpec
22+
seeing the script as plain code (TransformingLanguageServer)
5323
```
5424

55-
(with `:` instead of `;` on Linux and macOS) for the file types of interest
56-
(e.g. `*.py` for Jython, `*.groovy`).
25+
It does five things, each in a package of its own (the first and the last
26+
share one).
27+
28+
## 1. Brokering between scripts and servers (`org.scijava.code.lsp`)
29+
30+
The core. `LanguageServerPlugin`s offer lsp4j `LanguageServer`s for script
31+
languages, and say where a script runs (an `Environment`: interpreter, search
32+
paths, classpath, and a running interpreter's state, if any). For each
33+
script, the `LanguageServerService` gathers every server of its language, in
34+
its environment, behind one server: it opens, changes and closes the script
35+
on each, merges their answers, and moves the script to other servers should
36+
where it runs change.
37+
38+
Clients ask about a script through a `ScriptSession` from the service: it
39+
keeps the servers' copy of the script up to date, names it (its file's URI,
40+
or an `untitled:` one), takes offsets into its text (see `Positions`), and
41+
reports the problems found in it. Tools that ask once (e.g. to check a
42+
script) can call `LanguageServerService.diagnose`. For code typed into an
43+
interpreter whose language no plugin serves, a session completes the
44+
interpreter's variables.
45+
46+
## 2. Running server processes (`org.scijava.code.lsp.launch`)
47+
48+
For servers that are not Java in the SciJava process (e.g. jedi-language-server,
49+
for Python). An `LspServerPlugin` offers an `LspServerSpec` for an LSP
50+
language id (e.g. `python`), saying how to start a server for an environment
51+
and returning its streams (an `LspConnection`). Plugins get such a server via
52+
`LanguageServerService.launch`: started when first needed, one per
53+
environment, restarted if it stops, and stopped when idle.
54+
55+
## 3. Translating SciJava scripts (`org.scijava.code.lsp.script`)
56+
57+
A SciJava script is not quite plain code of its language: its `#@`
58+
parameters define variables before it runs. `LanguageServerService.scriptParameters`
59+
parses them; a `ScriptDocument` is the script as plain code, with them
60+
declared with their run-time types, as its language's `ScriptDialect` says.
61+
`TransformingLanguageServer` shows servers that know the language but not
62+
SciJava (e.g. jedi) this text, and maps positions in their answers back.
63+
In-process servers use `ScriptDocument` too, to know the parameters.
64+
65+
## 4. A toolkit for in-process servers (`org.scijava.code.lsp.jvm`)
66+
67+
For servers of JVM languages, written in Java (e.g. Groovy's and Jython's):
68+
`ScriptLanguageServer`, a base class keeping the open documents and turning
69+
requests into questions about a document and an offset; `Members`,
70+
completions for Java classes' members by reflection; `Callable`, something to
71+
call as a completion snippet; `Signatures`, rating overloads against the
72+
arguments typed; and `ClassIndex`, the classes on the classpath, with their
73+
javadoc.
74+
75+
## 5. Additions to LSP (`org.scijava.code.lsp`)
76+
77+
For in-process use, where both sides are SciJava's (over JSON-RPC, they
78+
degrade to plain LSP): `UpdatingCompletionList`, completions answered at once
79+
with better ones to follow (e.g. a slower server's); and
80+
`RatedSignatureInformation`, a signature rated by how well the arguments
81+
typed so far fit it.
82+
83+
## Who uses what
84+
85+
| | 1 | 2 | 3 | 4 | 5 |
86+
|-------------------------|---|---|---|---|---|
87+
| script-editor | ✓ | | | | ✓ |
88+
| scripting-groovy | ✓ | | ✓ | ✓ | ✓ |
89+
| scripting-jython | ✓ | ✓ | ✓ | ✓ | ✓ |
90+
| scripting-appose-python | ✓ | ✓ | ✓ | | |
91+
92+
The specialized packages depend only on `org.scijava.code.lsp`, never on each
93+
other. The module exports all four; its implementation
94+
(`org.scijava.code.lsp.impl`) is internal.

0 commit comments

Comments
 (0)