|
2 | 2 |
|
3 | 3 | Code intelligence for SciJava scripts (completions, signature help, hover and |
4 | 4 | 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. |
50 | 13 |
|
51 | 14 | ``` |
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) |
53 | 23 | ``` |
54 | 24 |
|
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