kaze/orx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[orx-expression-evaluator-typed] Add generated and verified documentation

Browse Source
This commit is contained in:
Edwin Jakobs
2025-01-18 23:15:18 +01:00
parent 66c4c2f459
commit 9a84b12198
2 changed files with 126 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

103
orx-expression-evaluator-typed/src/commonMain/kotlin/typed/CompiledFunctions.kt
View File

@@ -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 <T0, R> compileFunction1(
expression: String,
@@ -38,6 +47,21 @@ fun <T0, R> 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 <T0, R> compileFunction1OrNull(
expression: String,
parameter0: String,
@@ -53,8 +77,25 @@ fun <T0, R> 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 <T0, T1, R> compileFunction2(
expression: String,
parameter0: String,
@@ -93,6 +134,26 @@ fun <T0, T1, R> 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 <T0, T1, R> compileFunction2OrNull(
expression: String,
parameter0: String,
@@ -109,8 +170,23 @@ fun <T0, T1, R> 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 <T0, T1, T2, R> compileFunction3(
expression: String,
parameter0: String,
@@ -157,6 +233,23 @@ fun <T0, T1, T2, R> 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 <T0, T1, T2, R> compileFunction3OrNull(
expression: String,
parameter0: String,

28
orx-expression-evaluator-typed/src/commonMain/kotlin/typed/TypedExpressions.kt
View File

@@ -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 },