diff --git a/orx-expression-evaluator-typed/src/commonMain/kotlin/typed/CompiledFunctions.kt b/orx-expression-evaluator-typed/src/commonMain/kotlin/typed/CompiledFunctions.kt index ce8e6ab63..ed888b566 100644 --- a/orx-expression-evaluator-typed/src/commonMain/kotlin/typed/CompiledFunctions.kt +++ b/orx-expression-evaluator-typed/src/commonMain/kotlin/typed/CompiledFunctions.kt @@ -2,8 +2,17 @@ package org.openrndr.extra.expressions.typed import org.antlr.v4.kotlinruntime.tree.ParseTreeWalker + /** - * Compile a function + * Compiles a string expression into a single-parameter function capable of evaluating the expression. + * + * @param T0 The type of the single parameter that will be passed to the compiled function. + * @param R The return type of the compiled function. + * @param expression The string representation of the expression to be compiled. + * @param parameter0 The name of the required parameter in the expression. + * @param constants A lambda function to resolve constants in the expression by their names. Defaults to a function returning null for all names. + * @param functions A set of function extensions that can be used within the expression. Defaults to an empty set. + * @return A single-parameter function that takes an argument of type [T0] and evaluates the expression to return a result of type [R]. */ fun compileFunction1( expression: String, @@ -38,6 +47,21 @@ fun compileFunction1( } } +/** + * Tries to compile a given string expression into a single-parameter function. Returns the compiled function if successful, + * or `null` if an error occurs during compilation. Errors are handled using the provided [onError] callback. + * + * @param T0 The type of the single parameter that will be passed to the compiled function. + * @param R The return type of the compiled function. + * @param expression The string representation of the expression to be compiled. + * @param parameter0 The name of the required parameter in the expression. + * @param constants A lambda function to resolve constants in the expression by their names. Defaults to a function returning null for all names. + * @param functions A set of function extensions that can be used within the expression. Defaults to an empty set. + * @param onError A callback function that will be invoked when an error occurs during compilation. + * The error is passed to this function. + * @return A single-parameter function that takes an argument of type [T0] and evaluates the expression to return a result of type [R], + * or `null` if the compilation fails. + */ fun compileFunction1OrNull( expression: String, parameter0: String, @@ -53,8 +77,25 @@ fun compileFunction1OrNull( } } -// - +/** + * Compiles a string expression into a lambda function with two parameters. + * + * This function takes an expression as a string, as well as two parameter names, + * and returns a lambda that evaluates the expression with the provided parameter values. + * Optionally, a map of constants and custom functions can be provided for use in the expression. + * + * @param T0 The type of the first parameter. + * @param T1 The type of the second parameter. + * @param R The return type of the resulting lambda function. + * @param expression The string expression to compile. + * @param parameter0 The name of the first parameter in the expression. + * @param parameter1 The name of the second parameter in the expression. + * @param constants A lambda function that provides constant values by variable name. Defaults to returning null for all names. + * @param functions The custom functions available in the context of the expression. Defaults to an empty set of functions. + * @return A lambda function that takes two parameters of types T0 and T1 and returns a result of type R, + * based on the compiled expression. + * @throws IllegalArgumentException if either parameter name exists within the constants map. + */ fun compileFunction2( expression: String, parameter0: String, @@ -93,6 +134,26 @@ fun compileFunction2( } } +/** + * Attempts to compile a string expression into a lambda function with two parameters, + * returning null if an error occurs during compilation. + * + * This function is a safe wrapper around `compileFunction2`, catching any exceptions + * that may be thrown during the compilation process. If an error occurs, the provided + * `onError` callback is invoked with the exception, and the function returns null. + * + * @param T0 The type of the first parameter. + * @param T1 The type of the second parameter. + * @param R The return type of the resulting lambda function. + * @param expression The string expression to compile. + * @param parameter0 The name of the first parameter in the expression. + * @param parameter1 The name of the second parameter in the expression. + * @param constants A lambda function that provides constant values for variables by name. Defaults to returning null for all names. + * @param functions The custom functions available in the context of the expression. Defaults to an empty set of functions. + * @param onError A callback invoked with the exception if an error occurs during compilation. Defaults to an empty function. + * @return A lambda function that takes two parameters of types T0 and T1 and returns a result of type R if the compilation is successful. + * Returns null if an error occurs during compilation. + */ fun compileFunction2OrNull( expression: String, parameter0: String, @@ -109,8 +170,23 @@ fun compileFunction2OrNull( } } -// - +/** + * Compiles a 3-parameter function from a given string expression, allowing dynamic evaluation with specified parameters, constants, and external function extensions. + * + * @param T0 The type of the first parameter. + * @param T1 The type of the second parameter. + * @param T2 The type of the third parameter. + * @param R The return type of the compiled function. + * @param expression The string representation of the expression to be compiled. + * @param parameter0 The name of the first parameter referenced in the expression. + * @param parameter1 The name of the second parameter referenced in the expression. + * @param parameter2 The name of the third parameter referenced in the expression. + * @param constants A lambda function providing constant values for variable names used in the expression. Defaults to a function returning null. + * @param functions An optional container of external functions that can be called within the expression. Defaults to an empty set of functions. + * @return A lambda function that takes three parameters of types T0, T1, and T2, and returns a result of type R after evaluating the compiled expression. + * @throws IllegalArgumentException If any of the parameter names are found in the constants map. + * @throws ExpressionException If there is a syntax error in the provided expression. + */ fun compileFunction3( expression: String, parameter0: String, @@ -157,6 +233,23 @@ fun compileFunction3( } } +/** + * Compiles a 3-parameter function from a given string expression, returning null if an error occurs during compilation. + * + * @param T0 The type of the first parameter. + * @param T1 The type of the second parameter. + * @param T2 The type of the third parameter. + * @param R The return type of the compiled function. + * @param expression The string representation of the expression to be compiled. + * @param parameter0 The name of the first parameter referenced in the expression. + * @param parameter1 The name of the second parameter referenced in the expression. + * @param parameter2 The name of the third parameter referenced in the expression. + * @param constants A lambda function providing constant values for variable names used in the expression. Defaults to a function returning null. + * @param functions An optional container of external functions that can be called within the expression. Defaults to an empty set of functions. + * @param onError A lambda function that will be invoked with the exception if an error occurs during compilation. Defaults to an empty function. + * @return A lambda function that takes three parameters of types T0, T1, and T2, and returns a result of type R after evaluating the compiled expression, or null if an error occurs + * . + */ fun compileFunction3OrNull( expression: String, parameter0: String, diff --git a/orx-expression-evaluator-typed/src/commonMain/kotlin/typed/TypedExpressions.kt b/orx-expression-evaluator-typed/src/commonMain/kotlin/typed/TypedExpressions.kt index 929718b63..3b0c0fd72 100644 --- a/orx-expression-evaluator-typed/src/commonMain/kotlin/typed/TypedExpressions.kt +++ b/orx-expression-evaluator-typed/src/commonMain/kotlin/typed/TypedExpressions.kt @@ -63,6 +63,19 @@ enum class IDType { FUNCTION_ARGUMENT } +/** + * A base class for handling typed expressions in a custom language parser. + * This class provides an extensive set of overrides for various parser rules + * to allow custom implementation when these rules are triggered during parsing. + * + * @property functions Represents a mapping of functions categorized by their arity. + * @property constants Tracks constants identified during parsing. + * @property state Maintains the current state of the listener, preserving contextual information. + * + * Methods primarily handle entering and exiting parser rules for expressions, statements, and + * function calls, offering hooks to extend or modify behavior for each parsing scenario. Additionally, + * utility methods are provided to handle and propagate errors during parsing. + */ abstract class TypedExpressionListenerBase( val functions: TypedFunctionExtensions = TypedFunctionExtensions.EMPTY, val constants: (String) -> Any? = { null } @@ -940,6 +953,21 @@ expect class TypedExpressionListener( class ExpressionException(message: String) : RuntimeException(message) +/** + * Evaluates a typed expression based on the provided string input, constants, + * and function definitions. + * + * @param expression The string representation of the expression to evaluate. + * @param constants A lambda function providing constant values for specific + * variables. Returns null if a constant is not found. Defaults to a function + * returning null for any input. + * @param functions A `TypedFunctionExtensions` instance encapsulating function + * definitions for 0 to 5 arguments. Defaults to an empty set of functions. + * @return The result of the evaluated expression as an `Any?` type. + * Returns null if the evaluation produces no result. + * @throws ExpressionException If a syntax error occurs in the input expression + * or during expression evaluation. + */ fun evaluateTypedExpression( expression: String, constants: (String) -> Any? = { null },