aether-azathoth 0.2.0

A lightweight, embeddable domain-specific language (DSL) interpreter with rich standard library
Documentation

Aether

轻量级、可嵌入的领域特定语言 (DSL)

Crates.io Documentation License

高性能 · 易集成 · 跨平台 · 安全优先

📋 目录

🎯 概述

Aether 是一个现代化、轻量级的脚本语言，设计用于嵌入到 Rust、Go 和 TypeScript 应用程序中。

核心特性

  • 🚀 高性能: 基于 Rust，带 AST 缓存和常量折叠优化
  • 🔌 易于集成: 简单的 API，支持 Rust/Go/TypeScript
  • 🌍 跨平台: x86_64、ARM64、WebAssembly
  • ✨ 现代特性: Generator、惰性求值、闭包
  • 📝 简洁语法: 易学易读，UPPER_SNAKE_CASE 命名
  • 🔒 安全优先: 库模式默认禁用 IO，CLI 模式自动启用

标准库 (200+ 函数)

  • 基础: I/O、类型转换、字符串/数组/字典操作
  • 文件系统: READ_FILE, WRITE_FILE, LIST_DIR, CREATE_DIR 等
  • 网络: HTTP_GET, HTTP_POST, HTTP_PUT, HTTP_DELETE
  • 数学: 线性代数、统计、概率分布、矩阵运算
  • 精确计算: 分数运算、固定精度金融计算
  • 薪资计算: 工资、加班费、个税、社保（78个函数）
  • 报表生成: Excel创建/写入/保存、数据格式化（8个函数）
  • 报表生成: Excel/Word/PDF 操作、数据格式化、透视表（🆕）

🚀 快速开始

安装

# Rust 库
cargo add aether

# 命令行工具
cargo install aether

# Go
go get github.com/yourusername/aether-go

# TypeScript/JavaScript
npm install @yourusername/aether

Hello World

命令行 (IO 自动启用):

# 创建 hello.aether
echo 'Println("Hello, Aether!")' > hello.aether

# 运行
aether hello.aether

Rust 嵌入 (默认安全):

use aether::Aether;

fn main() {
    let mut engine = Aether::new(); // IO 默认禁用
    
    let result = engine.eval(r#"
        Set X 10
        Set Y 20
        (X + Y)
    "#).unwrap();
    
    println!("结果: {}", result); // 输出: 30
}

启用 IO (可选):

use aether::{Aether, IOPermissions};

// 完全启用 IO
let mut engine = Aether::with_all_permissions();

// 或仅启用文件系统
let permissions = IOPermissions {
    filesystem_enabled: true,
    network_enabled: false,
};
let mut engine = Aether::with_permissions(permissions);

engine.eval(r#"
    WriteFile("output.txt", "Hello!")
    Println(ReadFile("output.txt"))
"#).unwrap();

📚 语言特性

1. 基础语法

// 变量 (必须 UPPER_SNAKE_CASE)
Set COUNT 10
Set MESSAGE "Hello, Aether"
Set NUMBERS [1, 2, 3, 4, 5]
Set USER {"name": "Alice", "age": 30}

// 函数
Func ADD (A, B) {
    Return (A + B)
}

Set RESULT ADD(5, 3)
Println("5 + 3 =", RESULT)

2. 控制流

// If-Else
Func ABS (X) {
    If (X < 0) {
        Return (0 - X)
    } Else {
        Return X
    }
}

// For 循环
For I In RANGE(0, 5) {
    Println("数字:", I)
}

// While 循环
Set I 0
While (I < 5) {
    Println(I)
    Set I (I + 1)
}

3. Generator (惰性序列)

Generator FIBONACCI (LIMIT) {
    Set A 0
    Set B 1
    Set COUNT 0
    
    While (COUNT < LIMIT) {
        Yield A
        Set NEXT (A + B)
        Set A B
        Set B NEXT
        Set COUNT (COUNT + 1)
    }
}

// 使用
For NUM In FIBONACCI(10) {
    Println(NUM)
}

4. 惰性求值

// 延迟计算，仅在需要时执行
Lazy EXPENSIVE_DATA (
    Println("正在加载大数据集...")
    Return LOAD_FILE("big_data.json")
)

// 数据仅在访问时加载
If (NEEDS_ANALYSIS) {
    Set DATA EXPENSIVE_DATA  // 此时才执行
    PROCESS(DATA)
}

5. 精确和精度算术

// 问题：浮点精度
Set A 0.1
Set B 0.2
Println(A + B)  // 可能显示: 0.30000000000000004

// 解决方案：分数运算（精确）
Set FA TO_FRACTION(0.1)
Set FB TO_FRACTION(0.2)
Set FC FRAC_ADD(FA, FB)
Println(FC)           // 显示: 3/10
Println(TO_FLOAT(FC)) // 显示: 0.3

// 金融计算（固定精度）
Set PRICE1 19.99
Set PRICE2 29.99
Set TOTAL ADD_WITH_PRECISION(PRICE1, PRICE2, 2)
Println(TOTAL)  // 显示: 49.98

Set TAX MUL_WITH_PRECISION(TOTAL, 0.08, 2)
Println(TAX)    // 显示: 4.00

6. 文件系统操作

// CLI 模式：自动工作
WriteFile("data.txt", "Hello, World!")
Set CONTENT ReadFile("data.txt")
Println(CONTENT)

If FileExists("data.txt") {
    Println("文件存在!")
    DeleteFile("data.txt")
}

// 目录操作
CreateDir("output")
Set FILES ListDir(".")
For FILE In FILES {
    Println(FILE)
}

7. 网络操作

// HTTP GET
Set RESPONSE HttpGet("https://api.github.com")
Println(RESPONSE)

// HTTP POST
Set DATA '{"name": "test"}'
Set RESULT HttpPost(
    "https://api.example.com/data",
    DATA,
    "application/json"
)
Println(RESULT)

8. 报表生成 (🆕)

// Excel 操作
Set WORKBOOK EXCEL_CREATE()
EXCEL_WRITE_ROW(WORKBOOK, "Sheet1", 0, ["姓名", "销售额", "完成率"])
EXCEL_WRITE_ROW(WORKBOOK, "Sheet1", 1, ["张三", 120000, 0.95])
EXCEL_SAVE(WORKBOOK, "report.xlsx")

// 数据格式化
Set AMOUNT 1234567.89
Println(FORMAT_NUMBER(AMOUNT, 2))        // "1,234,567.89"
Println(FORMAT_CURRENCY(AMOUNT, "¥", 2)) // "¥1,234,567.89"
Println(FORMAT_PERCENT(0.1234, 2))       // "12.34%"

// Word 文档
Set DOC WORD_CREATE()
WORD_ADD_HEADING(DOC, "销售报告", 1)
WORD_ADD_PARAGRAPH(DOC, "2024年第一季度总结", "Normal")
WORD_SAVE(DOC, "report.docx")

// 数据透视（规划中）
Set PIVOT PIVOT_TABLE(DATA, ["region"], ["product"], ["amount"], "sum")

9. 错误处理

// 错误示例
Set myVar 10
// ❌ 错误: 变量名必须使用全大写字母和下划线
// 正确: Set MY_VAR 10

Set RESULT (X + Y
// ❌ 错误: Parse error at line 1, column 18: Expected RightParen

// 正确
Set RESULT (X + Y)

🔒 安全模型

CLI 模式 vs 库模式

模式 IO 状态 使用场景
CLI 默认启用 直接运行脚本，用户明确信任
库 默认禁用 嵌入应用，脚本可能不可信

权限控制

use aether::{Aether, IOPermissions};

// 1. 无 IO（最安全，默认）
let mut engine = Aether::new();

// 2. 仅文件系统
let permissions = IOPermissions {
    filesystem_enabled: true,
    network_enabled: false,
};
let mut engine = Aether::with_permissions(permissions);

// 3. 完全权限
let mut engine = Aether::with_all_permissions();

命名约定强制

所有变量、函数、参数必须使用 UPPER_SNAKE_CASE：

// ✅ 正确
Set MY_VARIABLE 10
Func CALCULATE_TOTAL (PRICE, TAX_RATE) { }

// ❌ 错误
Set myVariable 10      // 会报错
Func calculateTotal () // 会报错

⚡ 性能优化

Aether v0.2.0 引入了多项性能优化：

1. AST 缓存 (50-140x 加速)

自动缓存已解析的代码，避免重复解析：

let mut engine = Aether::new();
let code = "Set X 10\n(X + 20)";

// 第一次：解析 + 执行
engine.eval(code)?; // ~400µs

// 第二次：缓存命中 + 执行
engine.eval(code)?; // ~2.8µs (142x 快!)

// 查看缓存统计
println!("{}", engine.cache_stats());
// 输出: 命中率: 50.0%, 加速比: 142x

2. 常量折叠

编译时计算常量表达式：

// 优化前
Set X (2 + 3 * 4)

// 优化后（自动）
Set X 14

3. 死代码消除

移除永不执行的代码：

// 优化前
While False {
    Println("永远不执行")
}

// 优化后（自动删除整个循环）

4. 环境管理优化

  • HashMap 预分配容量
  • 热路径/冷路径分离
  • 环境对象池复用
  • 结果: 变量访问快 10-15%

自定义优化选项

let mut engine = Aether::new();

// 控制优化
engine.set_optimization(
    true,  // 常量折叠
    true,  // 死代码消除
    false  // 尾递归优化（部分完成）
);

性能测试

# 运行基准测试
cargo bench

# 快速测试
cargo bench -- --sample-size 10

# 对比优化效果
cargo bench -- --save-baseline before
# 进行优化...
cargo bench -- --baseline before

🔗 语言绑定

Go

package main

import (
    "fmt"
    "github.com/yourusername/aether-go"
)

func main() {
    engine := aether.New()
    defer engine.Close()
    
    result, err := engine.Eval(`
        Set X 10
        Set Y 20
        Return (X + Y)
    `)
    
    if err != nil {
        fmt.Println("Error:", err)
        return
    }
    fmt.Println("Result:", result) // 30
}

TypeScript/JavaScript

import { Aether } from '@yourusername/aether';

async function main() {
    const engine = new Aether();
    await engine.init();
    
    const result = engine.eval(`
        Set X 10
        Set Y 20
        Return (X + Y)
    `);
    
    console.log('Result:', result); // 30
}

main();

🛠️ 开发与测试

构建

# 克隆仓库
git clone https://github.com/yourusername/aether.git
cd aether

# 构建
cargo build --release

# 运行测试
cargo test

# 运行所有测试（包括集成测试）
cargo test --all

测试覆盖

  • ✅ 114 个测试 (100% 通过率)
  • ✅ 完整的解释器测试（Lexer, Parser, Evaluator）
  • ✅ 所有内置函数测试
  • ✅ 错误处理和命名约定测试
  • ✅ 性能基准测试

基准测试

# 运行所有基准测试
cargo bench

# 查看结果
open target/criterion/report/index.html

# 快速基准测试
./scripts/bench.sh quick

# 特定类别
./scripts/bench.sh arithmetic

基准覆盖：

  • 算术运算、变量操作、函数调用
  • 控制流、数据结构、解析性能
  • 不同程序规模（小/中/大型）

📖 内置函数速查

I/O 操作

PRINT, PRINTLN, INPUT

文件系统

READ_FILE, WRITE_FILE, APPEND_FILE
DELETE_FILE, FILE_EXISTS, CREATE_DIR
LIST_DIR, DELETE_DIR, FILE_SIZE

网络

HTTP_GET, HTTP_POST, HTTP_PUT, HTTP_DELETE

报表生成 (🆕)

// Excel
EXCEL_CREATE, EXCEL_READ_SHEET, EXCEL_WRITE_CELL
EXCEL_WRITE_ROW, EXCEL_WRITE_TABLE, EXCEL_SAVE
EXCEL_SET_CELL_FORMAT, EXCEL_ADD_CHART

// Word
WORD_CREATE, WORD_ADD_PARAGRAPH, WORD_ADD_HEADING
WORD_ADD_TABLE, WORD_SAVE, WORD_LOAD_TEMPLATE

// 数据格式化
FORMAT_NUMBER, FORMAT_CURRENCY, FORMAT_PERCENT
FORMAT_DATE

// 数据处理（规划中）
PIVOT_TABLE, GROUP_BY, AGGREGATE

类型转换

TO_STRING, TO_NUMBER, TYPE_OF
TO_ARRAY, TO_DICT, IS_NULL

数组操作

PUSH, POP, SHIFT, UNSHIFT
MAP, FILTER, REDUCE, SORT
FIND, INCLUDES, JOIN, SLICE

字符串操作

LEN, SPLIT, TRIM, UPPER, LOWER
REPLACE, SUBSTRING, STARTS_WITH, ENDS_WITH

数学函数

ABS, SQRT, POW, SIN, COS, TAN
MIN, MAX, SUM, AVG, MEDIAN
STDEV, VARIANCE, CORRELATION
LINEAR_REGRESSION, MATRIX_INVERSE

精确计算

TO_FRACTION, FRAC_ADD, FRAC_SUB
FRAC_MUL, FRAC_DIV, TO_FLOAT
ADD_WITH_PRECISION, SUB_WITH_PRECISION
MUL_WITH_PRECISION, DIV_WITH_PRECISION

薪资计算 (78 个函数)

// 基本工资
HOURLY_TO_DAILY, DAILY_TO_MONTHLY
MONTHLY_TO_ANNUAL, ANNUAL_TO_MONTHLY

// 加班费
CALC_WEEKDAY_OVERTIME  // 1.5x
CALC_WEEKEND_OVERTIME  // 2x
CALC_HOLIDAY_OVERTIME  // 3x

// 个税
CALC_PERSONAL_TAX      // 7级累进
CALC_BONUS_TAX         // 年终奖税

// 社保
CALC_SOCIAL_INSURANCE
CALC_HOUSING_FUND

🎯 开发状态

当前版本: v0.2.0

已完成：

  • ✅ 完整的解释器 (Lexer, Parser, Evaluator)
  • ✅ 190+ 内置函数
  • ✅ 增强的错误报告
  • ✅ 严格的命名约定
  • ✅ AST 缓存和性能优化
  • ✅ Go/TypeScript 绑定
  • ✅ 114 个测试通过

计划中：

  • 🔄 完整的尾递归优化
  • 🔄 JIT 编译器
  • 🔄 Python 绑定
  • 🔄 更多优化

📄 许可证

根据 Apache License 2.0 许可（LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0）。

🙏 致谢

Aether 的灵感来自：

📬 联系方式

由 Aether 贡献者用 ❤️ 制作

⬆ 返回顶部