Merge pull request praxis-live#56 from codelerity/script-api-update

Script API refactor

pom.xml

@@ -144,9 +144,9 @@
         <plugin>
           <groupId>org.apache.maven.plugins</groupId>
           <artifactId>maven-compiler-plugin</artifactId>
-          <version>3.11.0</version>
+          <version>3.12.1</version>
           <configuration>
-            <release>17</release>
+            <release>21</release>
           </configuration>
         </plugin>
         <plugin>

praxiscore-code-services/src/main/java/org/praxislive/code/services/CompilerCommandInstaller.java

@@ -39,7 +39,7 @@
 import org.praxislive.script.Env;
 import org.praxislive.script.InlineCommand;
 import org.praxislive.script.Namespace;
-import org.praxislive.script.impl.AbstractSingleCallFrame;
+import org.praxislive.script.AbstractSingleCallFrame;
 
 /**
  *

praxiscore-hub-net/src/main/java/org/praxislive/hub/net/internal/HubNetCommands.java

@@ -1,7 +1,7 @@
 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright 2020 Neil C Smith.
+ * Copyright 2024 Neil C Smith.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU Lesser General Public License version 3 only, as
@@ -32,10 +32,9 @@
 import org.praxislive.script.Command;
 import org.praxislive.script.CommandInstaller;
 import org.praxislive.script.Env;
-import org.praxislive.script.ExecutionException;
 import org.praxislive.script.Namespace;
 import org.praxislive.script.StackFrame;
-import org.praxislive.script.impl.AbstractSingleCallFrame;
+import org.praxislive.script.AbstractSingleCallFrame;
 
 /**
  *
@@ -53,7 +52,7 @@ public void install(Map<String, Command> commands) {
     private final static class ConfigurationCommand implements Command {
 
         @Override
-        public StackFrame createStackFrame(Namespace namespace, List<Value> args) throws ExecutionException {
+        public StackFrame createStackFrame(Namespace namespace, List<Value> args) throws Exception {
             return new AbstractSingleCallFrame(namespace, args) {
                 @Override
                 protected Call createCall(Env env, List<Value> args) throws Exception {

praxiscore-hub/src/main/java/org/praxislive/hub/Hub.java

@@ -43,7 +43,7 @@
 import org.praxislive.core.RootHub;
 import org.praxislive.core.services.Service;
 import org.praxislive.core.services.Services;
-import org.praxislive.script.impl.ScriptServiceImpl;
+import org.praxislive.script.DefaultScriptService;
 
 /**
  * Support for configuring and running a {@link RootHub}, along with the
@@ -91,7 +91,7 @@ private Hub(Builder builder) {
 
     private void extractExtensions(Builder builder, List<Root> exts) {
         exts.add(new DefaultComponentFactoryService());
-        exts.add(new ScriptServiceImpl());
+        exts.add(new DefaultScriptService());
         exts.add(new DefaultTaskService());
         exts.addAll(builder.extensions);
     }

praxiscore-script/pom.xml

@@ -12,8 +12,18 @@
 
   <dependencies>
     <dependency>
-      <groupId>org.junit.vintage</groupId>
-      <artifactId>junit-vintage-engine</artifactId>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-api</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-params</artifactId>
+      <scope>test</scope>
+    </dependency>
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter-engine</artifactId>
       <scope>test</scope>
     </dependency>
     <dependency>

praxiscore-script/src/main/java/module-info.java

@@ -1,13 +1,10 @@
 
 module org.praxislive.script {
 
-    requires java.logging;
-
     requires org.praxislive.core;
     requires org.praxislive.base;
 
     exports org.praxislive.script;
-    exports org.praxislive.script.impl;
 
     uses org.praxislive.script.CommandInstaller;
 

praxiscore-script/src/main/java/org/praxislive/script/impl/AbstractSingleCallFrame.java → praxiscore-script/src/main/java/org/praxislive/script/AbstractSingleCallFrame.java

@@ -1,7 +1,7 @@
 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright 2020 Neil C Smith.
+ * Copyright 2024 Neil C Smith.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU Lesser General Public License version 3 only, as
@@ -19,33 +19,42 @@
  * Please visit https://www.praxislive.org if you need additional information or
  * have any questions.
  */
-package org.praxislive.script.impl;
+package org.praxislive.script;
 
 import java.util.List;
+import java.util.Objects;
 import org.praxislive.core.Call;
 import org.praxislive.core.Value;
-import org.praxislive.core.types.PReference;
-import org.praxislive.script.Env;
-import org.praxislive.script.Namespace;
-import org.praxislive.script.StackFrame;
+import org.praxislive.core.types.PError;
 
 /**
- *
+ * An abstract {@link StackFrame} for commands that need to make a stack frame
+ * that makes a single call and processes its response.
+ * <p>
+ * Subclasses should implement
+ * {@link #createCall(org.praxislive.script.Env, java.util.List)} to create the
+ * call when required. Subclasses may additionally override
+ * {@link #processResult(java.util.List)} if the need to alter the return values
+ * from the call.
  */
 public abstract class AbstractSingleCallFrame implements StackFrame {
 
-    private Namespace namespace;
-    private List<Value> args;
+    private final Namespace namespace;
+    private final List<Value> args;
+
     private State state;
     private Call call;
     private List<Value> result;
 
     protected AbstractSingleCallFrame(Namespace namespace, List<Value> args) {
-        if (namespace == null || args == null) {
-            throw new NullPointerException();
-        }
-        this.namespace = namespace;
-        this.args = args;
+        this.namespace = Objects.requireNonNull(namespace);
+        this.args = Objects.requireNonNull(args);
+        state = State.Incomplete;
+    }
+
+    AbstractSingleCallFrame(List<Value> args) {
+        this.namespace = null;
+        this.args = Objects.requireNonNull(args);
         state = State.Incomplete;
     }
 
@@ -68,7 +77,7 @@ public final StackFrame process(Env env) {
                 }
                 env.getPacketRouter().route(call);
             } catch (Exception ex) {
-                result = List.of(PReference.of(ex));
+                result = List.of(PError.of(ex));
                 state = State.Error;
             }
         }
@@ -81,14 +90,20 @@ public final void postResponse(Call response) {
             call = null;
             result = response.args();
             if (response.isReply()) {
-                result = processResult(result);
-                state = State.OK;
+                try {
+                    result = processResult(result);
+                    state = State.OK;
+                } catch (Exception ex) {
+                    result = List.of(PError.of(ex));
+                    state = State.Error;
+                }
             } else {
                 state = State.Error;
             }
         }
     }
 
+    @Override
     public final void postResponse(State state, List<Value> args) {
         throw new IllegalStateException();
     }
@@ -101,11 +116,27 @@ public final List<Value> result() {
         return result;
     }
 
+    /**
+     * Create the Call. The call must use {@link Env#getAddress()} as the from
+     * address, and require a response.
+     *
+     * @param env environment for address, time, etc.
+     * @param args command arguments
+     * @return call
+     * @throws Exception on error
+     */
     protected abstract Call createCall(Env env, List<Value> args) throws Exception;
 
+    /**
+     * Process the result from the call on a successful response. Unless this
+     * method is overridden the result of the stack frame will be the result of
+     * the call.
+     *
+     * @param result successful result from call
+     * @return processed result
+     */
     protected List<Value> processResult(List<Value> result) {
         return result;
     }
 
 }
-

praxiscore-script/src/main/java/org/praxislive/script/Command.java

@@ -1,7 +1,7 @@
 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright 2020 Neil C Smith.
+ * Copyright 2024 Neil C Smith.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU Lesser General Public License version 3 only, as
@@ -19,18 +19,28 @@
  * Please visit https://www.praxislive.org if you need additional information or
  * have any questions.
  */
-
 package org.praxislive.script;
 
 import java.util.List;
 import org.praxislive.core.Value;
 
 /**
- *
+ * A script command. The script executor will look up commands by name in the
+ * current {@link Namespace}. Each execution of the command will cause a call
+ * {@link #createStackFrame(org.praxislive.script.Namespace, java.util.List)}.
  */
 public interface Command {
 
+    /**
+     * Create a StackFrame to execute the command with the provided Namespace
+     * and arguments.
+     *
+     * @param namespace current namespace
+     * @param args arguments
+     * @return stack frame to execute command with provided arguments
+     * @throws Exception if stack frame cannot be created
+     */
     public StackFrame createStackFrame(Namespace namespace, List<Value> args)
-            throws ExecutionException;
+            throws Exception;
 
 }

praxiscore-script/src/main/java/org/praxislive/script/CommandInstaller.java

@@ -1,7 +1,7 @@
 /*
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
  *
- * Copyright 2018 Neil C Smith.
+ * Copyright 2024 Neil C Smith.
  *
  * This code is free software; you can redistribute it and/or modify it
  * under the terms of the GNU Lesser General Public License version 3 only, as
@@ -19,17 +19,25 @@
  * Please visit https://www.praxislive.org if you need additional information or
  * have any questions.
  */
-
 package org.praxislive.script;
 
 import java.util.Map;
 
 /**
- *
- * 
+ * Service provider interface for other modules to provide commands.
+ * <p>
+ * Implementations should be registered for {@link ServiceLoader} to load.
  */
 public interface CommandInstaller {
 
+    /**
+     * Called on all registered command installers during initialization of a
+     * script executor. The implementation should add commands to the provided
+     * map. The String key is the name used to look up the command in the
+     * {@link Namespace}. A command might be registered under multiple names.
+     *
+     * @param commands map to install commands to
+     */
     public void install(Map<String, Command> commands);
 
 }