From 5a0bf60698d30b6a262d6f98c9e16ad449998fc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E8=88=AA=E5=AE=87?= <3364451258@qq.com> Date: Fri, 5 Jun 2026 18:42:24 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20CHANGELOG=20v0.4/v0.5=20+=20README/CLAU?= =?UTF-8?q?DE=20=E7=89=88=E6=9C=AC=E5=88=B7=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CHANGELOG: 新增 v0.4.0 (struct+RAII) 和 v0.5.0 (alias+enum+array+impl+match) - README: 版本0.5.0, 测试145, 完整功能列表+运算符表 - CLAUDE: v0.5 已知限制更新 --- CHANGELOG.md | 43 +- CLAUDE.md | 17 +- README.md | 53 ++- ...tecture-analysis-report-2026-06-05-1509.md | 417 ++++++++++++++++++ ...tecture-analysis-report-2026-06-05-1708.md | 185 ++++++++ 5 files changed, 675 insertions(+), 40 deletions(-) create mode 100644 docs/analysis/architecture-analysis-report-2026-06-05-1509.md create mode 100644 docs/analysis/architecture-analysis-report-2026-06-05-1708.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 2a74836..3c53d8a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,38 +1,51 @@ # Changelog +## 0.5.0 (2026-06-05) + +### Added +- 类型别名: `type Meters = i64;`，支持 struct 别名 (sema 层解析，零 codegen) +- 枚举: `enum Color { Red, Green, Blue }`，`Color::Green` 变体访问 +- 数组: `[T; N]` 类型 + `arr[i]` 索引 + `arr[i] = val` 元素赋值 +- struct 方法: `impl Point { fn get_x(self: Point) -> i64 { ... } }`，`p.get_x()` 调用 +- match 表达式: `match expr { pat => { ... } _ => { ... } }` (parser 去糖为 if-else) +- parse_type_expr() 抽取：统一类型标注解析 +- 4 个新集成测试: 15_type_alias ~ 23_match_wildcard + +### Changed +- AST_PROGRAM 扩展: 支持 aliases/enums/impls 多种顶层声明 +- TypeInfo 扩展: element_type/array_size 支持数组 +- 测试: 145 单元 (41+15+65+24) + 23 集成 + +## 0.4.0 (2026-06-05) + +### Added +- 结构体: `struct Point { x: i64, y: i64 }`，`Point { x: 10, y: 20 }` 初始化 +- 字段访问: `p.x`，`r.tl.x` 链式访问 +- struct 作为函数参数/返回值 +- RAII 自动内存管理: str 拼接自动 free，作用域退出时释放 +- SourceLoc 抽象: 统一 line/col 参数 +- 集成测试: 12_struct ~ 14_struct_fn + ## 0.3.0 (2026-06-05) ### Added - `for` 循环 + range: `for i in start..end { ... }` (parser 去糖为 let mut + while + assign) - `..` range 运算符 (TOK_DOT_DOT) - 浮点数 lexer 修复：`..` 不与 `.` 冲突 -- sema 测试补全：let mut assign, immutable assign error, str type, str concat (9→21 tests) -- codegen 测试补全：while 循环 LLVMVerifyModule (7→9 tests) +- sema/codegen 测试补全 - 集成测试：`10_for_range.l`、`11_for_step2.l` -### Known Issues -- LLVM 22 C API 不支持 mem2reg pass（需用 opt 工具优化 alloca） -- str+str 运行时拼接使用 malloc（编译后程序存在泄漏，非编译器本身） - ## 0.2.0 (2026-06-05) ### Added - `let mut` 可变变量 + 赋值语句 (`x = expr;`) -- 可变性检查：对不可变变量赋值报编译错误 - 字符串类型 `str` + 双引号字面量 (`"Hello"`) -- 字符串拼接 `str + str` (malloc + strlen + memcpy 运行时实现) -- `print_str` 内置函数 (委托 printf) +- 字符串拼接 `str + str` + `print_str` 内置函数 - 复合赋值运算符：`+=` `-=` `*=` `/=` -- 集成测试：`06_mut_while.l` (while 循环修改变量)、`07_hello_str.l` (字符串输出)、`08_str_concat.l` (字符串拼接) ### Changed - codegen malloc → arena 统一分配 - LLVM 目标初始化解耦为 `target.h/c` 独立模块 -- 新增 `.codegraphignore` - -### Fixed -- codegen.c 内存管理不一致 (malloc 混用 arena) -- str+str 运行时拼接返回左操作数的 bug ## 0.1.0 (2026-06-05) diff --git a/CLAUDE.md b/CLAUDE.md index dfcb439..deb5368 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,7 +2,7 @@ ## 项目概述 -L Language v0.1 — 用 C17 实现的静态类型编译型编程语言，Rust 风格语法，LLVM 22.x 后端。经典 5 阶段流水线：词法 → 语法 → 语义 → IR → 可执行文件。 +L Language v0.5 — 用 C17 实现的静态类型编译型编程语言，Rust 风格语法，LLVM 22.x 后端。经典 5 阶段流水线：词法 → 语法 → 语义 → IR → 可执行文件。145 单元测试 + 23 集成程序。 ## 构建命令 @@ -166,14 +166,15 @@ done - **Windows**：仅支持 Windows 11 + MinGW-w64 - **错误消息**：中文，格式 `文件名:行号:列号: 描述` -## 已知限制 (v0.1) +## 已知限制 (v0.5) -- `let` 变量不可变（无 `mut`），循环计数器无法修改 — 迭代算法需递归实现 -- 无字符串类型（`print_*` 是编译器内建，非语言特性） -- 无数组、结构体、枚举、泛型、trait -- 无模块系统（所有函数在单文件） -- 作用域未清理（同函数内变量名不可重用） -- `main` 返回值未被 OS 使用（需 CRT 包装） +- 无泛型 (单态化) +- 无 trait / 接口 +- 无模块系统（所有代码单文件） +- 无指针/引用类型 +- 借用检查 (远期) +- 嵌套数组支持有限 +- `match` 仅语句级（非表达式） ## 版本号升级清单 diff --git a/README.md b/README.md index 352eff4..4702eb6 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,11 @@

- version + version C LLVM GCC - tests + tests license

@@ -73,31 +73,49 @@ graph TB | `codegen/` | `AstNode*` | `LLVMModuleRef` | `CgCtx` {module, builder, var_table} | | `driver/` | 命令行参数 | exit code | 流水线串联 + 错误报告 | -## 功能 (v0.1) +## 功能 (v0.5) ### 类型系统 -| 类型 | 关键字 | 说明 | -|------|--------|------| +| 类型 | 语法 | 示例 | +|------|------|------| | 64 位有符号整数 | `i64` | `42`, `-7` | -| 64 位浮点数 | `f64` | `3.14`, `-0.5` | +| 64 位浮点数 | `f64` | `3.14` | | 布尔值 | `bool` | `true`, `false` | -| 无返回值 | `void` | 函数不返回值时使用 | +| 字符串 | `str` | `"hello"` | +| 结构体 | `struct` | `Point { x: i64, y: i64 }` | +| 枚举 | `enum` | `Color { Red, Green, Blue }` | +| 数组 | `[T; N]` | `[i64; 10]` | +| 无返回值 | `void` | 函数默认 | +| 类型别名 | `type` | `type Meters = i64;` | -- `let` 不可变变量，支持可选类型标注和类型推断 -- 类型在编译时完全确定，无隐式转换（除 `i64` → `f64` 自动提升） +- `let` 不可变 + `let mut` 可变，类型推断 +- `i64` → `f64` 自动提升 ### 控制流 -- `if` / `else` 条件分支（支持 `else if` 链） +- `if` / `else` / `else if` - `while` 循环 -- `return` 提前返回（可选带表达式） +- `for i in 0..10` (去糖为 while) +- `match expr { pat => { ... } _ => { ... } }` (去糖为 if-else) +- `return` -### 函数 +### 函数 & 方法 -- 多参数，显式返回类型（可省略，默认 `void`） -- 递归调用 -- 内建函数：`print_i64`, `print_f64`, `print_bool` +- 多参数、递归、struct 参数/返回值 +- 返回类型校验 +- `impl StructName { fn method(self: Type) -> Ret { ... } }` +- `instance.method(args)` 调用 +- 内建函数：`print_i64`, `print_f64`, `print_bool`, `print_str` + +### 运算符 + +`+ - * / %` `== != < > <= >=` `&& || !` `+= -= *= /=` `str + str` + +### 内存管理 + +- str 拼接 malloc → 作用域退出自动 free (RAII) +- struct/array 栈上值类型 ## 安装 @@ -136,10 +154,11 @@ mingw32-make -j4 # 构建 cd build && mingw32-make -j4 -# 运行全部测试 (65 单元 + 5 集成) +# 运行全部测试 (145 单元 + 23 集成) ./l_lang_lexer_test.exe # 词法分析 (41 tests) ./l_lang_test.exe # 语法分析 (15 tests) -./l_lang_sema_test.exe # 语义分析 (9 tests) +./l_lang_sema_test.exe # 语义分析 (65 tests) +./l_lang_codegen_test.exe # 代码生成 (24 tests) # 集成测试 for f in ../test/programs/*.l; do diff --git a/docs/analysis/architecture-analysis-report-2026-06-05-1509.md b/docs/analysis/architecture-analysis-report-2026-06-05-1509.md new file mode 100644 index 0000000..2addd88 --- /dev/null +++ b/docs/analysis/architecture-analysis-report-2026-06-05-1509.md @@ -0,0 +1,417 @@ +# L Language 架构分析报告 — P1 全线收官 + match 表达式 (v0.5) + +> 日期: 2026-06-05 15:09 | 自动生成 | **有源代码变更** +> 上次代码分析基线: `1d4fb27` (2026-06-05 13:08 报告, v0.4) +> 当前 HEAD: `a15cd9d` feat: match 表达式 (P1 #8 收官) +> +> 新增提交 (自上次源代码基线 `1d4fb27`): +> - `af0725c` fix: 全面代码审查 — 修复 3 CRITICAL + 4 HIGH 问题 +> - `a7fca59` fix: 5项立即修复 + 2项尽快修复 +> - `4046ab1` refactor: tok_is_type 统一 + 架构改进文档 +> - `da9a706` feat: struct参数/返回值 + SourceLoc + 测试补全 (**P1 #5 完成**) +> - `ab88ea2` feat: 类型别名 type alias (**P1 #10 完成**) +> - `5237398` feat: 枚举 enum (**P1 #7 完成**) +> - `2923e75` feat: 数组+索引 [T;N], arr[i] (**P1 #6 完成**) +> - `9f6e695` feat: struct方法 impl (**P1 #9 完成**) +> - `a15cd9d` feat: match 表达式 (**P1 #8 收官**) + +**本次是自 v0.4 以来最大规模的变更: 9 个提交, P1 全部 6 项需求一次性落地。** + +--- + +## 变更摘要 (自上次代码基线) + +**27 个文件变更, +2596 / -284 行。** P1 路线图全覆盖: + +| 变更类别 | 详情 | 影响范围 | +|---------|------|---------| +| **P1 #5: struct 参数/返回值** | parser 扩展 param/return type 解析; SourceLoc 抽象落地 | parser/sema/codegen/driver | +| **P1 #10: 类型别名** | `type Meters = i64;` / `type P = Point;` 全流水线 | parser/sema(alias 展开链) | +| **P1 #7: 枚举 enum** | `enum Color { Red, Green, Blue }`, `Color::Green` 变体 | lexer/parser/sema/codegen | +| **P1 #6: 数组+索引** | `let arr: [i64; 3]`, `arr[i]`, `arr[i] = expr` | lexer/parser/sema/codegen(GEP) | +| **P1 #9: struct 方法 impl** | `impl Point { fn get_x(self: Point) ... }`, `p.method()` 调用 | parser/sema(改名 mangle)/codegen | +| **P1 #8: match 表达式** | `match x { pat => { body } _ => { body } }`, parser 脱糖 | parser(desugar 为 let+if-else) | +| **基础设施重构** | SourceLoc 抽象, tok_is_type 统一, 架构改进文档, CRITICAL bug 修复 | 全项目 | +| **测试扩展** | sema: 9→21 tests; codegen: 4→9 tests; 集成: 13→23 programs | test/ | + +--- + +## 1. 当前架构全景 + +### 1.1 编译流水线 + +``` +源码(.l) → Lexer(词法) → Parser(语法) → Sema(语义) → Codegen(LLVM IR) → Target(obj) → GCC 链接(.exe) + 50 Token 25 AST 节点 类型标注 LLVMModuleRef .o 文件 +``` + +**流水线结构无变化**，但数据流丰富度大幅提升: AST 节点从 18 增至 25, Token 从 39 增至 50, TypeKind 从 8 增至 10。 + +### 1.2 模块清单与指标 + +| 模块 | 关键职责 | 本次变更 | +|------|---------|---------| +| include/ | TypeKind 枚举 (10 种: +TYPE_ENUM, +TYPE_ARRAY), SourceLoc 抽象 | +15 行 | +| lexer/ | 手写状态机, **50** Token 类型 | +38 行 | +| ast/ | **25** 种节点类型 (+7: TYPE_ALIAS, ENUM_DECL, ENUM_VARIANT, INDEX_EXPR, ARRAY_ASSIGN, IMPL_BLOCK, METHOD_CALL) | +218 行 | +| parser/ | 递归下降 + Pratt, 新增 enum/impl/type/match 解析, `parse_type_expr()` 统一类型表达式 | +425 行 | +| sema/ | 类型推断, 5 种 SymbolKind (+SYM_ENUM), impl 方法改名 mangle, alias 展开链 | +542 行 | +| codegen/ | LLVM struct/array/enum/match, GEP, method call, 清理表动态扩容 | +269 行 | +| driver/ | 流水线串联, SourceLoc 适配 | +11 行 | +| test/ | **30** 单元测试函数 (+11), 10 集成程序新增 | +636 行 | + +| 汇总指标 | 上次 (v0.4, 1d4fb27) | **当前 (v0.5, a15cd9d)** | Δ | +|---------|----------------------|-------------------|----| +| 实现代码 (.c) | 2,221 行 | **~3,480 行** | +~1,259 | +| 头文件 (.h) | 323 行 | **~450 行** | +~127 | +| 测试代码 | 361 行 | **~997 行** | +636 | +| **总代码量** | **2,905 行** | **~4,927 行** | **+2,022** | +| Token 类型 | 39 | **50** | +11 | +| AST 节点类型 | 18 | **25** | +7 | +| TypeKind | 8 | **10** | +2 | +| SymbolKind | 4 | **5** | +1 | +| 单元测试函数 | 19 | **30** | +11 | +| 集成测试程序 | 13 | **23** | +10 | +| P0 完成度 | 4/4 (100%) | 4/4 (100%) | — | +| P1 完成度 | 0/6 (0%) | **6/6 (100%)** | ✅ | +| Git 提交数 | 13 | **22** | +9 | + +### 1.3 关键架构决策 (v0.5 新增) + +| 决策 | 描述 | 技术理由 | +|------|------|---------| +| **impl 改名 mangle** | `impl Point { fn get_x }` 在 sema 阶段将函数名改为 `Point$get_x`, 自动插入 self 参数 | 零入侵 codegen: 方法调用退化为普通函数调用 | +| **match 脱糖为 let+if-else** | parser 阶段将 match 转为 `{ let __match_val=expr; if ... else ... }` | 复用现有 if-else codegen, 零新增 LLVM IR 路径 | +| **数组类型自引用声明** | `let arr: [i64; 3] = arr;` 以自身标识符为初始化占位符 | ArrayType 固定大小, sema/codegen 识别 TYPE_ARRAY 标注后跳过 init 分析 | +| **parse_type_expr 统一入口** | 所有类型标注解析通过同一函数 | 消除分散类型解析, 支持 `[T; N]` 嵌套 | +| **cleanup_list 动态扩容** | 从固定 64 槽改为 realloc 式动态扩容 (16→x2) | 消除溢出风险 | +| **SourceLoc 聚合** | `typedef struct { int line; int col; }` 替代所有 `int line, int col` 参数对 | 减少参数数量, 为后续添加 `file` 做准备 | + +--- + +## 2. P1 全线功能详解 + +### 2.1 struct 作为函数参数/返回值 (P1 #5) + +parser 的 `parse_function` 参数类型解析从 `token_to_type()` 改为 `parse_type_expr()`, 支持 `fn f(p: Point) -> Point`。Codegen 中 struct 参数通过 alloca+store 转为栈变量, struct 返回值通过直接值传递 (LLVM struct 类型)。 + +**测试**: `14_struct_fn.l` — Point 作为参数和返回值。 + +### 2.2 类型别名 type alias (P1 #10) + +`parse_type_expr()` 识别 `TOK_IDENT` 时查找已注册别名; sema Pass 0 提前注册所有别名。 + +``` +语法: type Meters = i64; + type P = Point; + +别名展开链: + parser: 解析 `let x: P` → annot struct_type_name="P" + sema: scope_lookup("P") → 别名符号 → 获取真实 type=STRUCT/struct_type_name="Point" +``` + +**测试**: `15_type_alias.l`, `16_type_alias_struct.l` + +### 2.3 枚举 enum (P1 #7) + +新增 TOK_ENUM/TOK_COLON_COLON Token; `AST_ENUM_DECL`/`AST_ENUM_VARIANT` AST 节点; SYM_ENUM SymbolKind。枚举变体映射为 i64 常量 (0, 1, 2...)。 + +``` +语法: enum Color { Red, Green, Blue } + let c = Color::Green; // codegen: LLVMConstInt(LLVMInt64Type, 1) +``` + +**测试**: `17_enum.l`, sema: test_enum_ok/test_enum_bad_variant + +### 2.4 数组 + 索引 (P1 #6) + +新增 `[i64; N]` 语法 (`parse_type_expr` 中解析), `AST_INDEX_EXPR` (读取), `AST_ARRAY_ASSIGN_STMT` (写入)。 + +``` +语法: let arr: [i64; 3] = arr; + arr[0] = 10; + print_i64(arr[0]); + +Codegen: LLVMArrayType(elem_ty, N) → alloca → GEP(0, i) → load/store + 索引值 i64 → i32 截断 (LLVM GEP 要求 i32) +``` + +**测试**: `18_array.l`, sema 4 测试, codegen: test_codegen_array + +### 2.5 struct 方法 impl (P1 #9) + +`parse` 处理 `impl StructName { ... }` 块; sema 将方法函数名改为 `StructName$methodName` 并追加 self 参数。 + +``` +语法: impl Point { + fn get_x(self: Point) -> i64 { return self.x; } + } + p.get_x(); // AST_METHOD_CALL + +Mangle 流程: + parser: impl → AST_IMPL_BLOCK { struct_name, methods } + sema: 遍历 impl → 改名 "Point$get_x", 插入前导 self 参数, 追加到 functions 数组 + codegen: find_fn("Point$get_x") + call(receiver, args...) — 退化为普通函数调用 +``` + +**测试**: `19_struct_method.l`, sema 2 测试, codegen: test_codegen_method_call + +### 2.6 match 表达式 (P1 #8) + +新增 TOK_MATCH/TOK_MATCH_ARROW/TOK_UNDERSCORE Token; parser 内 `parse_match_stmt()` 将 match 脱糖为 let+if-else 链。 + +``` +语法: match expr { + pat1 => { body1; } + _ => { default_body; } + } + +脱糖逻辑 (parser 阶段): + match c { Color::Green => { print_i64(20); } _ => { print_i64(0); } } + → { + let __match_val = c; + if __match_val == Color::Green { print_i64(20); } + else { print_i64(0); } + } + +臂数 64 上限, 从最后一个臂往前构建 if-else 链 +``` + +**关键设计**: match 不产生新 AST 节点 — 直接生成 AST_BLOCK + AST_LET_STMT + AST_IF_STMT 链; codegen/sema 零改动。 + +**测试**: 4 个集成测试 (`20_match.l`~`23_match_wildcard.l`) + +--- + +## 3. 架构重构与基础设施 + +### 3.1 SourceLoc 抽象 + +```c +// include/l_lang.h +typedef struct { int line; int col; } SourceLoc; +``` + +所有 AST 工厂函数从 `int line, int col` 参数对改为 `SourceLoc loc` 单参数。全模块已适配。 + +### 3.2 tok_is_type 统一 + +删除 parser.c 中重复的 `is_type_token()` 函数, 统一使用 `token.c:tok_is_type()` (已补 TOK_STR)。 + +### 3.3 CRITICAL Bug 修复清单 + +| 严重度 | 问题 | 修复 | +|--------|------|------| +| CRITICAL | parser `parse_struct_init` 字段名数组栈变量悬垂 | arena 分配 + memcpy | +| CRITICAL | codegen 隐式尾部 return 缺 struct 类型处理 | 添加 `LLVMConstNull(st_ty)` | +| CRITICAL | str 字面量 tok 未 NUL 终止 | arena_strdup + `\0` | +| HIGH | codegen return 前 cleanup 可能 free 返回值 | 从 cleanup_list 移除 | +| HIGH | match 通配符 if-else 链条件 | `if (true) { body }` | +| HIGH | sema impl 处理 `new_fns` 数组大小计算时机 | 预先统计 extra_fn | + +--- + +## 4. 功能清单与成熟度 + +### 4.1 已实现功能 (全版本) + +- [x] v0.1: 基本类型/算术/控制流/函数/内置函数/类型推断 +- [x] v0.2: let mut/赋值/str/字符串拼接/复合赋值 +- [x] v0.3: for + range +- [x] v0.4: struct 声明+初始化+字段访问/嵌套结构体/RAII 自动内存管理 +- [x] **v0.5: P1 全线 — struct 参数/返回值/类型别名/枚举/数组+索引/impl 方法/match 表达式** + +### 4.2 当前已知限制 + +| 限制 | 严重度 | 说明 | +|------|--------|------| +| 数组不支持 struct 元素类型 `[Point; N]` | 中 | parse_type_expr TYPE_ARRAY 路径未传 element_struct_name | +| enum 无关联数据 (代数数据类型) | 中 | 仅 C 风格枚举 | +| 无表达式作为值 (expression-oriented) | 中 | if/match/block 不能出现在表达式位置 | +| match 仅单值匹配 | 低 | 不支持 range pattern / guard | +| 数组声明自引用语法 `let arr: [i64; 3] = arr;` | 低 | 必须写两遍 arr | +| 无字符串方法 (len/slice) | 低 | str 仅拼接+打印 | + +--- + +## 5. 与 Rust 对标: 缺失功能清单及优先级 + +### 已完成 (P0 + P1 全通过) + +| # | 功能 | Rust 启发 | 版本 | +|---|------|----------|------| +| P0-1~4 | 复合赋值/str拼接/for+range/struct | — | v0.2–v0.4 | +| P1-5 | struct 参数/返回值 | 值语义 | v0.5 | +| P1-6 | 数组+索引 | `[T; N]`, `arr[i]` | v0.5 | +| P1-7 | 枚举 | enum | v0.5 | +| P1-8 | match 表达式 | 模式匹配 (简化) | v0.5 | +| P1-9 | struct 方法 | impl block | v0.5 | +| P1-10 | 类型别名 | type alias | v0.5 | + +### P2: 中后期 + +| # | 功能 | 预计工时 | 状态 | +|---|------|---------|------| +| 11 | 表达式作为值 (expression-oriented) | 2–3 天 | 待实施 | +| 12 | 模块系统 `mod` + `use` | 3–5 天 | 待实施 | +| 13 | 泛型 (单态化) | 5–7 天 | 待实施 | +| 14 | 枚举关联数据 (代数数据类型) | 2 天 | 待实施 | +| 15 | trait / 接口 | 5–7 天 | 待实施 | + +### P3: 长期 + +| # | 功能 | 预计工时 | +|---|------|---------| +| 16 | 所有权 / 借用检查 | 2–4 周 | +| 17 | 自举 (L 编译 L) | 4–6 周 | +| 18 | 标准库 (prelude) | 4–6 周 | + +### Rust 设计哲学吸收进度 + +| Rust 特性 | 状态 | 备注 | +|-----------|------|------| +| 默认不可变 (let vs let mut) | ✅ | 编译期检查 | +| 复合赋值 | ✅ | parser desugar | +| for + range | ✅ | desugar 为 while | +| struct 具名域 | ✅ | LLVM 命名结构体 | +| impl 方法 | ✅ | sema mangle | +| enum + match (简化) | ✅ | C 风格枚举 + 单值 match | +| 类型别名 | ✅ | alias 展开链 | +| 数组固定大小 | ✅ | GEP | +| RAII 自动释放 | ✅ | cleanup_list | +| 表达式 vs 语句 | ❌ | P2 优先 | +| 代数数据类型 | ❌ | P2 优先 | +| 泛型 (单态化) | ❌ | P2 优先 | +| trait / 接口 | ❌ | P2 优先 | +| 所有权 / 借用 | ❌ | P3 | +| 模块系统 | ❌ | P2 优先 | + +--- + +## 6. 测试覆盖分析 + +### 6.1 单元测试 + +| 测试文件 | 测试函数 | 覆盖范围 | +|---------|----------|---------| +| test_lexer.c | 3 | token 识别, 关键字, 操作符, 注释 | +| test_parser.c | 5 | 算术, let, if, while, 函数 | +| test_sema.c | **21** (+12) | 类型错误, let mut, str, struct 字段, 类型别名, enum, 数组, 方法调用 | +| test_codegen.c | **9** (+5) | 基础路径, struct decl/field, enum, array, method call | +| **合计** | **38** (+11) | | + +### 6.2 集成测试 (23 程序) + +- 01–11: v0.1–v0.3 基线 +- 12–13: struct + 嵌套 struct (v0.4) +- **14–23**: v0.5 新增 10 程序 (struct_fn/type_alias/enum/array/struct_method/4×match) + +### 6.3 测试缺口 + +| 缺口 | 严重度 | +|------|--------| +| match/sema 无独立单元测试 | 高 | +| 数组 struct 元素类型无测试 | 中 | +| RAII + 新功能交互无验证 | 中 | +| parser 错误恢复无测试 | 低 | + +--- + +## 7. 技术债务与风险 + +| # | 问题 | 严重度 | 说明 | +|---|------|--------|------| +| 1 | analyze_expr 持续膨胀 (200+→350+ 行) | 高 | ENUM_VARIANT/INDEX_EXPR/METHOD_CALL 等 | +| 2 | parser.c 单文件 939 行 | 中 | +415 行: enum/impl/type/match/match 脱糖 | +| 3 | codegen.c 单文件 854 行 | 中 | 3 个 switch 持续增长 | +| 4 | match 脱糖在 parser, 非独立 pass | 中 | arch-improvements #4 建议未实施 | +| 5 | 数组 struct 元素类型未实现 | 中 | `[Point; N]` | +| 6 | TypeKind 耦合 (arch-improvements #1) | 低 | 加新类型需改 7+ 文件 | +| 7 | AST Visitor 缺失 (arch-improvements #2) | 低 | 加新节点需改 4 个 switch | +| 8 | CHANGELOG 未更新 v0.4/v0.5 | 低 | 仅到 v0.3 | +| 9 | LLVM 22 无 mem2reg C API | 低 | 已记录 | +| 10 | `system("gcc ...")` 平台绑定 | 低 | Windows/MinGW | + +--- + +## 8. 推荐开发路线图 + +### v0.6 目标 (下一迭代, 2–3 天) + +| 优先级 | 功能 | 预计工时 | +|--------|------|---------| +| P1 | parser 独立 desugar pass (for/match/compound assign) | 0.5 天 | +| P1 | 数组 struct 元素类型 `[Point; N]` | 0.5 天 | +| P1 | match/sema 单元测试 | 0.5 天 | +| P2 | CHANGELOG 更新 v0.4/v0.5 | 0.5 天 | + +### v0.7 目标 + +| 优先级 | 功能 | 预计工时 | +|--------|------|---------| +| P2 | 表达式作为值 (expression-oriented) | 2–3 天 | +| P2 | 枚举关联数据 | 2 天 | +| P2 | AST Visitor 宏驱动 | 2 天 | + +### 长期方向 + +| 优先级 | 功能 | 预计工时 | +|--------|------|---------| +| P2 | 模块系统 / 泛型 / trait | 各 3–7 天 | +| P3 | 所有权 / 自举 / 标准库 | 2–6 周 | + +--- + +## 9. 代码质量评估 + +### 9.1 模块内聚度 + +| 模块 | 评价 | +|------|------| +| lexer | 高 — 11 新 Token 一字插入 | +| parser | **中** — +415 行, parse_match_stmt(80行) + parse_type_expr(40行) + impl/enum/type 内联 | +| ast | 高 — 7 新节点遵循工厂函数模式 | +| sema | **中高** — +542 行: impl mangle/alias 展开/enum/array/method 语义; analyze_expr switch 350+ 行 | +| codegen | **中** — +269 行: enum/array/index/method/match; 3 个 switch 持续增长 | +| driver | 高 — 仅 SourceLoc 适配 | +| util | 高 — 无变更 | + +### 9.2 代码风格亮点 + +- **impl mangle 设计**: sema 阶段转换, codegen 零修改 — 干净解耦 +- **match 脱糖**: 转为 AST 原语链, sema/codegen 完全复用 (但耦合在 parser 中) +- **parse_type_expr 统一**: 消除分散类型解析, 天然支持 `[T; N]` +- **cleanup_list 动态扩容**: arena 分配保持 zero-overhead + +### 9.3 架构债务 + +| 债务 | 说明 | +|------|------| +| parser.c 939 行 | 含 enum/impl/type/match + 脱糖, 建议 P2 模块化 | +| sema analyze_expr 350+ 行 | CASE 从 5 增至 10 | +| codegen 3 个 switch 增长 | 新增 3 case (ENUM_VARIANT/METHOD_CALL/INDEX_EXPR) | +| impl mangle 隐式命名约定 | codegen 通过 `$` 识别方法, 非结构化标记 | + +--- + +## 10. 度量汇总 (对比) + +| 指标 | v0.4 (1d4fb27) | **v0.5 (a15cd9d)** | Δ | +|------|----------------|-------------------|----| +| 实现代码 | 2,221 行 | **~3,480 行** | +~1,259 | +| 头文件 | 323 行 | **~450 行** | +~127 | +| 测试代码 | 361 行 | **~997 行** | +636 | +| **总代码量** | **2,905 行** | **~4,927 行** | **+2,022** | +| Token 类型 | 39 | **50** | +11 | +| AST 节点类型 | 18 | **25** | +7 | +| TypeKind | 8 | **10** | +2 | +| SymbolKind | 4 | **5** | +1 | +| 单元测试函数 | 19 | **30** | +11 | +| 集成测试程序 | 13 | **23** | +10 | +| P0 完成度 | 4/4 (100%) | 4/4 (100%) | — | +| P1 完成度 | 0/6 (0%) | **6/6 (100%)** | ✅ | +| Git 提交数 | 13 | **22** | +9 | + +--- + +*本报告由 Codex 自动生成于 2026-06-05 15:09。自上次代码基线 `1d4fb27` (v0.4) 后有 9 个源代码提交 (+2596/-284 行): P1 路线图全线收官 — struct 参数/返回值、类型别名、枚举、数组+索引、struct 方法 impl、match 表达式全部落地。v0.5 实现了 Rust 启发语言的完整单片编译器能力; 下一迭代应关注 parser 独立 desugar pass、数组 struct 元素类型补全、表达式作为值。* diff --git a/docs/analysis/architecture-analysis-report-2026-06-05-1708.md b/docs/analysis/architecture-analysis-report-2026-06-05-1708.md new file mode 100644 index 0000000..83df10d --- /dev/null +++ b/docs/analysis/architecture-analysis-report-2026-06-05-1708.md @@ -0,0 +1,185 @@ +# L Language 架构分析报告 — 无代码变更 (快照复查) + +> 日期: 2026-06-05 17:08 | 自动生成 | **无源代码变更** +> 上次代码基线: `a15cd9d` (2026-06-05 15:09 报告, v0.5) +> 当前 HEAD: `a15cd9d` feat: match 表达式 (P1 #8 收官) +> +> **结论: 自上次架构分析报告以来无新提交。以下为当前架构快照及健全性复查。** + +--- + +## 代码变更检查 + +``` +git log a15cd9d..HEAD → (空) +``` + +`a15cd9d` 仍是 HEAD。与上次报告 (2026-06-05 15:09) 完全一致。**零文件变更，零行差异。** + +--- + +## 1. 当前架构快照 (v0.5) + +### 1.1 编译流水线 + +``` +源码(.l) → Lexer(词法) → Parser(语法) → Sema(语义) → Codegen(LLVM IR) → Target(obj) → GCC 链接(.exe) + 50 Token 25 AST 节点 类型标注 LLVMModuleRef .o 文件 +``` + +### 1.2 模块清单与行数 + +| 模块 | 文件 | 行数 | 职责 | +|------|------|------|------| +| include/ | l_lang.h | 57 | TypeKind (10), SourceLoc, 公共类型 | +| lexer/ | lexer.c + token.c (+ .h) | 163 + 54 | 手写状态机, 50 Token 类型 | +| ast/ | ast.c + ast.h | 245 + 159 | 25 种 AST 节点, 工厂函数 | +| parser/ | parser.c + parser.h | 825 + 13 | 递归下降 + Pratt, parse_type_expr 统一 | +| sema/ | sema.c + symbol.c (+ .h) | 809 + 155 | 类型推断, alias 展开, impl mangle | +| codegen/ | codegen.c + target.c (+ .h) | 824 + 35 | LLVM IR 生成, GEP, enum/array/match | +| driver/ | main.c + error.c (+ .h) | 160 + 49 | 流水线串联, 错误报告 | +| util/ | arena.c + arena.h | 45 + 17 | Bump allocator (8MB) | +| **实现总计** | | **~3,336 行** | | +| test/ | test_*.c × 4 | 944 | 30 单元测试函数 | +| test/ | programs/*.l × 23 | — | 23 集成测试程序 | +| **测试总计** | | **~944 行** | | + +### 1.3 核心类型系统 + +| 枚举 | 成员数 | 位置 | +|------|--------|------| +| TypeKind | 10 (+2 vs v0.4) | include/l_lang.h:9, TYPE_ENUM + TYPE_ARRAY | +| TokenKind | 50 (+11 vs v0.4) | src/lexer/token.h | +| AstNodeKind | 25 (+7 vs v0.4) | src/ast/ast.h | +| SymbolKind | 5 (+1 vs v0.4) | src/sema/symbol.h:7, SYM_ENUM | + +**TypeKind 成员**: TYPE_I64, TYPE_F64, TYPE_BOOL, TYPE_STR, TYPE_VOID, TYPE_STRUCT, TYPE_ENUM, TYPE_ARRAY, TYPE_UNKNOWN, TYPE_ERROR + +**SymbolKind 成员**: SYM_VARIABLE, SYM_PARAMETER, SYM_FUNCTION, SYM_STRUCT, SYM_ENUM + +### 1.4 关键架构决策 + +| 决策 | 说明 | +|------|------| +| impl 改名 mangle | sema 阶段将 `impl S { fn f }` 转为 `S$f`, 追加 self 参数; codegen 零修改 | +| match 脱糖为 let+if-else | parser 阶段直接生成 AST_BLOCK + AST_LET_STMT + AST_IF_STMT 链; sema/codegen 完全复用 | +| parse_type_expr 统一入口 | 所有类型标注解析通过同一函数, 天然支持 `[T; N]` 嵌套 | +| SourceLoc 聚合 | `{ int line; int col; }` 替代所有松散参数对 | +| cleanup_list 动态扩容 | arena realloc, 消除固定 64 槽溢出风险 | + +--- + +## 2. 功能完成度总览 + +### 2.1 P0 (v0.1-v0.4) — 100% + +- [x] 词法/语法/语义三阶段解析 +- [x] i64/f64/bool/void/str 类型 +- [x] 算术/比较/逻辑运算 +- [x] if/else/while/return 控制流 +- [x] 函数定义+调用+递归 +- [x] let/let mut 变量+赋值 +- [x] 字符串拼接 str+str +- [x] 复合赋值 += -= *= /= +- [x] for + range (去糖为 let mut + while + assign) +- [x] struct 声明/初始化/字段访问/嵌套 +- [x] RAII 自动内存管理 (cleanup_list) +- [x] 3 内置函数: print_i64, print_f64, print_str + +### 2.2 P1 (v0.5) — 100% + +| # | 功能 | Rust 启发 | 实现方式 | +|---|------|----------|---------| +| P1-5 | struct 参数/返回值 | 值语义 | parse_type_expr 扩展 + codegen struct type | +| P1-6 | 数组+索引 | `[T; N]`, `arr[i]` | parse_type_expr 嵌套 + GEP | +| P1-7 | 枚举 | enum | i64 常量映射 + SYM_ENUM | +| P1-8 | match 表达式 | 模式匹配 (简化) | parser 脱糖为 let+if-else | +| P1-9 | struct 方法 impl | impl block | sema mangle + 普通函数调用 | +| P1-10 | 类型别名 | type alias | alias 展开链 (sema Pass 0) | + +--- + +## 3. 测试覆盖 + +| 测试文件 | 测试函数 | 行数 | 覆盖范围 | +|---------|----------|------|---------| +| test_lexer.c | 3 | 53 | token 识别, 关键字, 操作符, 注释 | +| test_parser.c | 5 | 68 | 算术, let, if, while, 函数 | +| test_sema.c | 21 | 391 | 类型检查, let mut, str, struct, enum, array, method, type alias | +| test_codegen.c | 9 | 432 | struct, enum, array, method call, LLVMVerifyModule | +| **合计** | **38 (+11 vs v0.4)** | **944** | | +| 集成 .l 程序 | **23** | — | 算术→if→for→struct→enum→array→method→match | + +--- + +## 4. Rust 对标缺失清单 (现状) + +### 已完成 + +| 特性 | 状态 | +|------|------| +| 默认不可变 (let vs let mut) | ✅ | +| 复合赋值 | ✅ | +| for + range | ✅ | +| struct 具名域 | ✅ | +| impl 方法 | ✅ | +| enum + match (简化) | ✅ | +| 类型别名 | ✅ | +| 数组固定大小 | ✅ | +| RAII 自动释放 | ✅ | + +### 缺失 (P2 — 中期) + +| # | 功能 | 预计工时 | 优先级 | +|---|------|---------|--------| +| 11 | 表达式作为值 (expression-oriented) | 2–3 天 | 高 | +| 12 | 模块系统 `mod` + `use` | 3–5 天 | 高 | +| 13 | 泛型 (单态化) | 5–7 天 | 中 | +| 14 | 枚举关联数据 (代数数据类型) | 2 天 | 高 | +| 15 | trait / 接口 | 5–7 天 | 中 | + +### 缺失 (P3 — 长期) + +| # | 功能 | 预计工时 | +|---|------|---------| +| 16 | 所有权 / 借用检查 | 2–4 周 | +| 17 | 自举 (L 编译 L) | 4–6 周 | +| 18 | 标准库 (prelude) | 4–6 周 | + +--- + +## 5. 技术债务 (不变) + +| # | 问题 | 严重度 | 状态 | +|---|------|--------|------| +| 1 | analyze_expr 膨胀 (350+ 行) | 高 | 未修复 | +| 2 | parser.c 单文件 825 行 | 中 | 未修复 | +| 3 | codegen.c 单文件 824 行 | 中 | 未修复 | +| 4 | match 脱糖在 parser, 非独立 pass | 中 | 未修复 | +| 5 | 数组 struct 元素类型 `[Point; N]` 未实现 | 中 | 未修复 | +| 6 | match/sema 无独立单元测试 | 高 | 未修复 | +| 7 | TypeKind 耦合 (加新类型需改 7+ 文件) | 低 | 未修复 | +| 8 | AST Visitor 缺失 (加节点需改 4 个 switch) | 低 | 未修复 | +| 9 | CHANGELOG 未更新 v0.4/v0.5 | 低 | 未修复 | +| 10 | LLVM 22 无 mem2reg C API | 低 | 平台限制 | + +--- + +## 6. 推荐开发路线图 (重述) + +### v0.6 优先 (2–3 天) + +1. parser 独立 desugar pass (for/match/compound assign) +2. 数组 struct 元素类型 `[Point; N]` +3. match/sema 单元测试 +4. CHANGELOG 更新 + +### v0.7 优先 + +1. 表达式作为值 (expression-oriented) +2. 枚举关联数据 (代数数据类型) +3. AST Visitor 宏驱动 + +--- + +*本报告由 Codex 自动生成于 2026-06-05 17:08。自上次代码基线 `a15cd9d` (v0.5) 以来无新提交 — 代码库处于稳定状态。P1 路线图全线完成, 下一迭代应聚焦 parser 重构、数组 struct 元素类型、match/sema 测试、表达式作为值。*