feat: improvements in api

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

@@ -0,0 +1,35 @@
+package com.instancify.scriptify.api.exception;
+
+/**
+ * Custom exception for errors in script functions.
+ */
+public class ScriptException extends Exception {
+
+    /**
+     * Creates a new ScriptException with the specified message.
+     *
+     * @param message the detail message
+     */
+    public ScriptException(String message) {
+        super(message);
+    }
+
+    /**
+     * Creates a new ScriptException with the specified message and cause.
+     *
+     * @param message the detail message
+     * @param cause the cause of the exception
+     */
+    public ScriptException(String message, Throwable cause) {
+        super(message, cause);
+    }
+
+    /**
+     * Creates a new ScriptException with the specified cause.
+     *
+     * @param cause the cause of the exception
+     */
+    public ScriptException(Throwable cause) {
+        super(cause);
+    }
+}

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

@@ -3,7 +3,7 @@
 /**
  * Custom exception for errors in script functions.
  */
-public class ScriptFunctionException extends Exception {
+public class ScriptFunctionException extends ScriptException {
 
     /**
      * Creates a new ScriptFunctionException with the specified message.

api/src/main/java/com/instancify/scriptify/api/script/Script.java

@@ -1,12 +1,16 @@
 package com.instancify.scriptify.api.script;
 
+import com.instancify.scriptify.api.exception.ScriptException;
+import com.instancify.scriptify.api.exception.ScriptFunctionException;
 import com.instancify.scriptify.api.script.constant.ScriptConstantManager;
 import com.instancify.scriptify.api.script.function.ScriptFunctionManager;
 
 /**
  * Defines the structure of a script that can be executed.
+ *
+ * @param <T> Type of value returned by the script after evaluation
  */
-public interface Script {
+public interface Script<T> {
 
     /**
      * Retrieves the function manager associated with this script.
@@ -42,6 +46,8 @@ public interface Script {
 
     /**
      * Evaluates and executes this script.
+     *
+     * @throws ScriptFunctionException If there's an error during script evaluation
      */
-    void eval(String script);
+    T eval(String script) throws ScriptException;
 }

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

@@ -1,5 +1,8 @@
 package com.instancify.scriptify.api.script.constant;
 
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
 /**
  * Represents a constant that can be used within scripts.
  */
@@ -10,14 +13,14 @@ public interface ScriptConstant {
      *
      * @return The name of the constant
      */
-    String getName();
+    @NotNull String getName();
 
     /**
      * Gets the value of the constant.
      *
      * @return The value of the constant
      */
-    Object getValue();
+    @Nullable Object getValue();
 
     /**
      * Creates a new ScriptConstant instance with the given name and value.
@@ -29,7 +32,7 @@ public interface ScriptConstant {
     static ScriptConstant of(String name, Object value) {
         return new ScriptConstant() {
             @Override
-            public String getName() {
+            public @NotNull String getName() {
                 return name;
             }
 

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

@@ -1,5 +1,7 @@
 package com.instancify.scriptify.api.script.constant;
 
+import org.jetbrains.annotations.Nullable;
+
 import java.util.Map;
 
 /**
@@ -20,7 +22,7 @@ public interface ScriptConstantManager {
      * @param name The name of the constant to retrieve
      * @return The ScriptConstant associated with the name, or null if not found
      */
-    default ScriptConstant getConstant(String name) {
+    default @Nullable ScriptConstant getConstant(String name) {
         return this.getConstants().get(name);
     }
 
@@ -30,4 +32,11 @@ default ScriptConstant getConstant(String name) {
      * @param constant The constant to be registered
      */
     void register(ScriptConstant constant);
+
+    /**
+     * Removes an existing constant in the manager.
+     *
+     * @param name The name of the constant to remove
+     */
+    void remove(String name);
 }

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

@@ -2,6 +2,9 @@
 
 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.
@@ -13,7 +16,7 @@ public interface ScriptFunction {
      *
      * @return The function's name
      */
-    String getName();
+    @NotNull String getName();
 
     /**
      * Invokes the function with the provided arguments.
@@ -23,5 +26,5 @@ public interface ScriptFunction {
      * @return The result of the function execution
      * @throws ScriptFunctionException If there's an error during invocation
      */
-    Object invoke(Script script, Object[] args) throws ScriptFunctionException;
+    @Nullable Object invoke(Script<?> script, ScriptFunctionArgument[] args) throws ScriptFunctionException;
 }

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

@@ -1,5 +1,7 @@
 package com.instancify.scriptify.api.script.function;
 
+import org.jetbrains.annotations.Nullable;
+
 import java.util.Map;
 
 /**
@@ -20,7 +22,7 @@ public interface ScriptFunctionManager {
      * @param name The name of the function to retrieve
      * @return The ScriptFunction associated with the name, or null if not found
      */
-    default ScriptFunction getFunction(String name) {
+    default @Nullable ScriptFunction getFunction(String name) {
         return this.getFunctions().get(name);
     }
 
@@ -30,4 +32,11 @@ default ScriptFunction getFunction(String name) {
      * @param function The function to be registered
      */
     void register(ScriptFunction function);
+
+    /**
+     * Removes an existing function in the manager.
+     *
+     * @param name The name of the function to remove
+     */
+    void remove(String name);
 }

api/src/main/java/com/instancify/scriptify/api/script/function/argument/ScriptFunctionArgument.java

@@ -0,0 +1,55 @@
+package com.instancify.scriptify.api.script.function.argument;
+
+/**
+ * Represents an argument that can be passed to a script function.
+ */
+public interface ScriptFunctionArgument {
+
+    /**
+     * Retrieves the value of this argument.
+     *
+     * @return The value of the argument
+     */
+    Object getValue();
+
+    /**
+     * Retrieves type the of value of this argument.
+     *
+     * @return Type the value of the argument
+     */
+    default Class<?> getType() {
+        return this.getValue().getClass();
+    }
+
+    /**
+     * Checks if the value of this argument is an instance of the specified class.
+     *
+     * @param classOf The class to check against
+     * @return true if the value is an instance of the given class, false otherwise
+     */
+    default boolean is(Class<?> classOf) {
+        return classOf.isInstance(getValue());
+    }
+
+    /**
+     * Casts the value of this argument to the specified class type.
+     *
+     * @param <T> The type to cast to
+     * @param classOf The class representing the type to cast to
+     * @return The value cast to the specified type
+     * @throws ClassCastException if the value cannot be cast to the specified type
+     */
+    default <T> T as(Class<T> classOf) {
+        return classOf.cast(getValue());
+    }
+
+    /**
+     * Creates a new ScriptFunctionArgument with the given value.
+     *
+     * @param value The value to be wrapped as an argument
+     * @return A new ScriptFunctionArgument instance
+     */
+    static ScriptFunctionArgument of(Object value) {
+        return () -> value;
+    }
+}

core/src/main/java/com/instancify/scriptify/core/script/constant/StandardConstantManager.java

@@ -24,6 +24,19 @@ public Map<String, ScriptConstant> getConstants() {
 
     @Override
     public void register(ScriptConstant constant) {
-        constants.put(constant.getName(), constant);
+        if (!constants.containsKey(constant.getName())) {
+            constants.put(constant.getName(), constant);
+        } else {
+            throw new IllegalStateException("The constant with this name already exists");
+        }
+    }
+
+    @Override
+    public void remove(String name) {
+        if (constants.containsKey(name)) {
+            constants.remove(name);
+        } else {
+            throw new IllegalArgumentException("The constant with this name does not exist");
+        }
     }
 }

core/src/main/java/com/instancify/scriptify/core/script/constant/impl/ScriptConstantBaseDir.java

@@ -1,6 +1,7 @@
 package com.instancify.scriptify.core.script.constant.impl;
 
 import com.instancify.scriptify.api.script.constant.ScriptConstant;
+import org.jetbrains.annotations.NotNull;
 
 import java.nio.file.Paths;
 
@@ -10,7 +11,7 @@
 public class ScriptConstantBaseDir implements ScriptConstant {
 
     @Override
-    public String getName() {
+    public @NotNull String getName() {
         return "baseDir";
     }
 

core/src/main/java/com/instancify/scriptify/core/script/constant/impl/ScriptConstantOsName.java

@@ -1,14 +1,15 @@
 package com.instancify.scriptify.core.script.constant.impl;
 
 import com.instancify.scriptify.api.script.constant.ScriptConstant;
+import org.jetbrains.annotations.NotNull;
 
 /**
  * Represents a constant with os name
  */
 public class ScriptConstantOsName implements ScriptConstant {
 
     @Override
-    public String getName() {
+    public @NotNull String getName() {
         return "osName";
     }
 

core/src/main/java/com/instancify/scriptify/core/script/function/StandardFunctionManager.java

@@ -60,6 +60,19 @@ public Map<String, ScriptFunction> getFunctions() {
 
     @Override
     public void register(ScriptFunction function) {
-        functions.put(function.getName(), function);
+        if (!functions.containsKey(function.getName())) {
+            functions.put(function.getName(), function);
+        } else {
+            throw new IllegalStateException("The function with this name already exists");
+        }
+    }
+
+    @Override
+    public void remove(String name) {
+        if (functions.containsKey(name)) {
+            functions.remove(name);
+        } else {
+            throw new IllegalArgumentException("The function with this name does not exist");
+        }
     }
 }

core/src/main/java/com/instancify/scriptify/core/script/function/impl/ScriptFunctionPrint.java

@@ -2,6 +2,8 @@
 
 import com.instancify.scriptify.api.script.Script;
 import com.instancify.scriptify.api.script.function.ScriptFunction;
+import com.instancify.scriptify.api.script.function.argument.ScriptFunctionArgument;
+import org.jetbrains.annotations.NotNull;
 
 import java.util.Arrays;
 import java.util.stream.Collectors;
@@ -12,13 +14,13 @@
 public class ScriptFunctionPrint implements ScriptFunction {
 
     @Override
-    public String getName() {
+    public @NotNull String getName() {
         return "print";
     }
 
     @Override
-    public Object invoke(Script script, Object[] args) {
-        System.out.println(Arrays.stream(args).map(String::valueOf).collect(Collectors.joining(" ")));
+    public Object invoke(Script<?> script, ScriptFunctionArgument[] args) {
+        System.out.println(Arrays.stream(args).map(arg -> arg.getValue().toString()).collect(Collectors.joining(" ")));
         return null;
     }
 }

core/src/main/java/com/instancify/scriptify/core/script/function/impl/ScriptFunctionShuffleArray.java

@@ -5,6 +5,8 @@
 import com.instancify.scriptify.api.exception.ScriptFunctionException;
 import com.instancify.scriptify.api.script.Script;
 import com.instancify.scriptify.api.script.function.ScriptFunction;
+import com.instancify.scriptify.api.script.function.argument.ScriptFunctionArgument;
+import org.jetbrains.annotations.NotNull;
 
 import java.util.ArrayList;
 import java.util.Collections;
@@ -16,18 +18,18 @@
 public class ScriptFunctionShuffleArray implements ScriptFunction {
 
     @Override
-    public String getName() {
+    public @NotNull String getName() {
         return "shuffleArray";
     }
 
     @Override
-    public Object invoke(Script script, Object[] args) throws ScriptFunctionException {
+    public Object invoke(Script<?> script, ScriptFunctionArgument[] args) throws ScriptFunctionException {
         if (args.length != 1) {
             throw new ScriptFunctionArgsCountException(1, args.length);
         }
 
-        if (!(args[0] instanceof List<?> array)) {
-            throw new ScriptFunctionArgTypeException(List.class, args[0].getClass());
+        if (!(args[0].getValue() instanceof List<?> array)) {
+            throw new ScriptFunctionArgTypeException(List.class, args[0].getType());
         }
 
         List<?> list = new ArrayList<Object>(array);