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