Skip to content

Commit ec8f4ee

Browse files
ctruedenclaude
andcommitted
scijava-script3: a script is an Executable like any other
It runs through the same Runner, meets the same preprocessors, harvests its inputs through the same dialog in whichever toolkit, and can sit in a menu beside a Java command. Nothing above this layer knows which it is -- a claim now tested rather than asserted: ScriptWidgetsTest renders a Groovy script's parameters with the Swing widgets and drives its callbacks through an actual JSpinner. javax.script is the first backend, not the only one. ScriptLanguage and ScriptSession are the SPI; JsrLanguage turns every JSR-223 engine on the classpath into one, so Groovy, Jython, JRuby, Clojure and BeanShell cost nothing and declare nothing. GraalVM polyglot and Appose become further ScriptLanguages without this layer changing. Callbacks work for scripts, which SciJava Common never managed. It resolved `callback = "foo"` by reflecting a Java method, leaving a script nothing to name; here the name is resolved by whatever kind of code the executable is, and for a script that means a function it defined. Three things make it work: - a *session* rather than a one-shot eval, so the functions still exist when a parameter changes; - what the function changed is converted back into the parameters -- Groovy's `celsius * 9 / 5 + 32` is a BigDecimal, and convert3 knows what the parameter's declared type wants; - every declared parameter is bound, including unfilled ones, since a language that resolves names at run time fails on an unbound name rather than seeing null. Validators and choicesFrom come along for the same ride. The #@ header syntax is unchanged, because tens of thousands of scripts are written in it. Declaration lines are blanked rather than removed, so the language's own error messages keep pointing at the line the author is looking at -- #@ being a comment in Python and a syntax error in Groovy, leaving it in was not an option. Not ported: the ScriptProcessor chain, which existed to rewrite a script before evaluation and was used for parameters and a shebang, both of which the header reader does directly. ScriptService has no equivalent. ScriptREPL, ScriptInterpreter, AutoCompleter and CodeGenerator belong with the script editor. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013gJpzGd3ksbME4CN6Tu2ni
1 parent 758e94a commit ec8f4ee

16 files changed

Lines changed: 1870 additions & 1 deletion

File tree

‎docs/migration-plan.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -801,6 +801,49 @@ converted into this parameter) is what a chooser widget wants, and is a
801801
separate question from what conversions are possible. It lands with the object
802802
widget.
803803

804+
### Scripting
805+
806+
**`scijava-script3`** (`org.scijava.script3`) is built, and the shape of it is
807+
one claim: **a script is an `Executable` like any other**. It runs through the
808+
same `Runner`, meets the same preprocessors, harvests its inputs through the
809+
same dialog in whichever toolkit, and can sit in a menu beside a Java command.
810+
Nothing above this layer knows which it is - a claim now tested, in
811+
`scijava-swing`, by rendering a Groovy script's parameters with the Swing
812+
widgets and watching its callbacks fire.
813+
814+
- **`javax.script` is the first backend, not the only one.** `ScriptLanguage`
815+
and `ScriptSession` are the SPI; `JsrLanguage` turns every JSR-223 engine on
816+
the classpath into one, so Groovy, Jython, JRuby, Clojure and BeanShell cost
817+
nothing and need declare nothing. GraalVM polyglot and Appose are further
818+
`ScriptLanguage` implementations when they are wanted, and neither needs this
819+
layer to change.
820+
- **Callbacks work for scripts**, which SciJava Common never managed.
821+
`ExecutableInstance.behavior(String)` resolves a name however that kind of
822+
code does, and for a script that means a function the script defined - so
823+
`#@ double(callback = "celsiusChanged") celsius` behaves exactly as the Java
824+
annotation does. What the function changed is converted back into the
825+
parameters afterwards, because a callback exists precisely to change other
826+
parameters. Validators and `choicesFrom` come along for the same ride.
827+
- **A session, not an `eval`.** Keeping the interpreter is what makes the
828+
functions callable afterwards, and it is why `ScriptSession` exists rather
829+
than a one-shot evaluation.
830+
- **Declarations are blanked, not removed**, so the language's own error
831+
messages still point at the line the author is looking at. `#@` is a comment
832+
in Python and a syntax error in Groovy, so leaving it in was not an option.
833+
- **Every declared parameter is bound, including the unfilled ones.** A
834+
language that resolves names at run time fails on an unbound name rather
835+
than seeing null, so a callback mentioning a parameter the user has not
836+
reached would otherwise blow up instead of behaving.
837+
- **Not ported**: the `ScriptProcessor` chain, which existed to rewrite a
838+
script before evaluation and was used for parameters and a shebang, both of
839+
which the header reader does directly. `ScriptService` has no equivalent -
840+
`Scripts.get().of(path)` is a line. `ScriptREPL`, `ScriptInterpreter`,
841+
`AutoCompleter` and `CodeGenerator` belong with the script editor.
842+
- **Open**: whether a parameter with declared choices and no value should
843+
preselect the first. SciJava Common does; the model here leaves it unset,
844+
which is honest but shows an empty chooser. It is a one-line change in
845+
either direction and wants a look at real dialogs before being made.
846+
804847
### Phase 4 — UI and desktop
805848

806849
- **`scijava-harvest`** (`org.scijava.harvest`): the model behind a parameter

‎docs/migration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,7 @@ A **dropped** row is a successful outcome, not a gap.
123123
| `convert` | `org.scijava.convert3`: `Converter` asks one question - can you turn *this value* into *that type* - where SciJava Common had eight `canConvert` overloads and a `ConversionRequest` to carry the combinations. `ConvertService` becomes `Converters`, backed by plain `ServiceLoader` so that conversion sits *below* the container: parameter binding converts, and a script or command line supplies strings for everything. `DefaultConverter`'s pile of special cases becomes one converter per concern (cast, number, string, to-string, array, collection, constructor, file/path), each contributable and orderable by priority. `Converter.of(String.class, Foo.class, Foo::parse)` covers the common case in a line | ported |
124124
| `module`, `module.process` | `org.scijava.execute`: `@Parameter` on fields, `Executables` for the plain case, and `Runner` for the processor chain. `ModuleService.run` becomes `Runner.run`, still returning a future, but of an `ExecutionResult` that reports a declined run with its reason and its author rather than through `ModulePreprocessor.isCanceled()` | ported |
125125
| `command` | `org.scijava.command`: `Command` is a `Runnable` whose `@Parameter` fields are its struct; `@Menu` (repeatable) carries the presentation metadata, read from the annotation index without loading the class. `CommandInfo` replaces `ModuleInfo` and needs no `Context`; `MenuTree` replaces `ShadowMenu`. There is no `DynamicCommand`: see `choicesFrom` and `@Group(membersFrom)` | ported |
126-
| `script`, `script.process` | scripting facade + `javax.script` / GraalVM polyglot / Appose adapters (Phase 3) | planned |
126+
| `script`, `script.process` | `org.scijava.script3`: `ScriptLanguage`/`ScriptSession` are the SPI, with `JsrLanguage` making every JSR-223 engine on the classpath available for free; GraalVM polyglot and Appose are further languages, not replacements. `ScriptInfo`/`ScriptModule` become `ScriptExecutable`, an ordinary `Executable`, so a script runs through the same `Runner`, preprocessors, dialogs and menus as a Java command. `ScriptService` has no equivalent: `Scripts.get().of(path)` is a line. The `#@` header syntax is unchanged, and declaration lines are blanked rather than removed so the language's error messages keep pointing at the right line. The processor chain (`ScriptProcessor` and friends) is not ported: it existed to rewrite scripts before evaluation, and parameters plus a shebang are all it was actually used for. `ScriptREPL`, `ScriptInterpreter`, `AutoCompleter` and `CodeGenerator` await the script editor | ported |
127127
| `widget` (`InputWidget`, `InputPanel`, `InputHarvester`, `WidgetModel`, `WidgetStyle`) | `org.scijava.ui3`: `Widget` is a view of a `ParameterNode`, `WidgetFactory` a discoverable `@Plugin`, `WidgetPanel` a widget holding widgets (so a group nests with no special case), and `WidgetPanels` walks the tree for every toolkit. `WidgetModel` has no equivalent - a widget reads the `ParameterModel` and the node directly, and `WidgetStyle`'s parsing is `Widgets.isStyle`/`styleValue`. `InputHarvester` is a `Preprocessor` that declines the run when the user dismisses the dialog, rather than setting a `canceled` flag on itself | ported |
128128
| `ui.awt` (satellite repo `scijava-ui-awt`) | `org.scijava.awt`: the widget set in pure `java.awt` - no spinner, so the number widget is a field and a scroll bar - plus `Edt`, the first of the AWT platform layer that the Swing binding shares. `AWTColors`, `AWTWindows`, `AWTClipboard`, `AWTInputEventDispatcher` and the drag-and-drop dispatchers belong there too, when the `input`/`tool` layer arrives; the `AWTUI`/`AWTApplicationFrame`/`AWTStatusBar` shell classes await the application layer | ported |
129129
| `ui.javafx` (satellite repo `scijava-ui-javafx`) | `org.scijava.javafx`: the same widget set as the Swing binding, plus `FxThread` for JavaFX's application thread. `JavaFXKeys`'s key-code mapping is worth keeping when the `input`/`tool` layer arrives; `JavaFXMenuCreator` is superseded by `FxMenus`, some 40 lines against `MenuCreator` | ported |

‎pom.xml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@
8787
<module>scijava-ops-tutorial</module>
8888
<module>scijava-priority</module>
8989
<module>scijava-progress</module>
90+
<module>scijava-script3</module>
9091
<module>scijava-spi</module>
9192
<module>scijava-struct</module>
9293
<module>scijava-swing</module>

‎scijava-script3/pom.xml‎

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
<?xml version="1.0" encoding="UTF-8"?>
2+
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
3+
<modelVersion>4.0.0</modelVersion>
4+
5+
<parent>
6+
<groupId>org.scijava</groupId>
7+
<artifactId>pom-scijava</artifactId>
8+
<version>44.0.0</version>
9+
<relativePath />
10+
</parent>
11+
12+
<artifactId>scijava-script3</artifactId>
13+
<!--
14+
NB: the major version tracks the incarnation, per the incubator README.
15+
The 1.x.y of the other components is a legacy of the first monoversioned
16+
release, not the intended scheme.
17+
-->
18+
<version>3.0.0-SNAPSHOT</version>
19+
20+
<name>SciJava Script</name>
21+
<description>Running scripts as things that declare their inputs and outputs.</description>
22+
<url>https://github.com/scijava/scijava</url>
23+
<inceptionYear>2026</inceptionYear>
24+
<organization>
25+
<name>SciJava</name>
26+
<url>https://scijava.org/</url>
27+
</organization>
28+
<licenses>
29+
<license>
30+
<name>Simplified BSD License</name>
31+
<distribution>repo</distribution>
32+
</license>
33+
</licenses>
34+
35+
<developers>
36+
<developer>
37+
<id>ctrueden</id>
38+
<name>Curtis Rueden</name>
39+
<roles>
40+
<role>founder</role>
41+
<role>lead</role>
42+
<role>reviewer</role>
43+
<role>support</role>
44+
<role>maintainer</role>
45+
</roles>
46+
</developer>
47+
<developer>
48+
<id>gselzer</id>
49+
<name>Gabriel Selzer</name>
50+
<roles>
51+
<role>founder</role>
52+
<role>debugger</role>
53+
<role>reviewer</role>
54+
<role>support</role>
55+
</roles>
56+
</developer>
57+
</developers>
58+
<contributors>
59+
<contributor>
60+
<name>Johannes Schindelin</name>
61+
<properties><id>dscho</id></properties>
62+
</contributor>
63+
</contributors>
64+
65+
<mailingLists>
66+
<mailingList>
67+
<name>Image.sc Forum</name>
68+
<archive>https://forum.image.sc/tag/scijava</archive>
69+
</mailingList>
70+
</mailingLists>
71+
72+
<scm>
73+
<connection>scm:git:https://github.com/scijava/scijava</connection>
74+
<developerConnection>scm:git:git@github.com:scijava/scijava</developerConnection>
75+
<tag>HEAD</tag>
76+
<url>https://github.com/scijava/scijava</url>
77+
</scm>
78+
<issueManagement>
79+
<system>GitHub Issues</system>
80+
<url>https://github.com/scijava/scijava/issues</url>
81+
</issueManagement>
82+
<ciManagement>
83+
<system>GitHub Actions</system>
84+
<url>https://github.com/scijava/scijava/actions</url>
85+
</ciManagement>
86+
87+
<properties>
88+
<package-name>org.scijava.script3</package-name>
89+
90+
<license.licenseName>bsd_2</license.licenseName>
91+
<license.copyrightOwners>SciJava developers.</license.copyrightOwners>
92+
93+
<!-- Note: These versions must match across all component POMs! -->
94+
<scijava-common3.version>1.0.1-SNAPSHOT</scijava-common3.version>
95+
<scijava-convert3.version>3.0.0-SNAPSHOT</scijava-convert3.version>
96+
<scijava-execute.version>1.0.0-SNAPSHOT</scijava-execute.version>
97+
<scijava-priority.version>1.0.1-SNAPSHOT</scijava-priority.version>
98+
<scijava-struct.version>1.0.1-SNAPSHOT</scijava-struct.version>
99+
</properties>
100+
101+
<dependencies>
102+
<!--
103+
NB: no container here either. A script is an Executable like any
104+
other, and languages come from plain ServiceLoader.
105+
-->
106+
<dependency>
107+
<groupId>org.scijava</groupId>
108+
<artifactId>scijava-common3</artifactId>
109+
<version>${scijava-common3.version}</version>
110+
</dependency>
111+
<dependency>
112+
<groupId>org.scijava</groupId>
113+
<artifactId>scijava-convert3</artifactId>
114+
<version>${scijava-convert3.version}</version>
115+
</dependency>
116+
<dependency>
117+
<groupId>org.scijava</groupId>
118+
<artifactId>scijava-execute</artifactId>
119+
<version>${scijava-execute.version}</version>
120+
</dependency>
121+
<dependency>
122+
<groupId>org.scijava</groupId>
123+
<artifactId>scijava-priority</artifactId>
124+
<version>${scijava-priority.version}</version>
125+
</dependency>
126+
<dependency>
127+
<groupId>org.scijava</groupId>
128+
<artifactId>scijava-struct</artifactId>
129+
<version>${scijava-struct.version}</version>
130+
</dependency>
131+
132+
<!-- Test scope dependencies -->
133+
<!--
134+
NB: a real engine, so that the tests exercise a language rather than a
135+
stand-in. Any JSR-223 engine on the classpath is discovered the same
136+
way; Groovy is simply the one Fiji users meet first.
137+
-->
138+
<dependency>
139+
<groupId>org.apache.groovy</groupId>
140+
<artifactId>groovy</artifactId>
141+
<scope>test</scope>
142+
</dependency>
143+
<dependency>
144+
<groupId>org.apache.groovy</groupId>
145+
<artifactId>groovy-jsr223</artifactId>
146+
<scope>test</scope>
147+
</dependency>
148+
<dependency>
149+
<groupId>org.junit.jupiter</groupId>
150+
<artifactId>junit-jupiter-api</artifactId>
151+
<scope>test</scope>
152+
</dependency>
153+
</dependencies>
154+
155+
<build>
156+
<plugins>
157+
<plugin>
158+
<artifactId>maven-enforcer-plugin</artifactId>
159+
<executions>
160+
<execution>
161+
<id>enforce-package-rules</id>
162+
<goals>
163+
<goal>enforce</goal>
164+
</goals>
165+
<phase>test</phase>
166+
<configuration>
167+
<rules>
168+
<NoPackageCyclesRule implementation="org.scijava.maven.plugin.enforcer.NoPackageCyclesRule" />
169+
<NoSubpackageDependenceRule implementation="org.scijava.maven.plugin.enforcer.NoSubpackageDependenceRule" />
170+
</rules>
171+
</configuration>
172+
</execution>
173+
</executions>
174+
</plugin>
175+
<plugin>
176+
<artifactId>maven-javadoc-plugin</artifactId>
177+
<configuration>
178+
<links>
179+
<link>https://javadoc.scijava.org/Java11/</link>
180+
</links>
181+
</configuration>
182+
</plugin>
183+
</plugins>
184+
</build>
185+
</project>
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
/*
2+
* #%L
3+
* Running scripts as things that declare their inputs and outputs.
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+
module org.scijava.script3 {
31+
32+
exports org.scijava.script3;
33+
34+
requires transitive java.scripting;
35+
requires transitive org.scijava.execute;
36+
requires transitive org.scijava.struct;
37+
requires org.scijava.common3;
38+
requires org.scijava.convert3;
39+
requires org.scijava.priority;
40+
41+
uses org.scijava.script3.ScriptLanguage;
42+
43+
}

0 commit comments

Comments
 (0)