Struct Aether 

pub struct Aether { /* private fields */ }

主要的 Aether 引擎结构体

Implementations

impl Aether

pub fn cache_stats(&self) -> CacheStats

获取缓存统计信息

pub fn clear_cache(&mut self)

清空缓存

pub fn set_optimization( &mut self, constant_folding: bool, dead_code: bool, tail_recursion: bool, )

设置优化选项

impl Aether

pub fn new() -> Self

创建新的 Aether 引擎实例

用于 DSL 嵌入：IO 操作默认禁用以确保安全性。 使用 with_permissions() 或 with_all_permissions() 来启用 IO。

用于 CLI 使用：命令行工具默认使用 with_all_permissions()。

pub fn with_permissions(permissions: IOPermissions) -> Self

使用自定义 IO 权限创建新的 Aether 引擎

pub fn with_all_permissions() -> Self

创建启用所有 IO 权限的新 Aether 引擎

pub fn with_stdlib() -> Result<Self, String>

创建预加载标准库的新 Aether 引擎

这将创建一个具有所有权限的引擎，并自动加载 所有标准库模块（string_utils、array_utils、validation、datetime、testing）。

impl Aether

pub fn eval(&mut self, code: &str) -> Result<Value, String>

求值 Aether 代码并返回结果

pub fn eval_report(&mut self, code: &str) -> Result<Value, ErrorReport>

求值 Aether 代码并在失败时返回结构化的错误报告。

这适用于需要机器可读诊断的集成。

pub fn set_module_resolver(&mut self, resolver: Box<dyn ModuleResolver>)

配置用于 Import/Export 的模块解析器。

默认情况下（DSL 嵌入），解析器出于安全考虑被禁用。

pub fn push_import_base(&mut self, module_id: String, base_dir: Option<PathBuf>)

推送用于解析相对导入的基础目录上下文。

这通常由基于文件的运行器（CLI）在调用 eval() 之前使用。

pub fn pop_import_base(&mut self)

弹出最近的基础目录上下文。

pub fn eval_file(&mut self, path: impl AsRef<Path>) -> Result<Value, String>

从文件路径求值 Aether 脚本。

这是一个便利包装器，它：

• 读取文件
• 推送导入基础上下文（module_id = 规范路径；base_dir = 父目录）
• 求值代码
• 弹出导入基础上下文

注意：这不会启用任何模块解析器。为了 DSL 安全性，除非您明确调用 set_module_resolver(...)，否则模块加载保持禁用状态。

pub fn eval_file_report( &mut self, path: impl AsRef<Path>, ) -> Result<Value, ErrorReport>

从文件路径求值 Aether 脚本，在失败时返回结构化的错误报告。

pub fn set_global(&mut self, name: &str, value: Value)

从宿主应用程序设置全局变量，而不使用 eval()。

当您已经有 Rust 端数据并希望将其作为 Value 注入脚本环境时，这很有用。

pub fn reset_env(&mut self)

重置运行时环境（变量/函数），同时保持内置函数注册。

注意：这会清除通过 eval() 引入的任何内容（包括 stdlib 代码）。

pub fn with_isolated_scope<R>( &mut self, f: impl FnOnce(&mut Aether) -> Result<R, String>, ) -> Result<R, String>

在隔离的子作用域内运行闭包。

在闭包内注入或定义的所有变量/函数将在返回时被丢弃，而外部环境被保留。

这是为 “DSL 宿主” 场景设计的：注入 Rust 数据 + 加载每请求的 Aether 函数（例如从 DB）+ 运行脚本，而不跨请求污染。

impl Aether

pub fn with_limits(self, limits: ExecutionLimits) -> Self

使用执行限制创建新的 Aether 引擎

pub fn set_limits(&mut self, limits: ExecutionLimits)

设置执行限制

pub fn limits(&self) -> &ExecutionLimits

获取当前执行限制

impl Aether

pub fn load_stdlib_module(&mut self, module_name: &str) -> Result<(), String>

加载特定的标准库模块

可用模块：“string_utils”、“array_utils”、“validation”、“datetime”、“testing”

pub fn load_all_stdlib(&mut self) -> Result<(), String>

加载所有标准库模块

pub fn with_stdlib_string_utils(self) -> Result<Self, String>

加载字符串工具模块（可链式调用）

pub fn with_stdlib_array_utils(self) -> Result<Self, String>

加载数组工具模块（可链式调用）

pub fn with_stdlib_validation(self) -> Result<Self, String>

加载验证模块（可链式调用）

pub fn with_stdlib_datetime(self) -> Result<Self, String>

加载日期时间模块（可链式调用）

pub fn with_stdlib_testing(self) -> Result<Self, String>

加载测试框架模块（可链式调用）

pub fn with_stdlib_set(self) -> Result<Self, String>

加载集合数据结构模块（可链式调用）

pub fn with_stdlib_queue(self) -> Result<Self, String>

加载队列数据结构模块（可链式调用）

pub fn with_stdlib_stack(self) -> Result<Self, String>

加载栈数据结构模块（可链式调用）

pub fn with_stdlib_heap(self) -> Result<Self, String>

加载堆数据结构模块（可链式调用）

pub fn with_stdlib_sorting(self) -> Result<Self, String>

加载排序算法模块（可链式调用）

pub fn with_stdlib_json(self) -> Result<Self, String>

加载 JSON 处理模块（可链式调用）

pub fn with_stdlib_csv(self) -> Result<Self, String>

加载 CSV 处理模块（可链式调用）

pub fn with_stdlib_functional(self) -> Result<Self, String>

加载函数式编程工具模块（可链式调用）

pub fn with_stdlib_cli_utils(self) -> Result<Self, String>

加载 CLI 工具模块（可链式调用）

pub fn with_stdlib_text_template(self) -> Result<Self, String>

加载文本模板引擎模块（可链式调用）

pub fn with_stdlib_regex_utils(self) -> Result<Self, String>

加载正则表达式工具模块（可链式调用）

impl Aether

pub fn take_trace(&mut self) -> Vec<String>

清空内存中的 TRACE 缓冲区。

这是为 DSL 安全调试设计的：脚本调用 TRACE(...) 来记录 值，宿主应用程序通过此方法带外读取它们。

pub fn clear_trace(&mut self)

清除 TRACE 缓冲区而不返回它。

pub fn trace_records(&self) -> Vec<TraceEntry>

获取所有结构化的跟踪条目

返回带有级别、类别、时间戳等的结构化跟踪条目向量。

pub fn trace_by_level(&self, level: TraceLevel) -> Vec<TraceEntry>

按级别过滤跟踪条目

pub fn trace_by_category(&self, category: &str) -> Vec<TraceEntry>

按类别过滤跟踪条目

pub fn trace_by_label(&self, label: &str) -> Vec<TraceEntry>

按标签过滤跟踪条目

pub fn trace_filter(&self, filter: &TraceFilter) -> Vec<TraceEntry>

对跟踪条目应用复杂过滤器

pub fn trace_stats(&self) -> TraceStats

获取跟踪统计信息

返回关于跟踪条目的统计信息，包括按级别和类别的计数。

pub fn set_trace_buffer_size(&mut self, size: usize)

设置 TRACE 缓冲区大小

这将设置 TRACE 缓冲区可以存储的最大条目数。 如果新大小小于当前条目数，多余的条目将被从缓冲区前端移除。

pub fn step_count(&self) -> usize

获取当前顶级执行的 step 计数。

该计数在每次调用 eval(...) / eval_report(...)（以及它们的文件包装器）开始时被重置。

说明：step 目前按“语句级”计数（每求值一条语句 +1）。

Trait Implementations

impl Default for Aether

fn default() -> Self

Returns the “default value” for a type.