feat: new function executor and refactor: use new function executor for all functions

README.md

@@ -21,7 +21,7 @@ For adding a library only:
 <dependency>
     <groupId>com.instancify.scriptify</groupId>
     <artifactId>core</artifactId>
-    <version>1.4.0-SNAPSHOT</version>
+    <version>1.4.1-SNAPSHOT</version>
 </dependency>
 ```
 
@@ -30,12 +30,12 @@ For adding a library with JS for Rhino or GraalVM:
 <dependency>
     <groupId>com.instancify.scriptify</groupId>
     <artifactId>script-js-rhino</artifactId>
-    <version>1.4.0-SNAPSHOT</version>
+    <version>1.4.1-SNAPSHOT</version>
 </dependency>
 <dependency>
     <groupId>com.instancify.scriptify</groupId>
     <artifactId>script-js-graalvm</artifactId>
-    <version>1.4.0-SNAPSHOT</version>
+    <version>1.4.1-SNAPSHOT</version>
 </dependency>
 ```
 ## Gradle
@@ -49,11 +49,11 @@ maven {
 
 For adding a library only:
 ```groovy
-implementation "com.instancify.scriptify:core:1.4.0-SNAPSHOT"
+implementation "com.instancify.scriptify:core:1.4.1-SNAPSHOT"
 ```
 
 For adding a library with JS for Rhino or GraalVM:
 ```groovy
-implementation "com.instancify.scriptify:script-js-rhino:1.4.0-SNAPSHOT"
-implementation "com.instancify.scriptify:script-js-graalvm:1.4.0-SNAPSHOT"
+implementation "com.instancify.scriptify:script-js-rhino:1.4.1-SNAPSHOT"
+implementation "com.instancify.scriptify:script-js-graalvm:1.4.1-SNAPSHOT"
 ```

api/src/main/java/com/instancify/scriptify/api/exception/ScriptFunctionArgumentCountMismatchException.java

@@ -0,0 +1,26 @@
+package com.instancify.scriptify.api.exception;
+
+/**
+ * Exception thrown when a function is called with
+ * an incorrect number of arguments.
+ */
+public class ScriptFunctionArgumentCountMismatchException extends ScriptFunctionException {
+
+    /**
+     * Creates a new exception for a mismatch in argument count.
+     *
+     * @param functionName The name of the function
+     * @param expectedMin The minimum number of expected arguments
+     * @param expectedMax The maximum number of expected arguments
+     * @param provided The number of arguments actually provided
+     */
+    public ScriptFunctionArgumentCountMismatchException(
+            String functionName,
+            int expectedMin,
+            int expectedMax,
+            int provided
+    ) {
+        super("Function '" + functionName + "' expects between " +
+                expectedMin + " and " + expectedMax + " arguments, but got " + provided);
+    }
+}

api/src/main/java/com/instancify/scriptify/api/exception/ScriptFunctionArgumentTypeMismatchException.java

@@ -0,0 +1,28 @@
+package com.instancify.scriptify.api.exception;
+
+/**
+ * Exception thrown when a function is called with arguments
+ * of incompatible types.
+ */
+public class ScriptFunctionArgumentTypeMismatchException extends ScriptFunctionException {
+
+    /**
+     * Creates a new exception for an argument type mismatch.
+     *
+     * @param functionName The name of the function
+     * @param index The index of the argument that failed validation
+     * @param expected The expected type of the argument
+     * @param actual The actual type of the provided argument
+     */
+    public ScriptFunctionArgumentTypeMismatchException(
+            String functionName,
+            int index,
+            Class<?> expected,
+            Class<?> actual
+    ) {
+        super("Function '" + functionName + "' argument #" + index +
+                " expected type " + expected.getName() +
+                " but got " + (actual == null ? "null" : actual.getName()));
+    }
+}
+

api/src/main/java/com/instancify/scriptify/api/script/constant/ScriptConstantManager.java

@@ -1,6 +1,7 @@
 package com.instancify.scriptify.api.script.constant;
 
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.UnmodifiableView;
 
 import java.util.Map;
 
@@ -14,7 +15,7 @@ public interface ScriptConstantManager {
      *
      * @return A map where keys are constant names and values are ScriptConstant instances
      */
-    Map<String, ScriptConstant> getConstants();
+    @UnmodifiableView Map<String, ScriptConstant> getConstants();
 
     /**
      * Gets a specific constant by its name.

api/src/main/java/com/instancify/scriptify/api/script/function/ScriptFunction.java

@@ -1,10 +1,6 @@
 package com.instancify.scriptify.api.script.function;
 
-import com.instancify.scriptify.api.exception.ScriptFunctionException;
-import com.instancify.scriptify.api.script.Script;
-import com.instancify.scriptify.api.script.function.argument.ScriptFunctionArgument;
 import org.jetbrains.annotations.NotNull;
-import org.jetbrains.annotations.Nullable;
 
 /**
  * Represents a function that can be used within scripts.
@@ -17,14 +13,4 @@ public interface ScriptFunction {
      * @return The function's name
      */
     @NotNull String getName();
-
-    /**
-     * Invokes the function with the provided arguments.
-     *
-     * @param script The script in which the function will be invoked
-     * @param args The arguments to pass to the function
-     * @return The result of the function execution
-     * @throws ScriptFunctionException If there's an error during invocation
-     */
-    @Nullable Object invoke(Script<?> script, ScriptFunctionArgument[] args) throws ScriptFunctionException;
 }

api/src/main/java/com/instancify/scriptify/api/script/function/ScriptFunctionManager.java

@@ -1,6 +1,8 @@
 package com.instancify.scriptify.api.script.function;
 
+import com.instancify.scriptify.api.script.function.definition.ScriptFunctionDefinition;
 import org.jetbrains.annotations.Nullable;
+import org.jetbrains.annotations.UnmodifiableView;
 
 import java.util.Map;
 
@@ -14,15 +16,15 @@ public interface ScriptFunctionManager {
      *
      * @return A map where keys are function names and values are ScriptFunction instances
      */
-    Map<String, ScriptFunction> getFunctions();
+    @UnmodifiableView Map<String, ScriptFunctionDefinition> getFunctions();
 
     /**
      * Gets a specific function by its name.
      *
      * @param name The name of the function to retrieve
      * @return The ScriptFunction associated with the name, or null if not found
      */
-    default @Nullable ScriptFunction getFunction(String name) {
+    default @Nullable ScriptFunctionDefinition getFunction(String name) {
         return this.getFunctions().get(name);
     }
 

api/src/main/java/com/instancify/scriptify/api/script/function/annotation/Argument.java

@@ -0,0 +1,14 @@
+package com.instancify.scriptify.api.script.function.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.PARAMETER)
+public @interface Argument {
+    String name();
+
+    boolean required() default true;
+}

api/src/main/java/com/instancify/scriptify/api/script/function/annotation/ExecuteAt.java

@@ -0,0 +1,12 @@
+package com.instancify.scriptify.api.script.function.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.METHOD)
+public @interface ExecuteAt {
+
+}

api/src/main/java/com/instancify/scriptify/api/script/function/annotation/Executor.java

@@ -0,0 +1,12 @@
+package com.instancify.scriptify.api.script.function.annotation;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+@Retention(RetentionPolicy.RUNTIME)
+@Target(ElementType.PARAMETER)
+public @interface Executor {
+
+}

api/src/main/java/com/instancify/scriptify/api/script/function/definition/ScriptFunctionArgumentDefinition.java

@@ -0,0 +1,28 @@
+package com.instancify.scriptify.api.script.function.definition;
+
+/**
+ * Represents a single argument in a script function definition.
+ */
+public interface ScriptFunctionArgumentDefinition {
+
+    /**
+     * Retrieves the name of this argument.
+     *
+     * @return The argument name
+     */
+    String getName();
+
+    /**
+     * Indicates whether this argument is required.
+     *
+     * @return true if the argument must be provided, false if it is optional
+     */
+    boolean isRequired();
+
+    /**
+     * Retrieves the expected Java type of this argument.
+     *
+     * @return The argument type
+     */
+    Class<?> getType();
+}

api/src/main/java/com/instancify/scriptify/api/script/function/definition/ScriptFunctionDefinition.java

@@ -0,0 +1,35 @@
+package com.instancify.scriptify.api.script.function.definition;
+
+import com.instancify.scriptify.api.script.function.ScriptFunction;
+
+import java.util.List;
+
+/**
+ * Represents the definition of a {@link ScriptFunction}, including
+ * its available executors parsed from annotated methods.
+ */
+public interface ScriptFunctionDefinition {
+
+    /**
+     * Retrieves the underlying script function.
+     *
+     * @return The associated {@link ScriptFunction}
+     */
+    ScriptFunction getFunction();
+
+    /**
+     * Retrieves all executors available for this function.
+     *
+     * @return A list of {@link ScriptFunctionExecutor} instances
+     */
+    List<ScriptFunctionExecutor> getExecutors();
+
+    /**
+     * Finds an executor matching the given argument types.
+     *
+     * @param arguments the argument types to match
+     * @return the matching {@link ScriptFunctionExecutor}
+     * @throws IllegalArgumentException if you cannot find a matching executor
+     */
+    ScriptFunctionExecutor getExecutor(Class<?>... arguments);
+}