Skip to content

Commit 2a0195d

Browse files
gselzerclaude
andcommitted
code-api: add virtual script documents
ScriptDocument turns a SciJava script into plain code of its language, for tools that know the language but not SciJava (e.g. language servers): script parameters are declared with their run-time types in one prepended line, and lines that are not of the language are blanked in place. PositionMap maps positions back; EnvironmentContext describes where the script runs; ScriptDialect is the per-language hook, offered by CodeCompleter#dialect(). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent b57ca4a commit 2a0195d

6 files changed

Lines changed: 668 additions & 0 deletions

File tree

‎code-api/src/main/java/org/scijava/code/api/CodeCompleter.java‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,4 +90,13 @@ default void prepare(final CompletionRequest request) {
9090
default SignatureHelp signatureHelp(final CompletionRequest request) {
9191
return SignatureHelp.NONE;
9292
}
93+
94+
/**
95+
* Gets how this completer's language turns a SciJava script into plain code
96+
* of the language (see {@link ScriptDocument}), or null if it does not. The
97+
* default does not.
98+
*/
99+
default ScriptDialect dialect() {
100+
return null;
101+
}
93102
}
Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
/*-
2+
* #%L
3+
* Core API for SciJava code intelligence features.
4+
* %%
5+
* Copyright (C) 2026 SciJava developers.
6+
* %%
7+
* Redistribution and use in source and binary forms, with or without
8+
* modification, are permitted provided that the following conditions are met:
9+
*
10+
* 1. Redistributions of source code must retain the above copyright notice,
11+
* this list of conditions and the following disclaimer.
12+
* 2. Redistributions in binary form must reproduce the above copyright notice,
13+
* this list of conditions and the following disclaimer in the documentation
14+
* and/or other materials provided with the distribution.
15+
*
16+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17+
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19+
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
20+
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21+
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22+
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23+
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24+
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25+
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26+
* POSSIBILITY OF SUCH DAMAGE.
27+
* #L%
28+
*/
29+
30+
package org.scijava.code.api;
31+
32+
import java.util.ArrayList;
33+
import java.util.Collections;
34+
import java.util.List;
35+
import java.util.Objects;
36+
37+
/**
38+
* Where a script runs, as far as analyzing it needs to know: the interpreter
39+
* (or other executable) that runs it, extra paths to search for modules or
40+
* packages, and classpath entries. Every part is optional.
41+
* <p>
42+
* For example, a CPython script run via Appose has its environment's Python
43+
* as interpreter, and a directory of packages installed for completion (see
44+
* dependency overlays) as an extra search path.
45+
* </p>
46+
*
47+
* @author Gabriel Selzer
48+
* @see ScriptDocument
49+
*/
50+
public final class EnvironmentContext {
51+
52+
/** No particular environment. */
53+
public static final EnvironmentContext EMPTY = new EnvironmentContext(null,
54+
Collections.emptyList(), Collections.emptyList());
55+
56+
private final String interpreter;
57+
private final List<String> searchPaths;
58+
private final List<String> classpath;
59+
60+
/**
61+
* @param interpreter Path of the interpreter or executable, or null.
62+
* @param searchPaths Extra paths to search for modules, e.g. for Python.
63+
* @param classpath Classpath entries, e.g. for JVM languages.
64+
*/
65+
public EnvironmentContext(final String interpreter,
66+
final List<String> searchPaths, final List<String> classpath)
67+
{
68+
this.interpreter = interpreter;
69+
this.searchPaths = searchPaths == null ? Collections.emptyList()
70+
: Collections.unmodifiableList(new ArrayList<>(searchPaths));
71+
this.classpath = classpath == null ? Collections.emptyList() : Collections
72+
.unmodifiableList(new ArrayList<>(classpath));
73+
}
74+
75+
/** Path of the interpreter or executable running the script, or null. */
76+
public String interpreter() {
77+
return interpreter;
78+
}
79+
80+
/** Extra paths to search for modules or packages; never null. */
81+
public List<String> searchPaths() {
82+
return searchPaths;
83+
}
84+
85+
/** Classpath entries; never null. */
86+
public List<String> classpath() {
87+
return classpath;
88+
}
89+
90+
@Override
91+
public boolean equals(final Object o) {
92+
if (!(o instanceof EnvironmentContext)) return false;
93+
final EnvironmentContext that = (EnvironmentContext) o;
94+
return Objects.equals(interpreter, that.interpreter) && searchPaths.equals(
95+
that.searchPaths) && classpath.equals(that.classpath);
96+
}
97+
98+
@Override
99+
public int hashCode() {
100+
return Objects.hash(interpreter, searchPaths, classpath);
101+
}
102+
103+
@Override
104+
public String toString() {
105+
return "EnvironmentContext[interpreter=" + interpreter + ", searchPaths=" +
106+
searchPaths + ", classpath=" + classpath + "]";
107+
}
108+
}
Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
/*-
2+
* #%L
3+
* Core API for SciJava code intelligence features.
4+
* %%
5+
* Copyright (C) 2026 SciJava developers.
6+
* %%
7+
* Redistribution and use in source and binary forms, with or without
8+
* modification, are permitted provided that the following conditions are met:
9+
*
10+
* 1. Redistributions of source code must retain the above copyright notice,
11+
* this list of conditions and the following disclaimer.
12+
* 2. Redistributions in binary form must reproduce the above copyright notice,
13+
* this list of conditions and the following disclaimer in the documentation
14+
* and/or other materials provided with the distribution.
15+
*
16+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17+
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19+
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
20+
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21+
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22+
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23+
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24+
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25+
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26+
* POSSIBILITY OF SUCH DAMAGE.
27+
* #L%
28+
*/
29+
30+
package org.scijava.code.api;
31+
32+
/**
33+
* Maps positions between a script and its {@link ScriptDocument transformed
34+
* text}. The transformation only prepends a header and blanks lines in place
35+
* (replacing their characters with spaces), so positions in the script just
36+
* shift by the header: by its length in characters, and by its line count in
37+
* lines; columns are unchanged.
38+
* <p>
39+
* Offsets and columns count {@code char}s, i.e. UTF-16 code units, as do
40+
* Java strings and the Language Server Protocol.
41+
* </p>
42+
*
43+
* @author Gabriel Selzer
44+
*/
45+
public final class PositionMap {
46+
47+
/** The identity: nothing prepended. */
48+
public static final PositionMap IDENTITY = new PositionMap(0, 0);
49+
50+
private final int headerLength;
51+
private final int headerLines;
52+
53+
/**
54+
* @param headerLength Number of characters prepended.
55+
* @param headerLines Number of lines prepended (each ending in a newline).
56+
*/
57+
public PositionMap(final int headerLength, final int headerLines) {
58+
this.headerLength = headerLength;
59+
this.headerLines = headerLines;
60+
}
61+
62+
/** Maps an offset in the script to one in the transformed text. */
63+
public int toTransformed(final int offset) {
64+
return offset + headerLength;
65+
}
66+
67+
/**
68+
* Maps an offset in the transformed text to one in the script, or returns
69+
* -1 if it lies in the prepended header.
70+
*/
71+
public int toOriginal(final int offset) {
72+
return offset < headerLength ? -1 : offset - headerLength;
73+
}
74+
75+
/** Maps a (0-based) line in the script to one in the transformed text. */
76+
public int lineToTransformed(final int line) {
77+
return line + headerLines;
78+
}
79+
80+
/**
81+
* Maps a (0-based) line in the transformed text to one in the script, or
82+
* returns -1 if it lies in the prepended header.
83+
*/
84+
public int lineToOriginal(final int line) {
85+
return line < headerLines ? -1 : line - headerLines;
86+
}
87+
88+
/** Number of characters prepended. */
89+
public int headerLength() {
90+
return headerLength;
91+
}
92+
93+
/** Number of lines prepended. */
94+
public int headerLines() {
95+
return headerLines;
96+
}
97+
}
Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
/*-
2+
* #%L
3+
* Core API for SciJava code intelligence features.
4+
* %%
5+
* Copyright (C) 2026 SciJava developers.
6+
* %%
7+
* Redistribution and use in source and binary forms, with or without
8+
* modification, are permitted provided that the following conditions are met:
9+
*
10+
* 1. Redistributions of source code must retain the above copyright notice,
11+
* this list of conditions and the following disclaimer.
12+
* 2. Redistributions in binary form must reproduce the above copyright notice,
13+
* this list of conditions and the following disclaimer in the documentation
14+
* and/or other materials provided with the distribution.
15+
*
16+
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
17+
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
18+
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
19+
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE
20+
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
21+
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
22+
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
23+
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
24+
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
25+
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
26+
* POSSIBILITY OF SUCH DAMAGE.
27+
* #L%
28+
*/
29+
30+
package org.scijava.code.api;
31+
32+
import java.util.Collection;
33+
import java.util.Collections;
34+
import java.util.List;
35+
36+
/**
37+
* What a script language knows about turning a SciJava script into plain code
38+
* of that language (a {@link ScriptDocument}): how its script parameters look
39+
* at run time, how to declare them, and where the script runs.
40+
* <p>
41+
* For example, CPython scripts run via Appose receive images as NumPy arrays,
42+
* declared {@code image: numpy.ndarray}; Groovy scripts receive the Java
43+
* objects themselves, declared {@code net.imglib2.img.Img image;}.
44+
* </p>
45+
*
46+
* @author Gabriel Selzer
47+
* @see ScriptDocument
48+
* @see CodeCompleter#dialect()
49+
*/
50+
public interface ScriptDialect {
51+
52+
/**
53+
* Gets the type a script parameter of the given Java type has in a running
54+
* script, as written in this language, e.g. {@code numpy.ndarray} for an
55+
* image in CPython; or null if it has no useful type (the parameter is then
56+
* not declared).
57+
*/
58+
String runtimeType(Class<?> type);
59+
60+
/**
61+
* Declares a variable, e.g. {@code image: numpy.ndarray} (Python) or
62+
* {@code net.imglib2.img.Img image;} (Groovy), without a line break.
63+
*
64+
* @param name The variable's name.
65+
* @param type Its type, as given by {@link #runtimeType}.
66+
*/
67+
String declare(String name, String type);
68+
69+
/**
70+
* Gets statements needed before the declarations, e.g. imports of the types
71+
* they use ({@code import numpy}). The default needs none.
72+
*
73+
* @param types The types declared, as given by {@link #runtimeType}.
74+
*/
75+
default List<String> imports(final Collection<String> types) {
76+
return Collections.emptyList();
77+
}
78+
79+
/**
80+
* Gets declarations of other variables scripts can use, e.g. Appose's
81+
* {@code task}. The default declares none.
82+
*/
83+
default List<String> extraDeclarations() {
84+
return Collections.emptyList();
85+
}
86+
87+
/**
88+
* Gets the separator between statements on one line, e.g. {@code "; "}
89+
* (the default).
90+
*/
91+
default String separator() {
92+
return "; ";
93+
}
94+
95+
/**
96+
* Whether a line of the script is not of this language, and must be blanked
97+
* (e.g. {@code #@} lines for languages whose comments start otherwise). The
98+
* default blanks none.
99+
*/
100+
default boolean blanks(final String line) {
101+
return false;
102+
}
103+
104+
/**
105+
* Gets where the script runs, e.g. its environment's interpreter. The
106+
* default knows nothing.
107+
*
108+
* @param request The script (and its path, if saved).
109+
*/
110+
default EnvironmentContext environment(final CompletionRequest request) {
111+
return EnvironmentContext.EMPTY;
112+
}
113+
}

0 commit comments

Comments
 (0)