EvalEx Documentation

EvalEx uses an EvaluationValue wrapper to store both a value and its corresponding data type. The following table maps EvalEx data types to their internal Java representations:

EvalEx supports complex data types:

• Arrays: Can be passed as Java List objects or standard Java arrays. Supports multidimensional access.
• Structures: Can be passed as Java Map objects.

These can be nested to build arbitrary data structures (e.g., a List of Maps).

// Array example
Expression arrayExpr = new Expression("values[i-1] * factors[i-1]");
EvaluationValue arrayResult = arrayExpr
    .with("values", List.of(2, 3, 4))
    .and("factors", new Object[] {2, 4, 6})
    .and("i", 1)
    .evaluate();

// Structure example
Map<String, Object> order = new HashMap<>();
order.put("id", 12345);
Map<String, Object> position = new HashMap<>();
position.put("amount", 3);
position.put("price", new BigDecimal("14.95"));
order.put("positions", List.of(position));

Expression structExpr = new Expression("order.positions[x].amount * order.positions[x].price")
    .with("order", order)
    .and("x", 0);

BigDecimal result = structExpr.evaluate().getNumberValue();

To create a custom function in EvalEx, you must implement the FunctionIfc interface. It is recommended to extend the AbstractFunction class to simplify implementation.

Function definition involves two main parts:

1. Defining logic and parameters: Create a class that implements the evaluate method. Use the @FunctionParameter annotation to define the expected arguments.
2. Registering the function: Add the function to a function dictionary or an ExpressionConfiguration so it can be recognized during expression evaluation.

The evaluate method is called during evaluation and receives the Expression context, the Token representing the function, and the EvaluationValue... parameterValues.

@FunctionParameter(name = "value")
@FunctionParameter(name = "scale")
public class RoundFunction extends AbstractFunction {
  @Override
  public EvaluationValue evaluate(
      Expression expression, Token functionToken, EvaluationValue... parameterValues) {

    EvaluationValue value = parameterValues[0];
    EvaluationValue precision = parameterValues[1];

    return new EvaluationValue(
        value
            .getNumberValue()
            .setScale(
                precision.getNumberValue().intValue(),
                expression.getConfiguration().getMathContext().getRoundingMode()));
  }
}

EvalEx uses a FunctionDictionaryIfc to store and retrieve functions used in expressions. By default, it uses MapBasedFunctionDictionary, which is case-insensitive.

To define your own dictionary, implement the FunctionDictionaryIfc interface. You must implement two core methods:

1. addFunction(String functionName, FunctionIfc function): Adds a function to the dictionary. This is called when using .withAdditionalFunctions() on an ExpressionConfiguration.
2. getFunction(String functionName): Retrieves the function implementation for a given name. Returns null if not found.

Note: Function names passed to these methods are case-sensitive, matching how they appear in the expression.

public interface FunctionDictionaryIfc {

  /**
   * Allows to add a function to the dictionary.
   * @param functionName The function name.
   * @param function The function implementation.
   */
  void addFunction(String functionName, FunctionIfc function);

  /**
   * Check if the dictionary has a function with that name.
   * @param functionName The function name to look for.
   * @return true if a function was found or false if not.
   */
  default boolean hasFunction(String functionName) {
    return getFunction(functionName) != null;
  }

  /**
   * Get the function definition for a function name.
   * @param functionName The name of the function.
   * @return The function definition or null if no function was found.
   */
  FunctionIfc getFunction(String functionName);
}

Structures are stored internally as java.util.Map<String, EvaluationValue>. When passed as a variable, map entries are converted to EvaluationValue objects.

Key features:

• Nesting: Structures can form tree-like data structures by containing other structures.
• Accessing keys with spaces: If a key contains spaces, wrap the key in double quotes within the expression (e.g., data."property name"). This also applies to array access on structure elements.
• Combination: Arrays and structures can be combined arbitrarily.

Map<String, Object> order = new HashMap<>();
order.put("id", 12345);
order.put("name", "Mary");

Map<String, Object> position = new HashMap<>();
position.put("article", 3114);
position.put("amount", 3);
position.put("price", new BigDecimal("14.95"));

order.put("positions", List.of(position));

Expression expression = new Expression("order.positions[x].amount * order.positions[x].price")
    .with("order", order)
    .and("x", 0);

BigDecimal result = expression.evaluate().getNumberValue();
System.out.println(result); // prints 44.85