Crate aether

Crate aether 

Source
Expand description

Aether - A lightweight, embeddable domain-specific language

This crate provides a complete implementation of the Aether language, including lexer, parser, evaluator, and standard library.

§Quick Start

§As a DSL (Embedded in Your Application)

When embedding Aether as a DSL, IO operations are disabled by default for security:

use aether::Aether;

// Default: IO disabled (safe for user scripts)
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),
}

Enable IO only when needed:

use aether::{Aether, IOPermissions};

// Enable only filesystem
let mut perms = IOPermissions::default();
perms.filesystem_enabled = true;
let mut engine = Aether::with_permissions(perms);

// Or enable all IO
let mut engine = Aether::with_all_permissions();

§High-Performance Engine Modes (New!)

For high-frequency, large-scale DSL execution, Aether provides three optimized engine modes:

§1. GlobalEngine - Global Singleton (Best for Single-Thread)

use aether::engine::GlobalEngine;

// Execute with isolated environment (variables cleared each time)
let result = GlobalEngine::eval_isolated("Set X 10\n(X + 20)").unwrap();
println!("Result: {}", result);

// Benefits:
// - ✅ Maximum performance (engine created only once)
// - ✅ AST cache accumulates (up to 142x speedup!)
// - ✅ Environment isolation (variables cleared between calls)
// - ⚠️ Single-threaded (uses Mutex)

§2. EnginePool - Engine Pool (Best for Multi-Thread)

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

// Create pool once (size = 2-4x CPU cores recommended)
let pool = EnginePool::new(8);

// Use across threads
let handles: Vec<_> = (0..4).map(|i| {
    let pool = pool.clone();
    thread::spawn(move || {
        let mut engine = pool.acquire(); // Auto-acquire
        let code = format!("Set X {}\n(X * 2)", i);
        engine.eval(&code)
    }) // Auto-return on scope exit
}).collect();

// Benefits:
// - ✅ Multi-thread safe (lock-free queue)
// - ✅ RAII pattern (auto-return to pool)
// - ✅ Environment isolation (cleared on acquire)
// - ✅ AST cache per engine

§3. ScopedEngine - Closure Style (Best for Simplicity)

use aether::engine::ScopedEngine;

// Closure style (like Py3o)
let result = ScopedEngine::with(|engine| {
    engine.eval("Set X 10")?;
    engine.eval("(X + 20)")
}).unwrap();

// Or simplified version
let result = ScopedEngine::eval("Set X 10\n(X + 20)").unwrap();

// Benefits:
// - ✅ Complete isolation (new engine each time)
// - ✅ Clean API (auto lifetime management)
// - ⚠️ Lower performance (no cache reuse)

§Mode Comparison

FeatureGlobalEngineEnginePoolScopedEngine
Performance⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐⭐
Multi-thread❌✅✅
Isolation✅✅✅
AST Cache✅✅❌
Use CaseSingle-thread high-freqMulti-threadOccasional

For better performance, load only the stdlib modules you need:

use aether::Aether;

// Load only string and array utilities
let mut engine = Aether::new()
    .with_stdlib_string_utils()
    .unwrap()
    .with_stdlib_array_utils()
    .unwrap();

// Or load data structures
let mut engine2 = Aether::new()
    .with_stdlib_set()
    .unwrap()
    .with_stdlib_queue()
    .unwrap()
    .with_stdlib_stack()
    .unwrap();

// Available modules:
// - 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()

§As a Standalone Language (Command-Line Tool)

The aether command-line tool automatically enables all IO permissions, allowing scripts to freely use file and network operations:

# All IO operations work in CLI mode
aether script.aether

Re-exports§

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

Modules§

ast
Abstract Syntax Tree (AST) definitions for Aether
builtins
Built-in functions standard library
cache
AST缓存机制,减少重复解析
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
pytranspile
runtime
运行时限制和能力
sandbox
沙箱模块：提供安全隔离和权限控制能力
stdlib
Aether Standard Library
token
Token definitions for the Aether lexer
value
Runtime value types for the Aether language

Structs§

Aether
Main Aether engine struct