Crate aether

Crate aether 

Source
Expand description

Aether - 一个轻量级、可嵌入的领域特定语言

这个 crate 提供了 Aether 语言的完整实现， 包括词法分析器、解析器、求值器和标准库。

§快速开始

§作为 DSL（嵌入到您的应用程序中）

当将 Aether 作为 DSL 嵌入时，IO 操作默认禁用以确保安全性：

use aether::Aether;

// 默认：IO 禁用（对用户脚本安全）
let mut engine = Aether::new();
let code = r#"
    Set X 10
    Set Y 20
    (X + Y)
"#;

match engine.eval(code) {
    Ok(result) => println!("Result: {}", result),
    Err(e) => eprintln!("Error: {}", e),
}

仅在需要时启用 IO：

use aether::{Aether, IOPermissions};

// 仅启用文件系统
let mut perms = IOPermissions::default();
perms.filesystem_enabled = true;
let mut engine = Aether::with_permissions(perms);

// 或启用所有 IO
let mut engine = Aether::with_all_permissions();

§高性能引擎模式（新增！）

对于高频、大规模 DSL 执行，Aether 提供了三种优化的引擎模式：

§1. GlobalEngine - 全局单例（最适合单线程）

use aether::engine::GlobalEngine;

// 使用隔离环境执行（每次清除变量）
let result = GlobalEngine::eval_isolated("Set X 10\n(X + 20)").unwrap();
println!("Result: {}", result);

// 优势：
// - ✅ 最大性能（引擎仅创建一次）
// - ✅ AST 缓存累积（高达 142 倍加速！）
// - ✅ 环境隔离（每次调用清除变量）
// - ⚠️ 单线程（使用 Mutex）

§2. EnginePool - 引擎池（最适合多线程）

use aether::engine::EnginePool;
use std::thread;

// 一次性创建池（大小 = 推荐 2-4 倍 CPU 核心数）
let pool = EnginePool::new(8);

// 跨线程使用
let handles: Vec<_> = (0..4).map(|i| {
    let pool = pool.clone();
    thread::spawn(move || {
        let mut engine = pool.acquire(); // 自动获取
        let code = format!("Set X {}\n(X * 2)", i);
        engine.eval(&code)
    }) // 作用域退出时自动返回
}).collect();

// 优势：
// - ✅ 多线程安全（无锁队列）
// - ✅ RAII 模式（自动返回池）
// - ✅ 环境隔离（获取时清除）
// - ✅ 每个引擎的 AST 缓存

§3. ScopedEngine - 闭包风格（最适合简单性）

use aether::engine::ScopedEngine;

// 闭包风格（类似 Py3o）
let result = ScopedEngine::with(|engine| {
    engine.eval("Set X 10")?;
    engine.eval("(X + 20)")
}).unwrap();

// 或简化版本
let result = ScopedEngine::eval("Set X 10\n(X + 20)").unwrap();

// 优势：
// - ✅ 完全隔离（每次新建引擎）
// - ✅ 简洁 API（自动生命周期管理）
// - ⚠️ 较低性能（无缓存重用）

§模式对比

特性GlobalEngineEnginePoolScopedEngine
性能⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
多线程❌✅✅
隔离✅✅✅
AST 缓存✅✅❌
使用场景单线程高频多线程偶尔使用

§选择性标准库加载（推荐用于 DSL）

为获得更好性能，仅加载您需要的 stdlib 模块：

use aether::Aether;

// 仅加载字符串和数组工具
let mut engine = Aether::new()
    .with_stdlib_string_utils()
    .unwrap()
    .with_stdlib_array_utils()
    .unwrap();

// 或加载数据结构
let mut engine2 = Aether::new()
    .with_stdlib_set()
    .unwrap()
    .with_stdlib_queue()
    .unwrap()
    .with_stdlib_stack()
    .unwrap();

// 可用模块：
// - with_stdlib_string_utils()
// - with_stdlib_array_utils()
// - with_stdlib_validation()
// - with_stdlib_datetime()
// - with_stdlib_testing()
// - with_stdlib_set()
// - with_stdlib_queue()
// - with_stdlib_stack()
// - with_stdlib_heap()
// - with_stdlib_sorting()
// - with_stdlib_json()
// - with_stdlib_csv()
// - with_stdlib_functional()
// - with_stdlib_cli_utils()
// - with_stdlib_text_template()
// - with_stdlib_regex_utils()

§作为独立语言（命令行工具）

aether 命令行工具自动启用所有 IO 权限， 允许脚本自由使用文件和网络操作：

# 在 CLI 模式下，所有 IO 操作都有效
aether script.aether

Re-exports§

pub use crate::ast::Expr;
pub use crate::ast::Program;
pub use crate::ast::Stmt;
pub use crate::builtins::BuiltInRegistry;
pub use crate::builtins::IOPermissions;
pub use crate::cache::ASTCache;
pub use crate::cache::CacheStats;
pub use crate::environment::Environment;
pub use crate::evaluator::ErrorReport;
pub use crate::evaluator::EvalResult;
pub use crate::evaluator::Evaluator;
pub use crate::evaluator::RuntimeError;
pub use crate::lexer::Lexer;
pub use crate::module_system::DisabledModuleResolver;
pub use crate::module_system::FileSystemModuleResolver;
pub use crate::module_system::ModuleResolver;
pub use crate::optimizer::Optimizer;
pub use crate::parser::ParseError;
pub use crate::parser::Parser;
pub use crate::runtime::ExecutionLimitError;
pub use crate::runtime::ExecutionLimits;
pub use crate::runtime::TraceEntry;
pub use crate::runtime::TraceFilter;
pub use crate::runtime::TraceLevel;
pub use crate::runtime::TraceStats;
pub use crate::sandbox::ExecutionMetrics;
pub use crate::sandbox::MetricsCollector;
pub use crate::sandbox::MetricsSnapshot;
pub use crate::sandbox::ModuleCacheManager;
pub use crate::sandbox::ModuleCacheStats;
pub use crate::sandbox::ModuleMetrics;
pub use crate::sandbox::PathRestriction;
pub use crate::sandbox::PathValidationError;
pub use crate::sandbox::PathValidator;
pub use crate::sandbox::SandboxConfig;
pub use crate::sandbox::SandboxPolicy;
pub use crate::sandbox::ScopedValidator;
pub use crate::token::Token;
pub use crate::value::Value;

Modules§

ast
Abstract Syntax Tree (AST) definitions for Aether
builtins
Built-in functions standard library
cache
AST缓存机制,减少重复解析
debugger
Interactive debugger for Aether
engine
Aether Engine - 高性能引擎管理模块
environment
Environment for variable storage and scoping 优化版本: 减少Rc/RefCell开销, 使用索引代替指针
evaluator
Evaluator for executing Aether AST
ffi
C-FFI interface for Aether language bindings
lexer
Lexer for the Aether language
module_system
optimizer
代码优化器 - 包含尾递归优化、常量折叠等
parser
Parser for the Aether language
runtime
运行时限制和能力
sandbox
沙箱模块：提供安全隔离和权限控制能力
stdlib
Aether Standard Library
token
Token definitions for the Aether lexer
value
Runtime value types for the Aether language

Structs§

Aether
主要的 Aether 引擎结构体