Skip to content

Commit 1760be0

Browse files
gselzerclaude
andcommitted
code-lsp: describe the README anew
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent a626099 commit 1760be0

1 file changed

Lines changed: 5 additions & 106 deletions

File tree

‎code-lsp/README.md‎

Lines changed: 5 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -1,112 +1,11 @@
11
# SciJava Code LSP
22

3-
Code intelligence for SciJava scripts (completions, signature help, hover and
4-
diagnostics), in the terms of the
5-
[Language Server Protocol](https://microsoft.github.io/language-server-protocol/).
3+
Manages code intelligence through the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/), based upon the [lsp4j](https://github.com/eclipse-lsp4j/lsp4j) library.
64

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.
5+
# Running Language Servers
136

14-
```
15-
client (e.g. Script Editor)
16-
│
17-
▼
18-
ScriptSession: a script's text, and offsets into it; shows a server of its
19-
│ own the script as plain code (ScriptDocument), and moves to another as
20-
│ where the script runs changes
21-
│ LanguageServerService finds
22-
│ ──► the ScriptDialect of the script's language:
23-
│ the plain code's LSP language, and where it runs
24-
│ the server, from the LanguageServerPlugin serving the LSP language
25-
├──► in-process servers (e.g. Groovy, Jython), built on AbstractLanguageServer
26-
└──► server processes (e.g. jedi-language-server), kept by ServerProcesses
27-
```
7+
`scijava-code-lsp` provides a `LanguageServerService`, allowing callers to find and launch `lsp4j` `LanguageServer` objects for a given programming language. Once created, these `LanguageServer` objects can be passed to any downstream application that knows how to use such an object.
288

29-
It does three things: the first for everyone, the others for those writing
30-
servers.
9+
# Interrogating SciJava Scripts
3110

32-
## 1. Brokering between scripts and servers (`org.scijava.code.lsp`)
33-
34-
The core. Two kinds of plugins meet here, so that script languages need not
35-
offer servers, nor servers know SciJava scripts:
36-
37-
* A `ScriptDialect` turns the scripts of a SciJava script language into plain
38-
code of an LSP language (e.g. Appose-Python scripts into `python`): it is
39-
what a script language contributes (e.g. scripting-groovy's, for Groovy
40-
scripts).
41-
* A `LanguageServerPlugin` offers lsp4j `LanguageServer`s for an LSP language,
42-
by its id (e.g. `groovy`): e.g. `scijava-code-lsp-groovy`'s. Each language
43-
is served by the highest-priority plugin supporting it. A server combining
44-
several sources (e.g. Jython's own analysis and jedi's) combines them
45-
itself.
46-
47-
Clients ask about a script through a `ScriptSession`, made with the
48-
service (`new ScriptSession(service, language)`): it
49-
keeps its servers' copy of the script up to date, names it (its file's URI,
50-
or an `untitled:` one), takes offsets into its text (see `Positions`), and
51-
reports the problems found in it. Behind it is a server of its own, from the
52-
plugin serving its dialect's language, for the environment the script runs
53-
in, as the dialect says. That is asked before each request, since it may
54-
change as the script is edited (e.g. an Appose environment it declares): the
55-
session then moves to a new server, of the new environment, off the caller's
56-
thread. A server analyzes scripts in exactly the environment it is given.
57-
For code typed into a running interpreter, the server learns the
58-
interpreter's state through its `Environment`. Tools that
59-
ask once (e.g. to check a script) can wait for a session's problems
60-
(`diagnostics(timeout)`). For code typed into an interpreter whose language
61-
has no dialect, or no servers, a session completes the interpreter's
62-
variables.
63-
64-
Those wanting a server itself, for plain code of a language, get one via
65-
`LanguageServerService.launch`, by LSP language id (e.g. `groovy`, or
66-
`python`): in-process, or a server process (see below), whichever the plugins
67-
offer, analyzing scripts as running in the environment given. (A server may
68-
analyze each document in an environment of its own, based on that one: e.g.
69-
`scijava-code-lsp-jedi`'s, with the packages a script declares added.)
70-
71-
A SciJava script is not quite plain code of its language: its `#@`
72-
parameters define variables before it runs. `LanguageServerService.scriptParameters`
73-
parses them; a `ScriptDocument` is the script as plain code, with them
74-
declared with their run-time types, as its `ScriptDialect` says. A session
75-
shows its servers the script so, and maps positions in their answers back.
76-
77-
## 2. Running server processes, and routing (`org.scijava.code.lsp.server`)
78-
79-
For servers that are not Java in the SciJava process (e.g. jedi-language-server,
80-
for Python). A `ServerLauncher` says how to start one for an environment: the
81-
process, speaking LSP over its standard streams, and the options and
82-
workspace root to initialize it with. `ServerProcesses` keeps them: started
83-
when first needed, one per environment, restarted if they stop, and stopped
84-
when idle, or when its owner (e.g. a `LanguageServerPlugin`, when disposed)
85-
shuts them down; each seen as a `LanguageServer` of its own.
86-
`scijava-code-lsp-jedi`'s plugin serves `python` this way.
87-
88-
## 3. A toolkit for in-process servers (`org.scijava.code.lsp.jvm`)
89-
90-
For servers of JVM languages, written in Java (e.g. Groovy's and Jython's):
91-
`AbstractLanguageServer`, a base class keeping the open documents and turning
92-
requests into questions about a document and an offset; `Members`,
93-
completions for Java classes' members by reflection; `Callable`, something to
94-
call as a completion snippet; `Signatures`, rating overloads against the
95-
arguments typed; and `ClassIndex`, the classes on the classpath, with their
96-
javadoc.
97-
98-
## Who uses what
99-
100-
| | 1 | 2 | 3 | offers |
101-
|-------------------------|---|---|---|----------------------------------------|
102-
| script-editor | ✓ | | | (a client) |
103-
| scripting-groovy | ✓ | | | a dialect, of Groovy scripts |
104-
| scripting-jython | ✓ | | | a dialect, of Jython scripts |
105-
| scripting-appose-python | ✓ | | | a dialect, of Appose-Python scripts |
106-
| code-lsp-groovy | ✓ | | ✓ | servers of `groovy` |
107-
| code-lsp-jython | ✓ | | ✓ | servers of `jython`, building on `python` |
108-
| code-lsp-jedi | ✓ | ✓ | | servers of `python` |
109-
110-
The toolkits (`org.scijava.code.lsp.server` and `org.scijava.code.lsp.jvm`)
111-
depend only on `org.scijava.code.lsp`. The module exports all three; its
112-
implementation (`org.scijava.code.lsp.impl`) is internal.
11+
SciJava Scripts *cannot* simply be handed off to a `LanguageServer` for tasks like auto-completion: SciJava Script parameters, as well as Appose-Python environment information (and maybe other things in the future) must be converted to a representation that a `LanguageServer` can understand. To that end, `scijava-code-lsp` offers the `ScriptSession` class, for synchronizing a SciJava script with a `LanguageServer` as the script is edited: clients only ever deal with the script's own text and offsets, and servers only ever see plain code of their language.

0 commit comments

Comments
 (0)