|
1 | 1 | # SciJava Code LSP |
2 | 2 |
|
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. |
6 | 4 |
|
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 |
13 | 6 |
|
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. |
28 | 8 |
|
29 | | -It does three things: the first for everyone, the others for those writing |
30 | | -servers. |
| 9 | +# Interrogating SciJava Scripts |
31 | 10 |
|
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