Add actual keyed returning support

Author: Efnilite

src/main/java/ch/njol/skript/lang/function/ExprFunctionCall.java

@@ -39,7 +39,7 @@ public ExprFunctionCall(FunctionReference<?> reference, Class<? extends T>[] exp
 		Class<?> returnType = Utils.getComponentType(functionReturnType);
 		if (CollectionUtils.containsSuperclass(expectedReturnTypes, returnType)) {
 			// Function returns expected type already
-			this.returnTypes = new Class[] {returnType};
+			this.returnTypes = new Class[]{returnType};
 			this.returnType = (Class<T>) returnType;
 		} else {
 			// Return value needs to be converted
@@ -55,12 +55,12 @@ public ExprFunctionCall(FunctionReference<?> reference, Class<? extends T>[] exp
 		if (execute == null) {
 			values = null;
 		} else if (!execute.getClass().isArray()) {
-			values = new Object[] {execute};
+			values = new Object[]{execute};
 		} else {
 			values = (Object[]) execute;
 		}
 
-		String[] keys = reference.function().returnedKeys();
+		String[] keys = reference.function().getReturnedKeys().toArray(new String[0]);
 		reference.function().resetReturnValue();
 
 		//noinspection unchecked
@@ -71,7 +71,7 @@ public ExprFunctionCall(FunctionReference<?> reference, Class<? extends T>[] exp
 		}
 
 		Converters.convert(values, convertedValues, returnTypes);
-		if (keys != null) {
+		if (keys.length > 0) {
 			for (int i = 0; i < convertedValues.length; i++) {
 				if (convertedValues[i] == null)
 					keys[i] = null;

src/main/java/ch/njol/skript/lang/function/Function.java

@@ -3,7 +3,6 @@
 import ch.njol.skript.SkriptConfig;
 import ch.njol.skript.classes.ClassInfo;
 import ch.njol.skript.lang.Expression;
-import ch.njol.skript.lang.KeyProviderExpression;
 import ch.njol.skript.lang.KeyedValue;
 import ch.njol.util.coll.CollectionUtils;
 import org.bukkit.Bukkit;
@@ -16,6 +15,8 @@
 import org.skriptlang.skript.common.function.ScriptParameter;
 
 import java.util.Arrays;
+import java.util.Collections;
+import java.util.SequencedCollection;
 
 /**
  * Functions can be called using arguments.
@@ -188,6 +189,11 @@ public Class<T> type() {
 		return null;
 	}
 
+	@Override
+	public @NotNull SequencedCollection<String> getReturnedKeys() {
+		return Collections.emptyList();
+	}
+
 	/**
 	 * Resets the return value of the {@code Function}.
 	 * Should be called right after execution.

src/main/java/ch/njol/skript/lang/function/JavaFunction.java

@@ -14,6 +14,7 @@
 
 import java.util.Collections;
 import java.util.List;
+import java.util.SequencedCollection;
 
 /**
  * @deprecated Use {@link DefaultFunction} instead.

src/main/java/ch/njol/skript/lang/function/ScriptFunction.java

@@ -15,6 +15,7 @@
 import org.skriptlang.skript.common.function.Parameters;
 
 import java.util.Arrays;
+import java.util.SequencedCollection;
 
 public class ScriptFunction<T> extends Function<T> implements ReturnHandler<T> {
 

src/main/java/org/skriptlang/skript/common/elements/functions/MathFunctions.java

@@ -2,6 +2,7 @@
 
 import ch.njol.skript.Skript;
 import ch.njol.skript.lang.Expression;
+import ch.njol.skript.lang.KeyedValue;
 import ch.njol.skript.lang.function.Functions;
 import ch.njol.skript.util.Contract;
 import ch.njol.util.Math2;
@@ -298,7 +299,7 @@ private static String str(double n) {
 						"clamp((5, 0, 10, 9, 13), 7, 10) = (7, 7, 10, 9, 10)",
 						"set {_clamped::*} to clamp({_values::*}, 0, 10)")
 				.since("2.8.0")
-				.parameter("values", Number[].class)
+				.parameter("values", Number[].class, Modifier.KEYED)
 				.parameter("min", Number.class)
 				.parameter("max", Number.class)
 				.contract(new Contract() {
@@ -312,16 +313,19 @@ public Class<?> getReturnType(Expression<?>... arguments) {
 						return Number.class;
 					}
 				})
-				.build(args -> {
-					Number[] values = args.get("values");
+				.buildKeyed(args -> {
+					KeyedValue<Number>[] values = args.get("values");
+					return KeyedValue.unzip(values).keys();
+				}, args -> {
+					KeyedValue<Number>[] values = args.get("values");
 					Double[] clampedValues = new Double[values.length];
 					double min = args.<Number>get("min").doubleValue();
 					double max = args.<Number>get("max").doubleValue();
 					// we'll be nice and swap them if they're in the wrong order
 					double trueMin = Math.min(min, max);
 					double trueMax = Math.max(min, max);
 					for (int i = 0; i < values.length; i++) {
-						double value = values[i].doubleValue();
+						double value = values[i].value().doubleValue();
 						if (!Double.isNaN(value) && !Double.isNaN(trueMin) && !Double.isNaN(trueMax)) {
 							clampedValues[i] = Math.clamp(value, trueMin, trueMax);
 						} else {

src/main/java/org/skriptlang/skript/common/function/DefaultFunction.java

@@ -6,6 +6,8 @@
 import org.skriptlang.skript.addon.SkriptAddon;
 import org.skriptlang.skript.common.function.Parameter.Modifier;
 
+import java.util.SequencedCollection;
+
 /**
  * A function that has been implemented in Java, instead of in Skript.
  * <p>
@@ -134,6 +136,17 @@ interface Builder<T> {
 		 */
 		DefaultFunction<T> build(@NotNull java.util.function.Function<FunctionArguments, T> execute);
 
+		/**
+		 * Completes this builder with the code to execute on call of this function.
+		 * Adds a function for setting the returned keys by this function.
+		 *
+		 * @param keys The function which sets the return keys.
+		 * @param execute The code to execute and the key consumer.
+		 * @return The final function.
+		 */
+		DefaultFunction<T> buildKeyed(@NotNull java.util.function.Function<FunctionArguments, SequencedCollection<String>> keys,
+									  @NotNull java.util.function.Function<FunctionArguments, T> execute);
+
 	}
 
 }

src/main/java/org/skriptlang/skript/common/function/DefaultFunctionImpl.java

@@ -19,20 +19,24 @@ final class DefaultFunctionImpl<T> extends ch.njol.skript.lang.function.Function
 	private final SkriptAddon source;
 	private final SequencedMap<String, Parameter<?>> parameters;
 	private final Function<FunctionArguments, T> execute;
+	private final Function<FunctionArguments, SequencedCollection<String>> keys;
 
 	private final List<String> description;
 	private final List<String> since;
 	private final List<String> examples;
 	private final List<String> keywords;
 	private final List<String> requires;
 
+	private SequencedCollection<String> returnedKeys;
+
 	DefaultFunctionImpl(
 			SkriptAddon source,
 			String name,
 			SequencedMap<String, Parameter<?>> parameters,
 			Class<T> returnType, boolean single,
 			@Nullable ch.njol.skript.util.Contract contract,
 			Function<FunctionArguments, T> execute,
+			Function<FunctionArguments, SequencedCollection<String>> keys,
 			String[] description, String[] since, String[] examples,
 			String[] keywords, String[] requires
 	) {
@@ -47,6 +51,7 @@ final class DefaultFunctionImpl<T> extends ch.njol.skript.lang.function.Function
 		this.source = source;
 		this.parameters = parameters;
 		this.execute = execute;
+		this.keys = keys;
 		this.description = description != null ? List.of(description) : Collections.emptyList();
 		this.since = since != null ? List.of(since) : Collections.emptyList();
 		this.examples = examples != null ? List.of(examples) : Collections.emptyList();
@@ -100,6 +105,7 @@ final class DefaultFunctionImpl<T> extends ch.njol.skript.lang.function.Function
 		}
 
 		FunctionArgumentsImpl arguments = new FunctionArgumentsImpl(args);
+		returnedKeys = keys.apply(arguments);
 		T result = execute.apply(arguments);
 
 		if (result == null) {
@@ -133,6 +139,7 @@ public T execute(@NotNull FunctionEvent<?> event, @NotNull FunctionArguments arg
 			}
 		}
 
+		returnedKeys = keys.apply(arguments);
 		return execute.apply(arguments);
 	}
 
@@ -141,6 +148,16 @@ public boolean resetReturnValue() {
 		return true;
 	}
 
+	@Override
+	public @NotNull String @Nullable [] returnedKeys() {
+		return returnedKeys.toArray(new String[0]);
+	}
+
+	@Override
+	public @NotNull SequencedCollection<String> getReturnedKeys() {
+		return returnedKeys;
+	}
+
 	@Override
 	public @NotNull String name() {
 		return getName();
@@ -273,7 +290,19 @@ public DefaultFunction<T> build(@NotNull Function<FunctionArguments, T> execute)
 			Preconditions.checkNotNull(execute, "execute cannot be null");
 
 			return new DefaultFunctionImpl<>(source, name, parameters,
-					returnType, !returnType.isArray(), contract, execute,
+					returnType, !returnType.isArray(), contract, execute, (_) -> Collections.emptyList(),
+					description, since, examples, keywords, requires);
+		}
+
+		@Override
+		public DefaultFunction<T> buildKeyed(@NotNull Function<FunctionArguments, SequencedCollection<String>> keys,
+		                                     @NotNull Function<FunctionArguments, T> execute) {
+			Preconditions.checkNotNull(execute, "execute cannot be null");
+			Preconditions.checkArgument(parameters.values().stream().anyMatch(it -> it.hasModifier(Modifier.KEYED)),
+					"buildKeyed cannot be called without any keyed arguments");
+
+			return new DefaultFunctionImpl<>(source, name, parameters,
+					returnType, !returnType.isArray(), contract, execute, keys,
 					description, since, examples, keywords, requires);
 		}
 
@@ -293,10 +322,10 @@ private static void checkNotNull(@NotNull String[] strings, @NotNull String mess
 	/**
 	 * A parameter for a {@link DefaultFunction}.
 	 *
-	 * @param name The name.
-	 * @param type The type's class.
+	 * @param name      The name.
+	 * @param type      The type's class.
 	 * @param modifiers The modifiers.
-	 * @param <T> The type.
+	 * @param <T>       The type.
 	 */
 	record DefaultParameter<T>(String name, Class<T> type, Set<Modifier> modifiers)
 			implements Parameter<T> {

src/main/java/org/skriptlang/skript/common/function/Function.java

@@ -7,6 +7,8 @@
 import org.jetbrains.annotations.NotNull;
 import org.jetbrains.annotations.Nullable;
 
+import java.util.SequencedCollection;
+
 /**
  * Represents a function implementation.
  *
@@ -41,7 +43,6 @@ public interface Function<T> {
 	/**
 	 * @return The returned keys.
 	 */
-	@Experimental
-	@NotNull String @Nullable [] returnedKeys();
+	@NotNull SequencedCollection<String> getReturnedKeys();
 
 }