feat: generate unified AST and editor contracts from ASDL
Verify databases and deploy Aster VM / verify-and-deploy (push) Successful in 7m55s
Verify databases and deploy Aster VM / verify-and-deploy (push) Successful in 7m55s
This commit is contained in:
@@ -12,6 +12,7 @@
|
||||
| Number、String、Dict、Cell、Function、异常数据 | [基本对象](runtime/builtins.md) | [objects/src](../crates/objects/src/README.md) |
|
||||
| 字符串、文件、流与 endor URI 如何进入 lexer | [Endor 阅读器](runtime/reader.md) | [reader.rs](../crates/frontend/src/reader.rs)、[source.rs](../crates/frontend/src/source.rs) |
|
||||
| 源码如何分词、PEG 规则、AST 和诊断 | [源码前端](runtime/frontend.md) | [lexer.peg](../crates/frontend/src/lexer.peg)、[grammar.peg](../crates/frontend/src/grammar.peg)、[frontend](../crates/frontend/README.md)、[CLI](../crates/cli/README.md) |
|
||||
| AST 根／声明／语句、ASDL 生成、遍历、位置与 JSON／编辑器接口 | [AST 模型](runtime/ast.md) | [Endor.asdl](../crates/frontend/Endor.asdl)、[AST 实现](../crates/frontend/src/ast/README.md)、[editor](../crates/frontend/editor/README.md) |
|
||||
| 操作码、代码验证、局部槽、函数定义与调用协议 | [字节码 VM](runtime/bytecode.md) | instruction.rs／code.rs 在 [objects/src](../crates/objects/src/README.md)，frame.rs／eval.rs 在 [core/src](../crates/core/src/README.md) |
|
||||
| 基础信息保存在哪里、旧库如何迁移 | [宿主文件信息](operations/host-information.md) | [host](../crates/host/README.md) |
|
||||
| UTF-8 在日本地区是否适用，其他编码怎样进入 VM | [文本编码](runtime/text-encoding.md) | [core](../crates/core/README.md)、[host](../crates/host/README.md) |
|
||||
|
||||
@@ -20,13 +20,13 @@ Server ─→ Core + Host
|
||||
未来数据库特殊类的宿主实现 ─→ Storage
|
||||
```
|
||||
|
||||
CLI、Server 依赖 Host 保存文件信息，不依赖 Storage；Core 只依赖本地 Objects，Objects 无依赖且不反向依赖 Core；二者均不依赖 Storage。CLI 的 parse 命令通过 Frontend 的 EndorReader 读取文件／stdin，再解析 AST；Frontend 的外部依赖只有 peg，读取适配使用标准库。平台 URI 的存储与授权由宿主 provider 提供，Core 不依赖 Frontend。HTTP、Tokio、SQLx、数据库、网络和浏览器能力不进入 core 或 objects；两包均无第三方依赖。包与文件定位见 [crates](../../crates/README.md)。
|
||||
CLI、Server 依赖 Host 保存文件信息，不依赖 Storage；Core 只依赖本地 Objects，Objects 无依赖且不反向依赖 Core；二者均不依赖 Storage。CLI 的 parse 命令通过 Frontend 的 EndorReader 读取文件／stdin，再解析 AST；Frontend 使用 peg 及工作区已有 serde／serde_json，读取适配使用标准库；Endor.asdl 在开发时生成 AST、遍历器与编辑器接口，普通构建不运行生成器。平台 URI 的存储与授权由宿主 provider 提供，Core 不依赖 Frontend。HTTP、Tokio、SQLx、数据库、网络和浏览器能力不进入 core 或 objects；两包均无第三方依赖。包与文件定位见 [crates](../../crates/README.md)。
|
||||
|
||||
| 组件 | 当前职责 | 全局契约 |
|
||||
| --- | --- | --- |
|
||||
| Core | Vm、执行帧、调用协议与取指求值循环；对象方法委托到 Objects | [字节码 VM](../runtime/bytecode.md) |
|
||||
| Objects | 核心对象、私有堆、ObjectStore、Number、代码对象、指令数据和静态验证；无求值器 | [对象模型](../runtime/objects.md) |
|
||||
| Frontend | Endor 阅读器、UTF-8 字符 PEG lexer、token PEG parser、基础函数／表达式 AST，不执行源码 | [源码前端](../runtime/frontend.md) |
|
||||
| Frontend | Endor 阅读器、UTF-8 字符 PEG lexer、token PEG parser、ASDL 生成的根／声明／语句／表达式 AST 与跨工具接口，不执行源码 | [源码前端](../runtime/frontend.md) |
|
||||
| Host | 基础信息的逐键 UTF-8 JSON 文件与旧库导入 | [宿主信息](../operations/host-information.md) |
|
||||
| Storage | 按显式配置建立 SQLite／PostgreSQL 连接池，不定义应用表 | [数据库特殊类](../runtime/database-objects.md) |
|
||||
| CLI | 对象引导演示、源码解析与文件信息命令 | [CLI](../../crates/cli/README.md) |
|
||||
|
||||
@@ -17,6 +17,7 @@
|
||||
| Number、String、Dict、Cell、函数环境和异常数据 | [builtins.md](../runtime/builtins.md) | objects/src、objects/tests 与 core/tests 文件表 |
|
||||
| lexer 前的输入适配、SourceUnit 与来源诊断 | [reader.md](../runtime/reader.md) | frontend 的 reader／source、CLI 与读取检查 |
|
||||
| Token、lexer.peg 词法／grammar.peg 语法规则、AST 与源码诊断 | [frontend.md](../runtime/frontend.md) | frontend 源码／测试／样例和 CLI |
|
||||
| AST 节点／根模式、ASDL 生成、Visitor、位置与 JSON／编辑器接口 | [ast.md](../runtime/ast.md) | Endor.asdl、生成器、生成产物与 AST／CLI 检查 |
|
||||
| 指令编码、栈效果、调用协议与执行限制 | [bytecode.md](../runtime/bytecode.md) | instruction／code／frame／eval 文件职责 |
|
||||
| 宿主基础信息、JSON 文件和旧库导入 | [host-information.md](../operations/host-information.md) | host、cli、server 与脚本 README |
|
||||
| 地区与文本编码边界 | [text-encoding.md](../runtime/text-encoding.md) | 配置主题与实际 I/O 入口 |
|
||||
@@ -48,7 +49,9 @@ Rust 实现依赖模块可见性、trait 和 rustfmt，不照搬 CPython C 符
|
||||
|
||||
Endor 是由平台解释执行的语言，字节码生成是内部准备步骤。资源版本属于平台元数据，具体 URI 与持久化协议尚未定稿，不提前写进业务语法；首版暂不要求持久化字节码缓存，详见 [执行与版本模型](../architecture/execution-and-versions.md)。
|
||||
|
||||
独立 Frontend 已提供阅读器、lexer/parser 和 AST；后续按实际需求接入名称／闭包分析和字节码编译、扩充迭代器等指令、宿主回调、错误传播和资源边界。语法可继续调整，AST 到字节码和云服务机制尚未实现，不写成既有功能。
|
||||
AST 节点以 frontend/Endor.asdl 为唯一来源，Rust 类型／遍历器和 TypeScript／JSON Schema 为提交到 Git 的生成产物，不直接编辑；通过 scripts/generate_ast.py --write 更新，--check 做静态同步检查。生成器行为测试仅在指定远端执行。
|
||||
|
||||
独立 Frontend 已提供阅读器、lexer/parser 和 ASDL 生成的 AST／跨工具接口；后续按实际需求接入名称／闭包分析和字节码编译、扩充迭代器等指令、宿主回调、错误传播和资源边界。语法可继续调整，AST 到字节码和云服务机制尚未实现，不写成既有功能。
|
||||
|
||||
## 导出与迁移
|
||||
|
||||
|
||||
@@ -16,6 +16,7 @@ Objects 零依赖，统一拥有核心对象、Number、代码对象／指令数
|
||||
- Function、NativeFunction、Dict、Cell、异常数据、UTF-8 String 和无损表示优先的 Number。
|
||||
- 小型 wordcode、共享代码对象、操作数／控制流／栈校验、显式执行帧及 execute／call；MakeFunction 可在执行中创建带默认参数与共享闭包 Cell 的函数。对象返回值持有根，用后 release_value；借用读取不自动 retain。
|
||||
- EndorReader 在 lexer 前提供字符串／流／文件／宿主 URI provider 输入，产出不可变 SourceUnit，保存来源与不透明修订标签；带来源的词法／语法错误保留行列，CLI parse 支持文件和 stdin。没有平台 URI 后端或版本锁实现，见 [阅读器](../runtime/reader.md)。
|
||||
- Endor.asdl 是 AST 唯一定义源，生成 Rust 节点／Spanned／Visitor、TypeScript 类型／遍历器和 JSON Schema。AstRoot 支持 Module／Expression／Interactive，Program／Block 使用声明／语句列表；AstDocument 提供带 schema 的 JSON 及范围校验，CLI 支持 --mode／--json，见 [AST 模型](../runtime/ast.md)。生成产物需通过 scripts/generate_ast.py 更新，不能手改。
|
||||
- Frontend 使用 peg 0.8.6，词法规则在 lexer.peg（字符 → Token），语法规则在 grammar.peg（Token → AST）；lexer.rs 保留逐 Token 游标与诊断位置换算，提供完整输入解析、基础函数／表达式 AST、Unicode 字节范围与行列诊断；CLI parse 可读 UTF-8 文件／stdin 输出 AST，不执行源码。当前语法以未完成设计稿为起点，可以继续调整，见 [源码前端](../runtime/frontend.md)。
|
||||
- Host 文件信息独立于数据库：host.version、deployment.release 与 metadata put/get 使用 UTF-8 JSON。旧 PostgreSQL 基础信息只读导入缺失文件，不删除原库，见 [文件信息](../operations/host-information.md)。
|
||||
- Storage 只提供显式 DatabaseConfig／DatabaseConnection；没有默认数据库、自动应用建表或基础信息 KV。特殊类的名称／接口尚未定义，没有将连接接入 VM。
|
||||
@@ -31,7 +32,7 @@ AST 到字节码生成、平台资源存储／修订与依赖锁、名称／闭
|
||||
|
||||
## 工作约定
|
||||
|
||||
本地不构建、不运行测试／冒烟，不下载依赖；只允许静态阅读、格式化、语法／链接检查。运行验证交给 ces-control 的 SQLite、真实 PostgreSQL 与宿主流程。按用户要求不主动跟踪 CI／部署，结果未查询就明确写未核实。
|
||||
本地不构建、不运行测试／冒烟，不下载依赖；允许静态阅读、格式化、ASDL 源码生成／同步检查、语法／链接检查。运行验证交给 ces-control 的 SQLite、真实 PostgreSQL 与宿主流程。按用户要求不主动跟踪 CI／部署，结果未查询就明确写未核实。
|
||||
|
||||
数据库、卷和已有资料保留；不得改其他项目或共享 Runner。研究材料与 AGENTS.md 不提交。Git 身份按本地工作约定使用专用 codex-bot，不能借用仓库所有者凭据。
|
||||
|
||||
@@ -43,4 +44,4 @@ Endor 由平台解释执行；AST 到字节码是解释器内部准备步骤，
|
||||
|
||||
## 下一步
|
||||
|
||||
前端已完成到 AST 的首版实现；下一步连接解释器内部的字节码生成：AST → 名称／局部槽与闭包分析 → 字节码 → 现有 VM，不改成 AST 直接解释。可以先连接字符串、名称、let、位置参数函数和调用，再补算术指令与数值语义。参数与返回类型目前只保存为语法节点，不引入 Python type／元类或借此实现整个语言类型系统。语法不必等外部设计稿全部定稿，按用户要求先实现可用子集、以后再调整；当前尚无源码执行命令。
|
||||
前端已完成 ASDL 单一来源、统一根／声明／语句层次、遍历及 JSON／编辑器接口；语法仍为可用子集，Interactive 仅解析单次提交，不是 REPL。下一步连接解释器内部的字节码生成：AST → 名称／局部槽与闭包分析 → 字节码 → 现有 VM，不改成 AST 直接解释。可以先连接字符串、名称、let、位置参数函数和调用，再补算术指令与数值语义。参数与返回类型目前只保存为语法节点，不引入 Python type／元类或借此实现整个语言类型系统。语法不必等外部设计稿全部定稿，按用户要求先实现可用子集、以后再调整；当前尚无源码执行命令。
|
||||
|
||||
@@ -14,11 +14,12 @@ cargo run -p cli -- bootstrap
|
||||
cargo run -p cli -- help
|
||||
cargo run -p cli -- parse crates/frontend/examples/basic.endor
|
||||
cargo run -p cli -- parse - < crates/frontend/examples/basic.endor
|
||||
cargo run -p cli -- parse --json crates/frontend/examples/basic.endor
|
||||
```
|
||||
|
||||
bootstrap 创建两个 Record，输出 runtime=EndorObject、type_system=disabled、objects_distinct=true 和 heap_objects=2，显式释放后输出 released heap_objects=0。默认无参数执行同一示例。
|
||||
|
||||
parse 通过 EndorReader 严格读取 UTF-8 源码文件；`parse -` 从 stdin 读到 EOF，输入来源为 `<stdin>`，没有 REPL 提示符或会话求值。成功时输出 Rust Debug 格式的 AST；失败时输出来源、行、列并返回非零退出码；阅读错误在进入 lexer 前返回。输入适配与 URI provider 见 [阅读器](../runtime/reader.md)。该命令只解析语法，不执行源码；语法与当前边界见 [源码前端](../runtime/frontend.md)。
|
||||
parse 通过 EndorReader 严格读取 UTF-8 源码文件；`parse -` 从 stdin 读到 EOF，输入来源为 `<stdin>`，没有 REPL 提示符或会话求值。默认解析 module 模式，成功时输出 Rust Debug 格式的 AstRoot；--mode 支持 expression／interactive，--json 输出带 schema 的 JSON，见 [AST 模型](../runtime/ast.md)；失败时输出来源、行、列并返回非零退出码；阅读错误在进入 lexer 前返回。输入适配与 URI provider 见 [阅读器](../runtime/reader.md)。该命令只解析语法，不执行源码；语法与当前边界见 [源码前端](../runtime/frontend.md)。
|
||||
|
||||
CLI 不读取数据库环境，不创建基础信息数据库表。metadata put/get 通过 host 包写 UTF-8 JSON 文件，metadata import 仅导入缺失记录；示例、配置和协议见 [宿主信息](host-information.md)。输入与退出码见 [cli/src](../../crates/cli/src/README.md)。
|
||||
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
## 执行约定
|
||||
|
||||
本地不运行 Cargo 构建、测试、Clippy、冒烟、Docker 或依赖下载；允许阅读、格式化和静态文件／文档检查。指定运行验证环境为 ces-control。按用户要求不主动追踪 CI／部署结果，有问题由用户反馈后再查。
|
||||
本地不运行 Cargo 构建、测试、Clippy、冒烟、Docker 或依赖下载；允许阅读、格式化、ASDL 源码生成／产物同步检查和静态文件／文档检查。指定运行验证环境为 ces-control。按用户要求不主动追踪 CI／部署结果，有问题由用户反馈后再查。
|
||||
|
||||
## 检查入口
|
||||
|
||||
@@ -16,7 +16,7 @@ cargo test -p storage --test postgres --locked -- --ignored
|
||||
python3 scripts/smoke.py
|
||||
```
|
||||
|
||||
check.sh 执行 cargo fmt --all --check、独立词法／语法文件的 rustfmt --edition 2024 --check crates/frontend/src/lexer.peg crates/frontend/src/grammar.peg、cargo test --workspace --locked 和 cargo clippy --workspace --all-targets --locked -- -D warnings。workspace 测试也包含 rustdoc 示例；显式忽略的 PostgreSQL 测试需要单独执行。
|
||||
check.sh 先运行 generate_ast.py --check 验证 ASDL 产物同步，以及仅远端执行的 test_generate_ast.py 生成器回归检查，再执行 cargo fmt --all --check、独立词法／语法文件的 rustfmt --edition 2024 --check crates/frontend/src/lexer.peg crates/frontend/src/grammar.peg、cargo test --workspace --locked 和 cargo clippy --workspace --all-targets --locked -- -D warnings。workspace 测试也包含 rustdoc 示例；显式忽略的 PostgreSQL 测试需要单独执行。
|
||||
|
||||
ci-ces-control.sh 负责准备全新专用临时 PostgreSQL 和测试 URL；成功路径使用真实数据库，不用模拟 socket 代替。测试库与生产数据不共享挂载。没有 ASTER_TEST_POSTGRES_URL 时，显式执行 PostgreSQL 测试会失败，不标记为通过。
|
||||
|
||||
@@ -30,6 +30,7 @@ ci-ces-control.sh 负责准备全新专用临时 PostgreSQL 和测试 URL；成
|
||||
| 基本对象 | Number 表示、字符串、Dict／Cell 引用与更新、函数环境、异常数据 | 同目录 builtins.rs |
|
||||
| 字节码 | 编解码、非法指令／控制流、跳转、调用、闭包、字节码创建函数／默认值／环境捕获、函数创建及后续失败清理、结果存活与限额 | 同目录 execution.rs |
|
||||
| Endor 阅读器 | 字符串、分块 UTF-8 流、文件、读取失败、URI provider、修订标签与来源诊断 | [frontend/tests](../../crates/frontend/tests/README.md) 的 reader.rs |
|
||||
| AST 与接口生成 | 三类根、声明／语句层次、Visitor 及失败退出、Unicode 位置、JSON 往返、schema／范围错误和跨语言产物标识 | frontend/tests/ast.rs 与 scripts/test_generate_ast.py，见 [AST 模型](../runtime/ast.md) |
|
||||
| 源码前端 | 字符 PEG 词法边界、逐 Token 原文位置与首个错误诊断、Unicode 范围、数字原文、字符串与错误、优先级／结合性、函数／绑定、完整输入与错误位置、源码样例 | [frontend/tests](../../crates/frontend/tests/README.md) |
|
||||
| CLI 解析 | AST 输出、未执行源码、文件／stdin 来源和行列错误、EOF 读取与非法 UTF-8 退出 | [cli/tests](../../crates/cli/tests/README.md) |
|
||||
| 公开示例 | 对象操作、手写指令执行与释放 | objects 与 core 的 src/lib.rs rustdoc，见 [objects/src](../../crates/objects/src/README.md)、[core/src](../../crates/core/src/README.md) |
|
||||
|
||||
@@ -8,6 +8,7 @@
|
||||
| [基本对象与 Number](builtins.md) | 函数、原生函数、字典、Cell、异常数据、字符串与无损数字 |
|
||||
| [Endor 阅读器](reader.md) | SourceUnit、来源／修订标签、字符串／流／文件和宿主 URI provider |
|
||||
| [源码前端](frontend.md) | 字符 PEG lexer、token PEG parser、AST、基础函数／表达式语法与诊断 |
|
||||
| [AST 模型与 ASDL](ast.md) | 统一根、声明／语句／表达式、生成器、Visitor、位置和 JSON／编辑器接口 |
|
||||
| [字节码 VM](bytecode.md) | 指令编码、代码校验、局部槽、执行帧、函数创建、调用／返回与边界 |
|
||||
| [文本编码](text-encoding.md) | UTF-8、日文、外部 Shift_JIS／CP932 与宿主解码边界 |
|
||||
| [数据库特殊类](database-objects.md) | 显式连接、调用方数据模型、未来类接入与资源生命周期 |
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
# AST 模型、ASDL 与跨工具接口
|
||||
|
||||
Endor 的 AST 节点统一由 [Endor.asdl](../../crates/frontend/Endor.asdl) 定义。它描述节点及字段；lexer.peg 描述字符识别，grammar.peg 描述语法与节点构造。ASDL 与语法各自维护一个职责，不引入 CST 或 Python type／元类；AST 位于 frontend，运行时对象位于 objects。
|
||||
|
||||
## 生成关系
|
||||
|
||||
```text
|
||||
Endor.asdl → scripts/generate_ast.py
|
||||
├─ src/ast/generated.rs：Rust 节点、Serde 与 Spanned
|
||||
├─ src/ast/visitor.rs：Rust Visitor／walk_*
|
||||
├─ editor/ast.ts：TypeScript 类型、Visitor／walk*
|
||||
└─ editor/ast.schema.json：JSON Schema 2020-12
|
||||
```
|
||||
|
||||
路径均相对 crates/frontend。生成器使用 Python 标准库和 rustfmt，无额外 Python 包、build.rs 或构建时网络访问。产物提交到 Git，普通 Cargo 构建直接使用它们。开发修改 schema 后，在仓库根执行：
|
||||
|
||||
```sh
|
||||
python3 scripts/generate_ast.py --write
|
||||
python3 scripts/generate_ast.py --check
|
||||
```
|
||||
|
||||
这两条命令是源码生成／静态检查，可在本地使用；行为测试仍仅在指定远端执行。CI 检查生成同步，并运行生成器回归检查与工作区测试。
|
||||
|
||||
ASDL 支持 module、产品类型 `(Type field, ...)`、构造器联合 `A(...) | B(...)`、`*` 序列、`?` 可选字段、`--` 行注释。内建 string 是拥有文本的 String，span 对应共享的 UTF-8 Span，schema_id 是交换契约标识。生成器检查重复名称、字段、未知类型和不支持的语法；这是项目使用的 ASDL 子集，不声称兼容 CPython ASDL 的全部扩展。
|
||||
|
||||
Rust 用 struct／enum、Vec／Option 表达结构；生成器在按值依赖图的回边放置 Box，Vec 已经断开按值递归。增加节点后，Rust 类型、两种语言的遍历接口和 JSON Schema 由同一次生成更新。
|
||||
|
||||
## 根、声明、语句、表达式
|
||||
|
||||
| 层级 | 当前数据模型 |
|
||||
| --- | --- |
|
||||
| AstRoot | Module(Program)、Expression(Expr)、Interactive(InteractiveInput) |
|
||||
| Program | declarations: Vec<Decl> 与 span；当前声明种类为 Function |
|
||||
| Decl／DeclKind | 声明的位置及其具体种类；Function 保存参数、返回类型名称和 Block |
|
||||
| Block | statements: Vec<Stmt> 与 span，不再用固定的 bindings／result 字段表示 |
|
||||
| Stmt／StmtKind | Binding、Return、Expression、Declaration；每条语句有自身范围 |
|
||||
| ReturnStatement | 可选表达式与范围；当前源码中的 return 仍要求表达式 |
|
||||
| Expr／ExprKind | 名称、数字原文、字符串、符号、一元／二元运算、成员和调用 |
|
||||
|
||||
参数与返回类型仍为 Name，只保留语法，不实施类型或名称检查。Program::functions() 提供函数迭代便捷接口。旧的 Program.functions、Block.bindings／result／return_span 字段已移除；源码构造和使用方改为声明／语句列表。ExprKind 的既有表达式结构保留。
|
||||
|
||||
AST 数据模型允许一般语句列表，不代表 parser 接受了所有组合。模块仍要求一个或多个函数；函数体仍接受 let* 后跟一个带值 return。Interactive 模式接受一次函数声明、let 绑定或表达式，必须消费完整输入；不创建交互会话，不处理续行提示，不执行语言代码。多条交互提交由宿主分别解析。条件、循环、导入、类等尚未实现，也不加入 FunctionType 这种 Python 专用入口。
|
||||
|
||||
## 解析与位置
|
||||
|
||||
parse_ast(&str, ParseMode) 和 parse_source_ast(&SourceUnit, ParseMode) 返回 AstRoot；ParseMode 包含 Module、Expression、Interactive。原有 parse／parse_expression／parse_source／parse_source_expression 保留对应的具体返回类型。带来源入口的诊断仍记录名称／URI／修订和行列。
|
||||
|
||||
Spanned 为有位置的节点提供 span()、source_text(&str)、location(&str)。Span::slice／location 拒绝反向、越界或截断 UTF-8 字符的范围；行列是一基 Unicode 标量列，CRLF 算一次换行。Span 不携带源码身份，调用方需关联原始 SourceUnit；AST JSON 本身不含源码、文件路径、URI 或资源修订。
|
||||
|
||||
## 遍历与分析
|
||||
|
||||
生成的 Rust Visitor 有每个节点／种类的 visit_* 方法、默认 walk_* 函数，以及 enter_node／leave_node 钩子。Error 为关联类型，子节点失败时默认遍历返回错误，并配对调用已进入节点的离开钩子。可在 visit_function、visit_binding、visit_expr 等位置实现名称分析或字节码生成。
|
||||
|
||||
覆盖 visit_* 后，调用 walk_* 可继续访问子节点；覆盖方法自身的钩子管理由实现者决定，直接调用 walk_* 不会重复调用当前节点的 visit_*。这些接口只提供遍历，尚未实现名称绑定、闭包捕获分析或字节码生成。TypeScript Visitor 对应编辑器使用，回调返回 false 可跳过子树。
|
||||
|
||||
## JSON 交换
|
||||
|
||||
frontend 使用工作区已有的 serde／serde_json。AstDocument 是带 schema 和 root 的交换外壳，提供 new、to_json、from_json、validate、validate_source。构造／读取／写出时检查 schema 标识、位置顺序、父子范围包含关系及 JS 安全整数范围；validate_source 额外检查给定原文的长度和 UTF-8 字符边界，不比较原文与节点的程序含义。
|
||||
|
||||
构造器联合按 `{"kind":"Variant","data":...}` 编码，无字段的运算符联合使用字符串。产品类型使用字段对象；未知字段和未知构造器拒绝。可选字段可省略或为 null，标准写出为 null。数字保留源码拼写字符串，不经浮点转换。
|
||||
|
||||
AST_SCHEMA_ID 从 Endor.asdl 的 UTF-8 文本计算 SHA-256，包含注释与空白；生成器读取时使用 Python 的统一换行规则。它标识这套 AST 接口定义，区别于用户资源修订、编译器或 VM 版本。修改 schema 后旧标识被拒绝，尚无历史格式迁移。改变生成器的交换编码或内建位置类型契约时，也必须更新 ASDL 顶部的 Wire contract 版本说明，使标识随之变化。直接调用 Serde 是结构编解码，跨边界应使用 AstDocument 方法执行完整校验；JSON Schema 不表达所有位置约束。
|
||||
|
||||
CLI 可提供具体的交换输出：
|
||||
|
||||
```sh
|
||||
cli parse --json source.endor
|
||||
cli parse --mode expression --json -
|
||||
cli parse --mode interactive --json -
|
||||
```
|
||||
|
||||
文件／stdin 阅读保持原有 UTF-8 和错误来源规则，stdin 到 EOF 后才解析。普通 cli parse 输出 AstRoot 的 Debug 文本，稳定交换使用带 schema 的 JSON；所有入口均不执行源码。命令在指定远端运行。
|
||||
|
||||
检查源码见 [frontend/tests](../../crates/frontend/tests/README.md) 和 [生成器检查](../../scripts/test_generate_ast.py)，边界见 [验证](../operations/validation.md)。返回 [运行时索引](README.md)。
|
||||
@@ -13,7 +13,7 @@ frontend 包提供 [Endor 阅读器](reader.md)、rust-peg 生成的字符 lexer
|
||||
| [lexer.peg](../../crates/frontend/src/lexer.peg) | str 字符输入，识别名称、数字、字符串／转义、标点、空白／注释及词法错误，生成 Token | [lexer.rs](../../crates/frontend/src/lexer.rs) 保留 lex／lex_source、游标、位置换算和字符串解码 |
|
||||
| [grammar.peg](../../crates/frontend/src/grammar.peg) | [Token] 输入，匹配函数／绑定／return、表达式优先级并构造 AST | [parser.rs](../../crates/frontend/src/parser.rs) 保留解析入口、诊断转换和 AST 辅助函数 |
|
||||
|
||||
lexer.rs 与 parser.rs 分别通过 include! 在编译期引入对应规则；两份 .peg 文件保留 peg::parser! 外层声明，直接参与编译，不新增 build.rs、生成脚本或依赖。远端检查脚本单独对两份规则执行 rustfmt。
|
||||
lexer.rs 与 parser.rs 分别通过 include! 在编译期引入对应规则；两份 .peg 文件保留 peg::parser! 外层声明，直接参与编译，自身不需要 build.rs 或生成脚本。AST 类型另由 Endor.asdl 离线生成，交换接口使用 serde／serde_json，见 [AST 模型](ast.md)。远端检查脚本单独对两份规则执行 rustfmt。
|
||||
|
||||
字符 PEG 的内部 next 规则使用 #[no_eof] 每次识别一个前缀，跳过空白／注释并返回一个 Token 或输入结束。Lexer 保存 source／offset，循环调用该规则，直到全输入结束或首个错误；公开 lex 仍扫描整份输入，不是增量／可恢复输入接口。规则中的 position! 相对本次输入切片，lexer.rs 将 Token 和诊断位置统一换算为原始源码 UTF-8 字节范围。
|
||||
|
||||
@@ -29,8 +29,10 @@ lexer.rs 与 parser.rs 分别通过 include! 在编译期引入对应规则；
|
||||
| lex(&str) | 产生 Vec<Token>；每个 token 只有种类和原始源码的字节范围，不复制文本 |
|
||||
| parse(&str) | 解析一个或多个完整函数定义，返回 Program；空输入和未消费的尾部内容报错 |
|
||||
| parse_expression(&str) | 解析一个完整表达式，不能忽略尾部 token |
|
||||
| parse_ast(&str, ParseMode) | 返回 Module／Expression／Interactive 三类 AstRoot，模式独立于输入来源 |
|
||||
| parse_source_ast(&SourceUnit, ParseMode) | 同一统一入口，失败保留来源、修订和行列 |
|
||||
|
||||
AST 的名称、数字原文和解码后的字符串均由 AST 自己持有，可以在释放输入后继续使用。Token／AST 的 Span 均为原始 UTF-8 源码的半开字节区间 start..end；节点跨度包含首尾 token 之间的空白及注释，不包含外侧 trivia。分组表达式的范围包括括号，Program 范围从第一个函数到最后一个函数。
|
||||
AST 结构及 Visitor、Spanned 和跨工具 JSON 契约见 [AST 模型](ast.md)。Program 使用 declarations，Block 使用 statements；ExprKind 保留既有表达式形状。AST 的名称、数字原文和解码后的字符串均由 AST 自己持有，可以在释放输入后继续使用。Token／AST 的 Span 均为原始 UTF-8 源码的半开字节区间 start..end；节点跨度包含首尾 token 之间的空白及注释，不包含外侧 trivia。分组表达式的范围包括括号，Program 范围从第一个函数到最后一个函数。
|
||||
|
||||
词法动作只返回 Token／诊断，语法动作只构造 AST；两者均不做 I/O、VM 分配或其他外部写入。PEG 回溯不会执行语言函数或产生宿主业务副作用。
|
||||
|
||||
@@ -54,7 +56,7 @@ block = "{" binding* "return" expression "}"
|
||||
binding = "let" name "=" expression
|
||||
```
|
||||
|
||||
parameters 和调用参数列表使用逗号分隔，不接受尾随逗号。函数体要求一个末尾 return；不支持独立表达式语句、重赋值、嵌套函数声明或默认参数源码写法。参数和返回类型目前只是名称节点；并不据此创建语言 type 对象或检查类型。
|
||||
parameters 和调用参数列表使用逗号分隔，不接受尾随逗号。函数体要求一个末尾 return；函数体尚不支持独立表达式语句、重赋值、嵌套函数声明或默认参数源码写法。新增 Interactive 解析模式接受一次函数声明、let 绑定或表达式，完整消费输入，但不创建 REPL 或执行代码；AST 可表示的语句组合比当前源码子集更广。参数和返回类型目前只是名称节点；并不据此创建语言 type 对象或检查类型。
|
||||
|
||||
表达式包括名称、数字、字符串、`.name` 符号、括号分组、成员访问与位置参数调用、一元负号以及四则运算。优先级从高到低为：
|
||||
|
||||
@@ -71,6 +73,6 @@ use、namespace、class、agent、完整类型语法、条件／循环、比较
|
||||
|
||||
词法和语法错误分别标记为 Lexical／Syntax。语法错误将 PEG 的 token 下标转换成原始源码 Span，保留期望项目列表；EOF 错误使用 source.len() 处的空区间。Diagnostic::location 返回一基行列，列按 Unicode 标量计数，CRLF 只算一次换行，不按字节列或字形簇计数。
|
||||
|
||||
`cli parse <file>` 与 `cli parse -` 成功时输出 Rust Debug 格式的 AST，失败时在 stderr 输出来源／行／列和诊断并返回非零退出码；`-` 表示从 stdin 读到 EOF，不是 REPL。阅读与来源包装规则见 [阅读器](reader.md)。AST Debug 文本不是稳定的序列化协议。命令不执行源码、不初始化 VM、不连接数据库；具体运行与本地禁测约定见 [运行](../operations/README.md) 和 [验证](../operations/validation.md)。
|
||||
`cli parse <file>` 与 `cli parse -` 成功时输出 Rust Debug 格式的 AST，失败时在 stderr 输出来源／行／列和诊断并返回非零退出码；`-` 表示从 stdin 读到 EOF，不是 REPL。阅读与来源包装规则见 [阅读器](reader.md)。可用 --mode 选择 module／expression／interactive，用 --json 输出带 schema 标识的 AstDocument；普通输出为 AstRoot Debug 文本，稳定交换格式见 [AST 模型](ast.md)。命令不执行源码、不初始化 VM、不连接数据库；具体运行与本地禁测约定见 [运行](../operations/README.md) 和 [验证](../operations/validation.md)。
|
||||
|
||||
后续需要将 AST 经名称／闭包分析转换为现有字节码，再交给 VM 解释执行。这是解释器内部的编译／执行准备步骤，不要求使用者先构建程序，见 [执行与版本模型](../architecture/execution-and-versions.md)。这条连接尚未实现；解析成功不表示表达式已有运行语义。VM 虽已支持 MakeFunction，但从源码创建函数仍需要字节码生成接入。解析器也不是不可信代码沙箱，当前没有通用输入大小或解析递归深度限额。
|
||||
|
||||
Reference in New Issue
Block a user