Class AstEvaluator

java.lang.Object
cloud.opencode.base.expression.eval.AstEvaluator
All Implemented Interfaces:
Evaluator
public class AstEvaluator extends Object implements Evaluator
AST Evaluator AST 求值器

The default evaluator that traverses and evaluates AST nodes. Uses the visitor pattern to evaluate different node types.

默认求值器，遍历和求值 AST 节点。使用访问者模式来求值不同的节点类型。

Features | 主要功能:

  • Evaluate single nodes or node lists - 求值单个节点或节点列表
  • Typed evaluation: boolean, number, string - 类型化求值: 布尔值、数字、字符串
  • Timeout-based evaluation - 基于超时的求值
  • Singleton and instance-based usage - 单例和基于实例的使用

Usage Examples | 使用示例:

AstEvaluator evaluator = AstEvaluator.getInstance();
Node ast = Parser.parse("x + y");
Object result = evaluator.evaluate(ast, ctx);

// Typed evaluation
boolean flag = evaluator.evaluateAsBoolean(conditionNode, ctx);
Number num = evaluator.evaluateAsNumber(calcNode, ctx);

Security | 安全性:

  • Thread-safe: Yes, stateless singleton - 线程安全: 是，无状态单例
  • Null-safe: Yes, null node returns null - 空值安全: 是，null节点返回null

Performance | 性能特性:

  • Time complexity: O(n) for evaluate where n is the number of AST nodes - 时间复杂度: evaluate 为 O(n)，n为 AST 节点数量
  • Space complexity: O(d) call stack where d is the expression nesting depth - 空间复杂度: O(d) 调用栈，d为表达式嵌套深度
Since:
JDK 25, opencode-base-expression V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Constructor Details

    • AstEvaluator

      public AstEvaluator()
      Create a new AstEvaluator 创建新的 AstEvaluator

  • Method Details

    • getInstance

      public static AstEvaluator getInstance()
      Get the singleton instance 获取单例实例
      Returns:
      the instance | 实例

    • evaluate

      public Object evaluate(Node node, EvaluationContext context)
      Description copied from interface: Evaluator
      Evaluate an AST node 求值 AST 节点
      Specified by:
      evaluate in interface Evaluator
      Parameters:
      node - the AST node | AST 节点
      context - the evaluation context | 求值上下文
      Returns:
      the evaluation result | 求值结果

    • evaluateAll

      public List<Object> evaluateAll(List<Node> nodes, EvaluationContext context)
      Evaluate a list of nodes 求值节点列表
      Parameters:
      nodes - the nodes | 节点列表
      context - the context | 上下文
      Returns:
      the results | 结果列表

    • evaluateAsBoolean

      public boolean evaluateAsBoolean(Node node, EvaluationContext context)
      Evaluate node and expect boolean result 求值节点并期望布尔结果
      Parameters:
      node - the node | 节点
      context - the context | 上下文
      Returns:
      the boolean result | 布尔结果

    • evaluateAsNumber

      public Number evaluateAsNumber(Node node, EvaluationContext context)
      Evaluate node and expect number result 求值节点并期望数字结果
      Parameters:
      node - the node | 节点
      context - the context | 上下文
      Returns:
      the number result | 数字结果

    • evaluateAsString

      public String evaluateAsString(Node node, EvaluationContext context)
      Evaluate node and expect string result 求值节点并期望字符串结果
      Parameters:
      node - the node | 节点
      context - the context | 上下文
      Returns:
      the string result | 字符串结果

    • evaluateWithTimeout

      public Object evaluateWithTimeout(Node node, EvaluationContext context, long timeoutMs)
      Evaluate with timeout (post-hoc detection) 带超时求值（事后检测）

      Important: This method uses post-hoc timeout detection, meaning the evaluation runs to completion and the elapsed time is checked afterward. It does NOT interrupt a long-running evaluation mid-execution. For expressions that may run indefinitely (e.g., deeply nested or recursive), this method will not prevent them from consuming CPU time beyond the specified timeout. Consider using an external mechanism (e.g., a virtual thread with interrupt-based timeout) for strict enforcement.

      重要：此方法使用事后超时检测，即求值运行完成后才检查耗时。 它不会在执行过程中中断长时间运行的求值。对于可能无限运行的表达式， 此方法不会阻止它们在超时之后继续消耗 CPU 时间。

      Parameters:
      node - the node | 节点
      context - the context | 上下文
      timeoutMs - the timeout in milliseconds | 超时毫秒数
      Returns:
      the result | 结果
      Throws:
      OpenExpressionException - if evaluation exceeded timeout (detected post-hoc) | 如果求值超过超时（事后检测）

    • eval

      public static Object eval(Node node, EvaluationContext context)
      Static method to evaluate expression 静态方法求值表达式
      Parameters:
      node - the node | 节点
      context - the context | 上下文
      Returns:
      the result | 结果