From bb0cf8c558b470a74cd7255fc262d9350c5f412e Mon Sep 17 00:00:00 2001 From: 0264408 Date: Fri, 26 Jun 2026 09:27:16 +0800 Subject: [PATCH] =?UTF-8?q?doc:=20=E6=9B=B4=E6=96=B0README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 2a83313..22ab06e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Aster -Aster 是一门使用 Rust 编写的动态类型脚本语言解释器，基于树遍历（tree-walker）实现。无外部依赖，纯标准库。 +Aster 是一门使用 Rust 编写的动态类型脚本语言解释器，支持两种执行模式：**树遍历（tree-walker）** 和 **字节码 VM**。无外部依赖，纯标准库。 ## 快速开始 @@ -11,9 +11,12 @@ cargo build # 启动 REPL（交互式） cargo run -# 执行脚本文件 +# 执行脚本文件（树遍历模式） cargo run -- examples/script.ast +# 执行脚本文件（字节码 VM 模式，性能更优） +cargo run -- --vm examples/script.ast + # 运行测试 cargo test ``` @@ -84,6 +87,21 @@ while (true) { if (condition) { break; } if (skip) { continue; } } + +// for-in 遍历（数组 / 字符串） +for (let item in [1, 2, 3]) { + print(item); +} +``` + +### 模块系统 + +```js +// 加载并执行外部脚本，返回模块导出的对象 +let math = require("math.ast"); +print(math.add(3, 4)); + +// 第二次 require 同一文件会返回缓存的对象（支持循环引用） ``` ### 函数与闭包 @@ -144,23 +162,26 @@ let t = os.clock(); // 模块化调用 ## 架构 ``` -源码文本 → Lexer → Tokens → Parser → AST → Interpreter → 输出 +源码文本 → Lexer → Tokens → Parser → AST ──→ Interpreter（树遍历）→ 输出 + └─→ Compiler → Bytecode → VM → 输出 ``` | 模块 | 职责 | |------|------| -| `lexer/` | 词法分析。`Lexer::tokenize()` 将源码转为 `(Vec, Vec)`，Token 记录行列号用于错误报告，支持 `//` 单行注释 | +| `lexer/` | 词法分析。`Lexer::tokenize()` 将源码转为 `(Vec, Vec)`，Token 记录行列号用于错误报告，支持 `//` 单行注释和 `/* */` 块注释 | | `parser/` | 递归下降 + Pratt 解析器。`Parser::parse()` 返回 `(Vec, Vec)`，遇到语法错误通过 `synchronize()` 跳过至下一条语句边界继续解析 | | `ast/` | AST 节点定义。`Expr`（表达式）涵盖字面量、变量、赋值、属性/索引访问、一元/二元/逻辑运算、函数调用、lambda 和对象/数组字面量。`Stmt`（语句）涵盖 let、表达式语句、块、if/while/for、函数、return/break/continue | | `interpreter/` | 树遍历求值器。`Env` 是基于 `Rc>` 的链式作用域。`Signal` 枚举通过调用栈传播 `Return`/`Break`/`Continue`。`builtins/` 按 `io` 和 `os` 模块组织原生函数，同时注册为全局函数以方便使用 | +| `vm/` | 字节码 VM。`Compiler` 将 AST 编译为基于栈的字节码，`Vm` 执行字节码指令。支持闭包 upvalue 捕获、3 层嵌套闭包、`require()` 模块加载。通过 `--vm` 标志启用 | | `error/` | 三种错误：`LexError`（行列号）、`ParseError`（Token）、`RuntimeError`（可选 Token） | ### 关键设计决策 - **零外部依赖** — 全部基于 Rust 标准库构建 +- **双执行模式** — 树遍历模式（默认，适合交互和调试）和字节码 VM 模式（`--vm`，约 40% 性能提升），共享同一 AST 和运行时语义 - **错误容忍解析** — 词法分析器和解析器均将错误收集到 `Vec` 中，单次运行可报告多个诊断信息，而非在第一个错误处就中止 - **`Rc>` 共享所有权** — 用于 `Env` 链、`Value::Object`、`Value::Array` 和 `Value::Function`，提供动态可变语义 -- **词法作用域闭包** — `Function` 在定义时捕获 `Env`，lambda 表达式同理 +- **词法作用域闭包** — `Function` 在定义时捕获 `Env`，lambda 表达式同理；VM 通过 upvalue 机制支持最多 3 层传递式捕获 ## 许可证