增加文档
This commit is contained in:
parent
4ba7f6c2f7
commit
a7f1627df0
@ -1,6 +1,6 @@
|
||||
<component name="ProjectRunConfigurationManager">
|
||||
<configuration default="false" name="Main" type="Application" factoryName="Application" nameIsGenerated="true">
|
||||
<option name="MAIN_CLASS_NAME" value="org.jcnc.snow.compiler.Main" />
|
||||
<option name="MAIN_CLASS_NAME" value="org.jcnc.snow.compiler.cli.SnowCompiler" />
|
||||
<module name="SCompiler" />
|
||||
<option name="PROGRAM_PARAMETERS" value="test" />
|
||||
<extension name="coverage">
|
||||
|
||||
@ -1,27 +1,19 @@
|
||||
package org.jcnc.snow.compiler;
|
||||
package org.jcnc.snow.compiler.cli;
|
||||
|
||||
import org.jcnc.snow.compiler.lexer.LexerEngine;
|
||||
import org.jcnc.snow.compiler.lexer.core.LexerEngine;
|
||||
import org.jcnc.snow.compiler.lexer.token.Token;
|
||||
import org.jcnc.snow.compiler.lexer.utils.TokenPrinter;
|
||||
import org.jcnc.snow.compiler.parser.core.ParserEngine;
|
||||
import org.jcnc.snow.compiler.parser.ast.ModuleNode;
|
||||
import org.jcnc.snow.compiler.parser.context.ParserContext;
|
||||
import org.jcnc.snow.compiler.parser.ast.base.Node;
|
||||
import org.jcnc.snow.compiler.parser.function.ASTPrinter;
|
||||
import org.jcnc.snow.compiler.semantic.core.SemanticAnalyzer;
|
||||
import org.jcnc.snow.compiler.semantic.core.SemanticAnalyzerRunner;
|
||||
import org.jcnc.snow.compiler.semantic.error.SemanticError;
|
||||
import org.jcnc.snow.compiler.semantic.utils.SemanticAnalysisReporter;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.nio.file.Files;
|
||||
import java.nio.file.Path;
|
||||
import java.util.ArrayList;
|
||||
import java.util.List;
|
||||
import java.util.stream.Collectors;
|
||||
|
||||
public class Main {
|
||||
public class SnowCompiler {
|
||||
public static void main(String[] args) throws IOException {
|
||||
// 读取源文件
|
||||
String source = Files.readString(Path.of(args[0]), StandardCharsets.UTF_8);
|
||||
@ -1,5 +1,6 @@
|
||||
package org.jcnc.snow.compiler.lexer;
|
||||
package org.jcnc.snow.compiler.lexer.base;
|
||||
|
||||
import org.jcnc.snow.compiler.lexer.core.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.token.Token;
|
||||
|
||||
import java.util.List;
|
||||
@ -1,10 +1,12 @@
|
||||
package org.jcnc.snow.compiler.lexer;
|
||||
package org.jcnc.snow.compiler.lexer.core;
|
||||
|
||||
import org.jcnc.snow.compiler.lexer.base.TokenScanner;
|
||||
|
||||
/**
|
||||
* {@code LexerContext} 是词法分析中的状态管理器，负责追踪当前字符位置、
|
||||
* 行号、列号，并提供字符读取、匹配等功能。
|
||||
* <p>
|
||||
* 它是 {@link LexerEngine} 和 {@link org.jcnc.snow.compiler.lexer.TokenScanner}
|
||||
* 它是 {@link LexerEngine} 和 {@link TokenScanner}
|
||||
* 之间共享的上下文对象，用于读取字符并记录位置信息。
|
||||
*/
|
||||
public class LexerContext {
|
||||
@ -1,5 +1,6 @@
|
||||
package org.jcnc.snow.compiler.lexer;
|
||||
package org.jcnc.snow.compiler.lexer.core;
|
||||
|
||||
import org.jcnc.snow.compiler.lexer.base.TokenScanner;
|
||||
import org.jcnc.snow.compiler.lexer.scanners.*;
|
||||
import org.jcnc.snow.compiler.lexer.token.Token;
|
||||
|
||||
@ -1,42 +1,51 @@
|
||||
# Snow Compiler - Lexer 模块
|
||||
|
||||
🎯 这是 `Snow Compiler` 项目的词法分析模块，负责将源代码解析为一系列结构化的 Token，为后续的语法分析（Parser）或解释器（Interpreter）做准备。
|
||||
> Snow 编译器的前端模块 —— 负责将源代码扫描并生成 Token 流
|
||||
|
||||
---
|
||||
## 项目简介
|
||||
|
||||
## 🧠 核心模块职责
|
||||
**Lexer** 是 [Snow 编译器]() 项目的子模块，承担编译器前端的词法分析阶段任务。
|
||||
它负责将源代码输入，根据 Snow 语言的语法规则，识别并划分为有意义的 Token 流，为后续语法解析（Parser）提供标准输入。
|
||||
|
||||
| 模块 | 说明 |
|
||||
|----------------------|-----------------------------------------------------|
|
||||
| `LexerEngine` | 主引擎，接收字符流，分发给各个 `TokenScanner` 处理 |
|
||||
| `LexerContext` | 封装源码字符流和当前扫描状态（如 `peek()`、`advance()`） |
|
||||
| `TokenScanner` | 扫描器接口，所有扫描器需实现该接口进行识别与处理 |
|
||||
| `scanners/` | 各类扫描器实现 |
|
||||
| `token/` | Token 结构、类型定义、工厂方法 |
|
||||
| `utils/TokenPrinter` | Token 输出辅助类，格式化打印 Token 序列 |
|
||||
该模块采用模块化设计，每类 Token 类型（如标识符、运算符、数字、字符串等）由独立的扫描器（Scanner）负责识别，提高了扩展性和可维护性。
|
||||
|
||||
---
|
||||
## 核心功能
|
||||
|
||||
## 🔍 支持的 Token 类型
|
||||
- **词法分析引擎**：从源代码提取标准化 Token 流
|
||||
- **模块化扫描器体系**：按需扩展不同类型的 Token 识别
|
||||
- **灵活的上下文管理**：跟踪源代码位置，支持错误处理
|
||||
- **统一的 Token 工厂**：集中创建 Token 实例
|
||||
- **工具支持**：Token 打印与调试辅助
|
||||
|
||||
- 标识符（变量名、函数名）
|
||||
- 数字（整数、小数）
|
||||
- 字符串（支持转义）
|
||||
- 注释（单行、多行）
|
||||
- 运算符（==, !=, &&, ||, <, >= 等）
|
||||
- 符号（: , . + - * ( )）
|
||||
- 换行符
|
||||
- 空白符（自动跳过）
|
||||
- 未知字符（捕获非法或暂不支持的符号）
|
||||
## 模块结构
|
||||
|
||||
---
|
||||
```
|
||||
lexer/
|
||||
├── base/ // 公共基础接口
|
||||
├── core/ // 词法分析核心引擎与上下文
|
||||
├── scanners/ // 各类 Token 扫描器
|
||||
├── token/ // Token 定义、工厂与类型
|
||||
├── utils/ // 辅助工具（如 Token 打印）
|
||||
└── doc/ // 项目文档
|
||||
```
|
||||
|
||||
## 🚀 示例：使用 LexerEngine 分析源码
|
||||
## 快速上手
|
||||
|
||||
```java
|
||||
String code = "let x = 42;\nprint(\"hello\")";
|
||||
LexerEngine lexer = new LexerEngine();
|
||||
List<Token> tokens = lexer.tokenize(code);
|
||||
```
|
||||
// 1. 创建词法分析引擎实例
|
||||
LexerEngine engine = new LexerEngine();
|
||||
|
||||
// 输出 token 流
|
||||
// 2. 提供源代码输入
|
||||
String sourceCode = "let x = 5 + 3;";
|
||||
|
||||
// 3. 执行分析，生成 Token 流
|
||||
List<Token> tokens = engine.tokenize(sourceCode);
|
||||
|
||||
// 4. 可选：打印 Token 列表，便于调试
|
||||
TokenPrinter.print(tokens);
|
||||
```
|
||||
|
||||
## 开发环境
|
||||
|
||||
- JDK 21 或更高版本
|
||||
- 建议使用 Maven 进行构建管理
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
package org.jcnc.snow.compiler.lexer.scanners;
|
||||
|
||||
import org.jcnc.snow.compiler.lexer.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.TokenScanner;
|
||||
import org.jcnc.snow.compiler.lexer.core.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.base.TokenScanner;
|
||||
import org.jcnc.snow.compiler.lexer.token.Token;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
package org.jcnc.snow.compiler.lexer.scanners;
|
||||
|
||||
import org.jcnc.snow.compiler.lexer.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.core.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.token.Token;
|
||||
import org.jcnc.snow.compiler.lexer.token.TokenType;
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
package org.jcnc.snow.compiler.lexer.scanners;
|
||||
|
||||
import org.jcnc.snow.compiler.lexer.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.core.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.token.Token;
|
||||
import org.jcnc.snow.compiler.lexer.token.TokenFactory;
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
package org.jcnc.snow.compiler.lexer.scanners;
|
||||
|
||||
import org.jcnc.snow.compiler.lexer.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.core.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.token.Token;
|
||||
import org.jcnc.snow.compiler.lexer.token.TokenType;
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
package org.jcnc.snow.compiler.lexer.scanners;
|
||||
|
||||
import org.jcnc.snow.compiler.lexer.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.core.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.token.Token;
|
||||
import org.jcnc.snow.compiler.lexer.token.TokenType;
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
package org.jcnc.snow.compiler.lexer.scanners;
|
||||
|
||||
import org.jcnc.snow.compiler.lexer.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.core.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.token.Token;
|
||||
import org.jcnc.snow.compiler.lexer.token.TokenType;
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
package org.jcnc.snow.compiler.lexer.scanners;
|
||||
|
||||
import org.jcnc.snow.compiler.lexer.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.core.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.token.Token;
|
||||
import org.jcnc.snow.compiler.lexer.token.TokenType;
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
package org.jcnc.snow.compiler.lexer.scanners;
|
||||
|
||||
import org.jcnc.snow.compiler.lexer.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.core.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.token.Token;
|
||||
import org.jcnc.snow.compiler.lexer.token.TokenType;
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
package org.jcnc.snow.compiler.lexer.scanners;
|
||||
|
||||
import org.jcnc.snow.compiler.lexer.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.core.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.token.Token;
|
||||
import org.jcnc.snow.compiler.lexer.token.TokenType;
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
package org.jcnc.snow.compiler.lexer.scanners;
|
||||
|
||||
import org.jcnc.snow.compiler.lexer.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.core.LexerContext;
|
||||
import org.jcnc.snow.compiler.lexer.token.Token;
|
||||
|
||||
/**
|
||||
|
||||
59
src/main/java/org/jcnc/snow/compiler/parser/doc/README.md
Normal file
59
src/main/java/org/jcnc/snow/compiler/parser/doc/README.md
Normal file
@ -0,0 +1,59 @@
|
||||
# Snow Compiler - Parser 模块
|
||||
|
||||
> Snow 编译器的前端模块 —— 负责将 Token 流解析为抽象语法树（AST）
|
||||
|
||||
## 项目简介
|
||||
|
||||
**Parser** 是 [Snow 编译器]() 项目的子模块，承担编译器前端的解析阶段任务。
|
||||
它负责将词法分析得到的 Token 流，按照 Snow 语言的语法规则，解析为标准的抽象语法树（AST）。
|
||||
|
||||
框架使用了 Pratt 解析算法处理表达式，同时采用模块化设计，支持声明、函数、条件语句、循环语句等各类结构的解析。
|
||||
|
||||
## 核心功能
|
||||
|
||||
- **抽象语法树（AST）生成**：定义丰富的 AST 节点类型
|
||||
- **表达式解析器**：基于 Pratt 解析，支持优先级、调用、成员访问等
|
||||
- **语句解析器**：支持 Snow 语言中的声明、控制流等
|
||||
- **模块解析器**：处理 `import` 导入声明
|
||||
- **函数解析器**：支持函数定义与调用
|
||||
- **灵活的解析上下文管理**：错误处理与流式 Token 管理
|
||||
- **工具支持**：AST JSON 序列化，便于调试与前后端通信
|
||||
|
||||
## 模块结构
|
||||
|
||||
```
|
||||
parser/
|
||||
├── ast/ // AST 节点定义
|
||||
├── base/ // 顶层解析器接口
|
||||
├── context/ // 解析上下文与异常处理
|
||||
├── core/ // 核心解析引擎
|
||||
├── expression/ // 表达式解析模块
|
||||
├── factory/ // 解析器工厂
|
||||
├── function/ // 函数解析及 AST 打印
|
||||
├── module/ // 模块导入解析
|
||||
├── statement/ // 各类语句解析器
|
||||
└── utils/ // JSON 序列化、辅助方法
|
||||
```
|
||||
|
||||
## 快速上手
|
||||
|
||||
```
|
||||
// 1. 创建解析引擎实例
|
||||
ParserEngine engine = new ParserEngine();
|
||||
|
||||
// 2. 准备 Token 流（通常由词法分析器生成）
|
||||
TokenStream tokenStream = ...;
|
||||
|
||||
// 3. 执行解析，生成 AST
|
||||
ModuleNode ast = engine.parse(tokenStream);
|
||||
|
||||
// 4. 可选：将 AST 序列化为 JSON 格式，便于调试
|
||||
String astJson = ASTJsonSerializer.serialize(ast);
|
||||
System.out.println(astJson);
|
||||
```
|
||||
|
||||
## 开发环境
|
||||
|
||||
- JDK 21 或更高版本
|
||||
- 建议使用 Maven 进行构建管理
|
||||
|
||||
56
src/main/java/org/jcnc/snow/compiler/semantic/doc/README.md
Normal file
56
src/main/java/org/jcnc/snow/compiler/semantic/doc/README.md
Normal file
@ -0,0 +1,56 @@
|
||||
# Snow Compiler - Semantic 模块
|
||||
|
||||
> Snow 编译器的前端模块 —— 负责语义分析与符号表管理
|
||||
|
||||
## 项目简介
|
||||
|
||||
**Semantic** 是 [Snow 编译器]() 项目的子模块，承担编译器前端的语义分析阶段任务。
|
||||
它负责在抽象语法树（AST）基础上，进行符号绑定、类型检查、作用域管理等操作，确保程序符合语义规则，并为后续中间代码生成（IR）阶段提供准备。
|
||||
|
||||
该模块采用模块化设计，针对不同类型的表达式与语句提供独立的分析器，同时内置完整的符号表和类型系统支持。
|
||||
|
||||
## 核心功能
|
||||
|
||||
- **表达式与语句语义分析**：根据 Snow 语言规范校验各类 AST 节点
|
||||
- **符号表管理**：支持作用域嵌套、符号绑定与查找
|
||||
- **类型系统**：内建基础类型与函数类型推导
|
||||
- **语义错误报告**：标准化错误收集与输出
|
||||
- **可扩展的分析器体系**：按节点类型组织，便于维护与扩展
|
||||
|
||||
## 模块结构
|
||||
|
||||
```
|
||||
semantic/
|
||||
├── analyzers/ // 各类表达式和语句分析器
|
||||
│ ├── base/ // 基础分析器接口
|
||||
│ ├── expression/ // 表达式分析器
|
||||
│ └── statement/ // 语句分析器
|
||||
├── core/ // 核心分析引擎与上下文管理
|
||||
├── error/ // 语义错误定义
|
||||
├── symbol/ // 符号表系统
|
||||
├── type/ // 类型系统
|
||||
└── utils/ // 辅助工具
|
||||
```
|
||||
|
||||
## 快速上手
|
||||
|
||||
```
|
||||
// 1. 创建语义分析引擎实例
|
||||
SemanticAnalyzerRunner runner = new SemanticAnalyzerRunner();
|
||||
|
||||
// 2. 准备待分析的 AST（通常由 Parser 生成）
|
||||
ModuleNode ast = ...;
|
||||
|
||||
// 3. 执行语义分析
|
||||
runner.analyze(ast);
|
||||
|
||||
// 4. 可选：检查并输出语义分析报告
|
||||
SemanticAnalysisReporter.report(runner.getErrors());
|
||||
```
|
||||
|
||||
## 开发环境
|
||||
|
||||
- JDK 21 或更高版本
|
||||
- 建议使用 Maven 进行构建管理
|
||||
|
||||
---
|
||||
Loading…
x
Reference in New Issue
Block a user