Luke/snow
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 更新文档内容

Browse Source 
- 移除加粗样式
- 更新 CLI 命令列表，增加 debug 命令
- 添加词法分析和语义分析的示例输出
- 调整编译流程和命令选项的描述
This commit is contained in:
Luke 2025-07-24 12:59:26 +08:00
parent 34e5de0454
commit 688d6d7393
1 changed files with 197 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

277
README.md
View File

@ -54,11 +54,11 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
| 类别 | 关键特性 | | 类别 | 关键特性 |
|----------|---------------------------------------------------------------------------------------------------| |----------|---------------------------------------------------------------------------------------------------|
| 语言层 | `module` / `import` / `function` / `loop` / `if–else` / Pratt 表达式解析<br>静态类型检查 & 作用域分析 | | 语言层 | `module` / `import` / `function` / `loop` / `if–else` / Pratt 表达式解析<br>静态类型检查 & 作用域分析 |
| 编译器前端 | **Lexer / Parser / Semantic Analyzer** 全栈自研，生成 JSON-AST | | 编译器前端 | Lexer / Parser / Semantic Analyzer 全栈自研，生成 JSON-AST |
| IR & 后端 | 三地址式 IR ➜ 线性扫描寄存器分配 ➜ SnowVM 指令 | | IR & 后端 | 三地址式 IR ➜ 线性扫描寄存器分配 ➜ SnowVM 指令 |
| 虚拟机 | 栈 + 寄存器混合架构、GUI 局部变量监视 | | 虚拟机 | 栈 + 寄存器混合架构、GUI 局部变量监视 |
| snow pkg | - `.cloud` DSL 描述项目、依赖与构建<br>- 预设 `clean / compile / run / package / publish` 任务<br>- 离线缓存与远程仓库解析 | | snow pkg | - `.cloud` DSL 描述项目、依赖与构建<br>- 预设 `clean / compile / run / package / publish` 任务<br>- 离线缓存与远程仓库解析 |
| CLI | `snow init`, `snow compile`, `snow run`, `snow clean`, `snow build`, `snow generate` | | CLI | init, compile, run, clean, build, generate,debug |
## Snow-Lang 官网 ## Snow-Lang 官网
@ -104,7 +104,7 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
4. **运行成功** 4. **运行成功**
`````snow `````snow
## 编译器输出 ## 编译器输出
### Snow 源代码 ### Snow 源代码
#### Main.snow #### Main.snow
@ -118,6 +118,59 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
end body end body
end function end function
end module end module
line col type lexeme
----------------------------------------------------
1 1 KEYWORD module
1 7 COLON :
1 9 IDENTIFIER Main
1 13 NEWLINE \n
2 5 KEYWORD import
2 11 COLON :
2 12 IDENTIFIER Math
2 16 NEWLINE \n
3 5 KEYWORD function
3 13 COLON :
3 15 IDENTIFIER main
3 19 NEWLINE \n
4 9 KEYWORD return_type
4 20 COLON :
4 22 TYPE int
4 25 NEWLINE \n
5 9 KEYWORD body
5 13 COLON :
5 14 NEWLINE \n
6 13 IDENTIFIER Math
6 17 DOT .
6 18 IDENTIFIER add
6 21 LPAREN (
6 22 NUMBER_LITERAL 6
6 23 COMMA ,
6 24 NUMBER_LITERAL 1
6 25 RPAREN )
6 26 NEWLINE \n
7 13 KEYWORD return
7 20 NUMBER_LITERAL 0
7 21 NEWLINE \n
8 9 KEYWORD end
8 13 KEYWORD body
8 17 NEWLINE \n
9 5 KEYWORD end
9 9 KEYWORD function
9 17 NEWLINE \n
10 1 KEYWORD end
10 5 KEYWORD module
10 1 EOF
## 词法分析通过，没有发现错误
#### Math.snow #### Math.snow
module: Math module: Math
function: add function: add
@ -126,121 +179,179 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
declare n2: int declare n2: int
return_type: int return_type: int
body: body:
return n1 + n2 return n1 + n2
end body end body
end function end function
end module end module
line col type lexeme
----------------------------------------------------
1 1 KEYWORD module
1 7 COLON :
1 9 IDENTIFIER Math
1 13 NEWLINE \n
2 5 KEYWORD function
2 13 COLON :
2 15 IDENTIFIER add
2 18 NEWLINE \n
3 9 KEYWORD parameter
3 18 COLON :
3 19 NEWLINE \n
4 13 KEYWORD declare
4 21 IDENTIFIER n1
4 23 COLON :
4 25 TYPE int
4 28 NEWLINE \n
5 13 KEYWORD declare
5 21 IDENTIFIER n2
5 23 COLON :
5 25 TYPE int
5 28 NEWLINE \n
6 9 KEYWORD return_type
6 20 COLON :
6 22 TYPE int
6 25 NEWLINE \n
7 9 KEYWORD body
7 13 COLON :
7 14 NEWLINE \n
8 12 KEYWORD return
8 19 IDENTIFIER n1
8 22 PLUS +
8 24 IDENTIFIER n2
8 26 NEWLINE \n
9 9 KEYWORD end
9 13 KEYWORD body
9 17 NEWLINE \n
10 5 KEYWORD end
10 9 KEYWORD function
10 17 NEWLINE \n
11 1 KEYWORD end
11 5 KEYWORD module
11 1 EOF
## 词法分析通过，没有发现错误
## 语义分析通过，没有发现错误
### AST ### AST
[ [
{ {
"type": "Module", "type": "Module",
"name": "Main", "name": "Main",
"imports": [ "imports": [
{ {
"module": "Math", "type": "Import",
"type": "Import" "module": "Math"
} }
], ],
"functions": [ "functions": [
{ {
"type": "Function", "type": "Function",
"name": "main", "name": "main",
"parameters": [ "parameters": [
], ],
"returnType": "int", "returnType": "int",
"body": [ "body": [
{ {
"type": "ExpressionStatement", "type": "ExpressionStatement",
"expression": { "expression": {
"type": "CallExpression", "type": "CallExpression",
"callee": { "callee": {
"type": "MemberExpression", "type": "MemberExpression",
"object": { "object": {
"type": "Identifier", "type": "Identifier",
"name": "Math" "name": "Math"
}, },
"member": "add" "member": "add"
}, },
"arguments": [ "arguments": [
{ {
"type": "NumberLiteral", "type": "NumberLiteral",
"value": "6" "value": "6"
}, },
{ {
"type": "NumberLiteral", "type": "NumberLiteral",
"value": "1" "value": "1"
} }
] ]
} }
}, },
{ {
"type": "Return", "type": "Return",
"value": { "value": {
"type": "NumberLiteral", "type": "NumberLiteral",
"value": "0" "value": "0"
} }
} }
] ]
} }
] ]
}, },
{ {
"type": "Module", "type": "Module",
"name": "Math", "name": "Math",
"imports": [ "imports": [
], ],
"functions": [ "functions": [
{ {
"type": "Function", "type": "Function",
"name": "add", "name": "add",
"parameters": [ "parameters": [
{ {
"name": "n1", "name": "n1",
"type": "int" "type": "int"
}, },
{ {
"name": "n2", "name": "n2",
"type": "int" "type": "int"
} }
], ],
"returnType": "int", "returnType": "int",
"body": [ "body": [
{ {
"type": "Return", "type": "Return",
"value": { "value": {
"type": "BinaryExpression", "type": "BinaryExpression",
"left": { "left": {
"type": "Identifier", "type": "Identifier",
"name": "n1" "name": "n1"
}, },
"operator": "+", "operator": "+",
"right": { "right": {
"type": "Identifier", "type": "Identifier",
"name": "n2" "name": "n2"
}
} }
} }
}
] ]
} }
] ]
} }
] ]
### IR ### IR
func main() { func main() {
%0 = CONST 6 %0 = CONST 6
%1 = CONST 1 %1 = CONST 1
%2 = CALL Math.add, %0, %1 %2 = CALL Math.add, %0, %1
%3 = CONST 0 %3 = CONST 0
RET %3 RET %3
} }
func add(%0, %1) { func add(%0, %1) {
%2 = ADD_I32 %0, %1 %2 = ADD_I32 %0, %1
RET %2 RET %2
} }
### VM code ### VM code
0000: I_PUSH 6 0000: I_PUSH 6
0001: I_STORE 0 0001: I_STORE 0
@ -248,35 +359,41 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
0003: I_STORE 1 0003: I_STORE 1
0004: I_LOAD 0 0004: I_LOAD 0
0005: I_LOAD 1 0005: I_LOAD 1
0006: CALL 12 2 0006: CALL 13 2
0007: I_STORE 2 0007: I_STORE 2
0008: I_PUSH 0 0008: I_PUSH 0
0009: I_STORE 3 0009: I_STORE 3
0010: I_LOAD 3 0010: I_LOAD 3
0011: HALT 0011: HALT
0012: I_LOAD 0 0012: HALT
0013: I_LOAD 1 0013: I_LOAD 0
0014: I_ADD 0014: I_LOAD 1
0015: I_STORE 2 0015: I_ADD
0016: I_LOAD 2 0016: I_STORE 2
0017: RET 0017: I_LOAD 2
0018: RET
0019: RET
Written to D:\Devs\IdeaProjects\Snow\target\Demo1.water Written to D:\Devs\IdeaProjects\Snow\target\Demo1.water
=== Launching VM === === Launching VM ===
Calling function at address: 12
Calling function at address: 13
Return 7 Return 7
Process has ended Process has ended
Operand Stack state:[0] Operand Stack state:[0]
--- Call Stack State --- --- Call Stack State ---
### VM Local Variable Table: ### VM Local Variable Table:
0: 6 0: 6
1: 1 1: 1
2: 7 2: 7
3: 0 3: 0
=== VM exited ===
````` `````
## 编译 Snow 源代码 ## 编译 Snow 源代码
@ -287,36 +404,36 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
#### 独立编译步骤: #### 独立编译步骤:
1. **运行编译器: ** 1. **运行编译器:**
你可以通过以下命令来编译单个或多个 `.snow` 文件，或者递归编译一个目录中的所有 `.snow` 源文件为`.water`虚拟机指令。 你可以通过以下命令来编译单个或多个 `.snow` 文件，或者递归编译一个目录中的所有 `.snow` 源文件为`.water`虚拟机指令。
* **单个文件编译: ** * **单个文件编译:**
```bash ```bash
Snow complete [SnowCode].snow Snow complete [SnowCode].snow
``` ```
* **多个文件编译: ** * **多个文件编译:**
```bash ```bash
Snow complete [SnowCode1].snow [SnowCode2].snow [SnowCode3].snow -o [Name] Snow complete [SnowCode1].snow [SnowCode2].snow [SnowCode3].snow -o [Name]
``` ```
* **目录递归编译: ** * **目录递归编译:**
```bash ```bash
Snow -d path/to/source_dir Snow -d path/to/source_dir
``` ```
2. **查看编译输出: ** 2. **查看编译输出:**
编译过程会输出源代码、抽象语法树（AST）、中间表示（IR）以及虚拟机指令等内容。你可以看到如下几个分段输出: 编译过程会输出源代码、抽象语法树（AST）、中间表示（IR）以及虚拟机指令等内容。你可以看到如下几个分段输出:
* **AST**（抽象语法树）部分以 JSON 格式输出。 * **AST**（抽象语法树）部分以 JSON 格式输出。
* **IR**（中间表示）部分会列出逐行的中间代码。 * **IR**（中间表示）部分会列出逐行的中间代码。
* **VM code**（虚拟机指令）会展示虚拟机的字节码指令。 * **VM code**（虚拟机指令）会展示虚拟机的字节码指令。
3. **默认执行模式: ** 3. **默认执行模式:**
编译器会在 **DEBUG 模式** 下运行，显示详细的执行过程和状态，并且在虚拟机中执行编译后的代码，最后会打印出所有局部变量的值。 编译器会在 **RUN 模式** 下运行，**DEBUG 模式**显示详细的执行过程和状态，并且在虚拟机中执行编译后的代码，最后会打印出所有局部变量的值。
--- ---
@ -326,18 +443,18 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
#### 集成编译命令: #### 集成编译命令:
1. **基本用法: ** 1. **基本用法:**
```bash ```bash
snow [OPTIONS] <command> snow [OPTIONS] <command>
``` ```
2. **命令选项: ** 2. **命令选项:**
* `-h, --help`: 显示帮助信息并退出。 * `-h, --help`: 显示帮助信息并退出。
* `-v, --version`: 打印 Snow 编程语言的版本并退出。 * `-v, --version`: 打印 Snow 编程语言的版本并退出。
3. **可用命令: ** 3. **可用命令:**
* `compile`: 将 `.snow` 源文件编译成虚拟机字节码文件（`.water`）。此命令会使用 `.cloud` 文件来指导编译过程。 * `compile`: 将 `.snow` 源文件编译成虚拟机字节码文件（`.water`）。此命令会使用 `.cloud` 文件来指导编译过程。
* `clean`: 清理构建输出和本地缓存，移除中间产物，释放磁盘空间。 * `clean`: 清理构建输出和本地缓存，移除中间产物，释放磁盘空间。
@ -347,7 +464,7 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
* `generate`: 根据 `project.cloud` 生成项目目录结构。 * `generate`: 根据 `project.cloud` 生成项目目录结构。
* `build`: 构建当前项目，按顺序解析依赖、编译和打包。 * `build`: 构建当前项目，按顺序解析依赖、编译和打包。
4. **例如，执行集成编译命令: ** 4. **例如，执行集成编译命令:**
```bash ```bash
snow compile [SnowCode].snow snow compile [SnowCode].snow
@ -355,7 +472,7 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
* 此命令会使用 `.cloud` 文件中的配置信息来指导编译过程，并生成 `.water`。 * 此命令会使用 `.cloud` 文件中的配置信息来指导编译过程，并生成 `.water`。
5. **使用帮助: ** 5. **使用帮助:**
如果你需要了解某个命令的详细选项，可以使用: 如果你需要了解某个命令的详细选项，可以使用:
```bash ```bash