aether/
lib.rs

1//! Aether - 一个轻量级、可嵌入的领域特定语言
2//!
3//! 这个 crate 提供了 Aether 语言的完整实现，
4//! 包括词法分析器、解析器、求值器和标准库。
5//!
6//! # 快速开始
7//!
8//! ## 作为 DSL（嵌入到您的应用程序中）
9//!
10//! 当将 Aether 作为 DSL 嵌入时，IO 操作**默认禁用**以确保安全性：
11//!
12//! ```
13//! use aether::Aether;
14//!
15//! // 默认：IO 禁用（对用户脚本安全）
16//! let mut engine = Aether::new();
17//! let code = r#"
18//!     Set X 10
19//!     Set Y 20
20//!     (X + Y)
21//! "#;
22//!
23//! match engine.eval(code) {
24//!     Ok(result) => println!("Result: {}", result),
25//!     Err(e) => eprintln!("Error: {}", e),
26//! }
27//! ```
28//!
29//! 仅在需要时启用 IO：
30//!
31//! ```
32//! use aether::{Aether, IOPermissions};
33//!
34//! // 仅启用文件系统
35//! let mut perms = IOPermissions::default();
36//! perms.filesystem_enabled = true;
37//! let mut engine = Aether::with_permissions(perms);
38//!
39//! // 或启用所有 IO
40//! let mut engine = Aether::with_all_permissions();
41//! ```
42//!
43//! ## 高性能引擎模式（新增！）
44//!
45//! 对于**高频、大规模 DSL 执行**，Aether 提供了三种优化的引擎模式：
46//!
47//! ### 1. GlobalEngine - 全局单例（最适合单线程）
48//!
49//! ```rust
50//! use aether::engine::GlobalEngine;
51//!
52//! // 使用隔离环境执行（每次清除变量）
53//! let result = GlobalEngine::eval_isolated("Set X 10\n(X + 20)").unwrap();
54//! println!("Result: {}", result);
55//!
56//! // 优势：
57//! // - ✅ 最大性能（引擎仅创建一次）
58//! // - ✅ AST 缓存累积（高达 142 倍加速！）
59//! // - ✅ 环境隔离（每次调用清除变量）
60//! // - ⚠️ 单线程（使用 Mutex）
61//! ```
62//!
63//! ### 2. EnginePool - 引擎池（最适合多线程）
64//!
65//! ```rust
66//! use aether::engine::EnginePool;
67//! use std::thread;
68//!
69//! // 一次性创建池（大小 = 推荐 2-4 倍 CPU 核心数）
70//! let pool = EnginePool::new(8);
71//!
72//! // 跨线程使用
73//! let handles: Vec<_> = (0..4).map(|i| {
74//!     let pool = pool.clone();
75//!     thread::spawn(move || {
76//!         let mut engine = pool.acquire(); // 自动获取
77//!         let code = format!("Set X {}\n(X * 2)", i);
78//!         engine.eval(&code)
79//!     }) // 作用域退出时自动返回
80//! }).collect();
81//!
82//! // 优势：
83//! // - ✅ 多线程安全（无锁队列）
84//! // - ✅ RAII 模式（自动返回池）
85//! // - ✅ 环境隔离（获取时清除）
86//! // - ✅ 每个引擎的 AST 缓存
87//! ```
88//!
89//! ### 3. ScopedEngine - 闭包风格（最适合简单性）
90//!
91//! ```rust
92//! use aether::engine::ScopedEngine;
93//!
94//! // 闭包风格（类似 Py3o）
95//! let result = ScopedEngine::with(|engine| {
96//!     engine.eval("Set X 10")?;
97//!     engine.eval("(X + 20)")
98//! }).unwrap();
99//!
100//! // 或简化版本
101//! let result = ScopedEngine::eval("Set X 10\n(X + 20)").unwrap();
102//!
103//! // 优势：
104//! // - ✅ 完全隔离（每次新建引擎）
105//! // - ✅ 简洁 API（自动生命周期管理）
106//! // - ⚠️ 较低性能（无缓存重用）
107//! ```
108//!
109//! ### 模式对比
110//!
111//! | 特性 | GlobalEngine | EnginePool | ScopedEngine |
112//! |---------|-------------|------------|--------------|
113//! | 性能 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | ⭐⭐⭐ |
114//! | 多线程 | ❌ | ✅ | ✅ |
115//! | 隔离 | ✅ | ✅ | ✅ |
116//! | AST 缓存 | ✅ | ✅ | ❌ |
117//! | 使用场景 | 单线程高频 | 多线程 | 偶尔使用 |
118//!
119//! ### 选择性标准库加载（推荐用于 DSL）
120//!
121//! 为获得更好性能，仅加载您需要的 stdlib 模块：
122//!
123//! ```
124//! use aether::Aether;
125//!
126//! // 仅加载字符串和数组工具
127//! let mut engine = Aether::new()
128//!     .with_stdlib_string_utils()
129//!     .unwrap()
130//!     .with_stdlib_array_utils()
131//!     .unwrap();
132//!
133//! // 或加载数据结构
134//! let mut engine2 = Aether::new()
135//!     .with_stdlib_set()
136//!     .unwrap()
137//!     .with_stdlib_queue()
138//!     .unwrap()
139//!     .with_stdlib_stack()
140//!     .unwrap();
141//!
142//! // 可用模块：
143//! // - with_stdlib_string_utils()
144//! // - with_stdlib_array_utils()
145//! // - with_stdlib_validation()
146//! // - with_stdlib_datetime()
147//! // - with_stdlib_testing()
148//! // - with_stdlib_set()
149//! // - with_stdlib_queue()
150//! // - with_stdlib_stack()
151//! // - with_stdlib_heap()
152//! // - with_stdlib_sorting()
153//! // - with_stdlib_json()
154//! // - with_stdlib_csv()
155//! // - with_stdlib_functional()
156//! // - with_stdlib_cli_utils()
157//! // - with_stdlib_text_template()
158//! // - with_stdlib_regex_utils()
159//! ```
160//!
161//! ## 作为独立语言（命令行工具）
162//!
163//! `aether` 命令行工具自动启用所有 IO 权限，
164//! 允许脚本自由使用文件和网络操作：
165//!
166//! ```bash
167//! # 在 CLI 模式下，所有 IO 操作都有效
168//! aether script.aether
169//! ```
170
171pub mod ast;
172pub mod builtins;
173pub mod cache;
174pub mod debugger;
175pub mod engine;
176pub mod environment;
177pub mod evaluator;
178pub mod lexer;
179pub mod module_system;
180pub mod optimizer;
181pub mod parser;
182pub mod runtime;
183pub mod sandbox;
184pub mod stdlib;
185pub mod token;
186pub mod value;
187
188// FFI 和语言绑定
189pub mod ffi;
190
191#[cfg(target_arch = "wasm32")]
192pub mod wasm;
193
194mod api;
195mod prelude;
196
197pub use api::Aether;
198pub use prelude::*;
aether/lib.rs

aether/
lib.rs
