docs: 更新文档内容
- 移除加粗样式 - 更新 CLI 命令列表,增加 debug 命令 - 添加词法分析和语义分析的示例输出 - 调整编译流程和命令选项的描述
This commit is contained in:
parent
34e5de0454
commit
688d6d7393
169
README.md
169
README.md
@ -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 官网
|
||||||
|
|
||||||
@ -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
|
||||||
@ -130,6 +183,65 @@ 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 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
|
||||||
[
|
[
|
||||||
{
|
{
|
||||||
@ -137,8 +249,8 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
|
|||||||
"name": "Main",
|
"name": "Main",
|
||||||
"imports": [
|
"imports": [
|
||||||
{
|
{
|
||||||
"module": "Math",
|
"type": "Import",
|
||||||
"type": "Import"
|
"module": "Math"
|
||||||
}
|
}
|
||||||
],
|
],
|
||||||
"functions": [
|
"functions": [
|
||||||
@ -240,7 +352,6 @@ Snow 语言受到 LLM 驱动代码生成趋势的启发,强调简单而清晰的
|
|||||||
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
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user