3232import java .io .File ;
3333import java .util .Collection ;
3434import java .util .Collections ;
35- import java .util .List ;
35+ import java .util .LinkedHashSet ;
36+ import java .util .Map ;
37+ import java .util .Set ;
3638
3739import org .scijava .plugin .SciJavaPlugin ;
3840import org .scijava .script .ScriptLanguage ;
4850 * know their language, not SciJava scripts (see {@link LanguageServerPlugin}).
4951 * </p>
5052 * <p>
51- * A dialect describes the translation , rather than doing it : a
52- * {@link ScriptDocument} translates every script the same way, prepending one
53- * line of declarations and blanking lines in place, and the dialect supplies
54- * only the pieces (types, declarations, imports ). So, for every language,
55- * positions in a script and in its document differ by just that line's length,
56- * which is how a session maps servers' answers back to the script (and leaves
57- * out those about the line ); and the translation is written, and tested, once.
58- * A language whose scripts need more (e.g. wrapping in a class) would extend
59- * that rule in {@link ScriptDocument}, for all languages.
53+ * A dialect supplies the declarations , rather than translating scripts : a
54+ * {@link ScriptDocument} translates every script the same way, prepending the
55+ * dialect's {@link #header}, and blanking in place the lines SciJava removes
56+ * before a script runs (e.g. its {@code #@} lines ). So, for every language,
57+ * positions in a script and in its document differ by just the header's
58+ * length, which is how a session maps servers' answers back to the script
59+ * (and leaves out those about the header ); and that mapping is written, and
60+ * tested, once. A language whose scripts need more (e.g. wrapping in a class)
61+ * would extend that rule in {@link ScriptDocument}, for all languages.
6062 * </p>
6163 *
6264 * @author Gabriel Selzer
@@ -83,8 +85,8 @@ public interface ScriptDialect extends SciJavaPlugin {
8385 * {@link org.scijava.code.lsp.server.RoutingLanguageServer}). The default knows
8486 * nothing: {@link Environment#NONE}.
8587 *
86- * @param text The script, as its servers see it (see
87- * {@link ScriptDocument} ).
88+ * @param text The script, as written (e.g. with its {@code #@script} line,
89+ * which its servers do not see ).
8890 * @param file The script's file, or null if it has none (e.g. unsaved).
8991 */
9092 // TODO: Consider whether this is necessary: so far only Appose-Python
@@ -94,64 +96,59 @@ default Environment environment(final String text, final File file) {
9496 }
9597
9698 /**
97- * Gets the type, as written in this language, that a script parameter of
98- * the given Java type has in a running script, e.g. {@code numpy.ndarray}
99- * for an image in CPython; or null if it has no useful type (the parameter
100- * is then not declared).
101- */
102- String parameterType (Class <?> type );
103-
104- /**
105- * Declares a variable, e.g. {@code image: numpy.ndarray} (Python) or
106- * {@code net.imglib2.img.Img image;} (Groovy), without a line break.
99+ * Gets the code declaring a script's parameters with the types they have
100+ * when it runs, for a {@link ScriptDocument} to prepend to the script: e.g.
101+ * {@code import numpy; image: numpy.ndarray} for an image in CPython. It
102+ * may also import what the declarations need, and declare other variables
103+ * scripts can use (e.g. Appose's {@code task}); parameters without a useful
104+ * type may be left out.
107105 *
108- * @param name The variable's name.
109- * @param type Its type, as given by {@link #parameterType}.
106+ * @param parameters The script's parameters (see
107+ * {@link LanguageServerService#scriptParameters}), by name, with
108+ * their Java types, in order.
110109 */
111- String declare ( String name , String type );
110+ Header header ( Map < String , Class <?>> parameters );
112111
113112 /**
114- * Gets statements needed before the declarations, e.g. imports of the types
115- * they use ({@code import numpy}). The default needs none.
116- *
117- * @param types The types declared, as given by {@link #parameterType}.
113+ * One line of code to prepend to a script (see {@link #header}), e.g.
114+ * statements joined by {@code ;}.
118115 */
119- default List <String > imports (final Collection <String > types ) {
120- return Collections .emptyList ();
121- }
116+ final class Header {
122117
123- /**
124- * Gets the name one of the {@link #imports} binds, e.g. {@code numpy} for
125- * {@code import numpy}; or null if none. Unless the script itself mentions
126- * it, the name is the declarations' alone: it is not completed (see
127- * {@link ScriptDocument#added()}). The default binds none.
128- */
129- default String imported (final String statement ) {
130- return null ;
131- }
118+ private final String code ;
119+ private final Set <String > hiddenNames ;
132120
133- /**
134- * Gets declarations of other variables scripts can use, e.g. Appose's
135- * {@code task}. The default declares none.
136- */
137- default List <String > extraDeclarations () {
138- return Collections .emptyList ();
139- }
121+ /**
122+ * @param code The code: one line, without a line break (the
123+ * {@link ScriptDocument} adds one after it), or empty if none.
124+ * @param hiddenNames The names to leave out of completion: those the
125+ * code binds only to declare the parameters, e.g.
126+ * {@code numpy} for {@code import numpy}.
127+ * @throws IllegalArgumentException If the code has a line break.
128+ */
129+ public Header (final String code , final Collection <String > hiddenNames ) {
130+ if (code .indexOf ('\n' ) >= 0 || code .indexOf ('\r' ) >= 0 ) {
131+ throw new IllegalArgumentException (
132+ "A header is one line, without line breaks: " + code );
133+ }
134+ this .code = code ;
135+ this .hiddenNames = Collections .unmodifiableSet (new LinkedHashSet <>(
136+ hiddenNames ));
137+ }
140138
141- /**
142- * Gets the separator between statements on one line, e.g. {@code "; "}
143- * (the default).
144- */
145- default String separator () {
146- return "; " ;
147- }
139+ /** The code: one line, without a line break; or empty if none. */
140+ public String code () {
141+ return code ;
142+ }
148143
149- /**
150- * Whether a line of the script is not of this language, and must be blanked
151- * (e.g. {@code #@} lines for languages whose comments start otherwise). The
152- * default blanks none.
153- */
154- default boolean blanks (final String line ) {
155- return false ;
144+ /**
145+ * The names to leave out of completion: those the code binds only to
146+ * declare the parameters, e.g. {@code numpy} for {@code import numpy}
147+ * (unless the script itself mentions them, see
148+ * {@link ScriptDocument#hiddenNames()}).
149+ */
150+ public Set <String > hiddenNames () {
151+ return hiddenNames ;
152+ }
156153 }
157154}
0 commit comments