Function package rework and named function arguments

[Efnilite]

Problem

Skript should add named function arguments, similar to languages like Kotlin. This increases the clarity of which argument is passed.

Example:

function x(a: int, b: text):
  return length of {_b} * {_a} 

on load:
  set {_f::1} to x(a: 1, b: "nice")
  set {_f::2} to x(b: "nice", a: 1)
  set {_f::3} to x(1, "nice") # same behaviour as old

Also, the function package code is a mess.

Solution

Named function arguments

Named function arguments act as you would expect. They are always usable, except for when mixing named and unnamed arguments. To avoid assigning the incorrect value to a parameter, mixing named/unnamed is only allowed when the named arguments are in the same order as the parameters of the function. An example.

# all good since these are exclusively named arguments
x(a: 1, b: "nice", c: 2)
x(b: "nice", a: 1, c: 2)

# still allowed as they follow the order of appearance of the parameters
x(a: 1, "nice", c: 2)
x(1, "nice", c: 2)

# not allowed
x(a: 1, c: 2, "nice")
x(c: 2, a: 1, "nice")
x(2, a: 1, "nice")

Lists are also supported.

# allowed
x(xs: (1, 2, 3), 2, 3)

Rework changes

Function references

Function references have had a major rework. These changes are extensive and happen predominantly in SkriptParser. To try and improve organization, all function parsing code has been moved to the FunctionParser subclass. To accommodate these changes , njol.FunctionReference has been deprecated and has been replaced by skript.FunctionReference.

Function references are now determined inside the parser by using existing function signatures, which allows it to automatically select the correct function reference based on the argument types (fixing #8106). For every signature, it will attempt to parse the given arguments to the types belonging to the signature. If this is successful, it will continue with all other signatures. Then, if only one signature is valid, an exact match has been found. If there are multiple matches, an error will be printed.

The integration with SkriptParser also removes the need to fetch the signature of functions at runtime, as these can be stored directly inside the reference, which improves performance and reduces complexity.

Function arguments

Since Skript doesn't support the format to achieve named function arguments, a new function reference argument parser has been written. On receiving the input string, this parser correctly separates the arguments into arguments, and also determines whether these arguments are named or not. An example output is as follows.

Function execution

Since position is no longer relevant, all function execution is now handled via the abstract Function#execute(FunctionEvent, FunctionArguments) method. Instead of a 2D object array, functions now have access to FunctionArguments, which is essentially a glorified map. This map holds all the passed function arguments by name. The old execution method has been deprecated.

Parameters

njol.Parameter has been deprecated and has been replaced by the following classes, both of which implement the new skript.Parameter interface.

• skript.ScriptParameter: for parameters that are parsed from scripts. This class has an additional default value attribute, as well as the attributes provided by skript.Parameter. This default value is used in e.g. x: int = 3;
• skript.DefaultParameter: for parameters for DefaultFunctions. This class has no additional attributes other than those provided by skript.Parameter;

These new parameters use classes instead of classinfos for their types. When a parameter accepts multiple values, its type is e.g. Integer[] or String[]. When it accepts a single value, it is e.g. Integer or String. Parameters also have a set of modifiers, which dictate the behaviour of the parameter. The Modifier interface details the two currently used parameters:

• OPTIONAL: for function parameters that are optional,
• KEYED: for function parameters that accept keyed values.

Furthermore, parameters are now stored as a LinkedHashMap, which encourages the intended use for accessing function arguments. Using names and accessing the first argument are easy, while getting a parameter by its position is now more involved. Due to Skript still supporting Java 17, SequencedMap cannot be used as an abstraction of LinkedHashMap yet.

Parameter parsing

Script parameter parsing has been relocated from the (soon-to-be-extinct) Functions class. Parsing a single parameter has been moved to ScriptParameter, and parsing the entire signature of a script function has been moved to the new subclass StructFunction.FunctionParser.

Adds -> as a function return prefix

Looks nicer than the others :)

function add(x: int, y: int) -> int:
  return {_x} + {_y}

function add(x: int, y: int) :: int:
  return {_x} + {_y}

function add(x: int, y: int) returns int:
  return {_x} + {_y}

Testing Completed

• Existing tests
• Added tests for literal parsing
• Added tests for providing too few or too many arguments
• Added tests for named function arguments
• Added JUnit tests for the function reference argument parser

Supporting Information

Breaking changes

• SkriptParser#parseFunction(Class[]) has been entirely replaced with SkriptParser#parseFunctionReference()
• Function#execute(FunctionEvent, FunctionArguments) must be implemented by anyone extending Function directly
• Signature#getParameters() and Signature#getParameter(int) have had their return type changed to skript.Parameter instead of njol.Parameter
• ExprFunctionCall and EffFunctionCall's constructors have changed from accepting njol.FunctionReference to now accepting skript.FunctionReference.
• Due to a bug in JavaFunction#execute, the implementation of location has been updated to avoid the world being null. (as described in Java function rework #7969)
• All package-protected fields in njol.Parameter and njol.Signature have been changed to be private, with methods being added for access.
• Removed ScriptFunction#setReturnValue (deprecated since 2.9)
• Removed SkriptParser#wildcard (deprecated since 2.8)
• Removed SkriptParser#listSplitPattern (deprecated since 2.7)

---

Completes: #7987, #8106
Related: none