增加注释
This commit is contained in:
parent
965b1a1add
commit
c0d47ae3ef
@ -8,8 +8,8 @@ import org.jcnc.snow.compiler.parser.ast.base.StatementNode;
|
||||
|
||||
/**
|
||||
* FunctionBuilder 负责将 AST 中的 FunctionNode 构建为可执行的 IRFunction。
|
||||
*
|
||||
* <p>构建流程：
|
||||
* <p>
|
||||
* 构建流程：
|
||||
* <ol>
|
||||
* <li>创建 IRFunction 实例并初始化 IRContext；</li>
|
||||
* <li>将函数签名中的参数声明为虚拟寄存器；</li>
|
||||
|
||||
@ -7,38 +7,43 @@ import java.util.HashMap;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* IRBuilderScope 用于管理单个函数的变量名与虚拟寄存器的映射。
|
||||
* IRBuilderScope 用于管理单个函数内变量名与虚拟寄存器的映射关系。
|
||||
*
|
||||
* <p>功能：
|
||||
* <p>主要功能包括：
|
||||
* <ul>
|
||||
* <li>维护变量声明后的寄存器分配；</li>
|
||||
* <li>支持将已有寄存器与变量重新绑定；</li>
|
||||
* <li>根据变量名查找对应的虚拟寄存器。</li>
|
||||
* <li>维护在当前作用域中已声明变量的寄存器分配信息；</li>
|
||||
* <li>支持将已有虚拟寄存器与变量名重新绑定；</li>
|
||||
* <li>根据变量名查找对应的虚拟寄存器实例。</li>
|
||||
* </ul>
|
||||
*/
|
||||
final class IRBuilderScope {
|
||||
|
||||
/** 存储变量名到 IRVirtualRegister 的映射 */
|
||||
/**
|
||||
* 存储变量名到对应 IRVirtualRegister 的映射。
|
||||
* 变量名为键，虚拟寄存器对象为值，用于查找和更新。
|
||||
*/
|
||||
private final Map<String, IRVirtualRegister> vars = new HashMap<>();
|
||||
|
||||
/**
|
||||
* 当前作用域所属的 IRFunction，用于分配新的寄存器。
|
||||
* 当前作用域所绑定的 IRFunction 对象，用于申请新的虚拟寄存器。
|
||||
*/
|
||||
private IRFunction fn;
|
||||
|
||||
/**
|
||||
* 关联一个 IRFunction 到当前作用域，用于后续寄存器分配。
|
||||
* 将指定的 IRFunction 关联到当前作用域，以便后续声明变量时能够
|
||||
* 调用该函数的 newRegister() 方法生成新的寄存器。
|
||||
*
|
||||
* @param fn 要绑定的 IRFunction 实例
|
||||
* @param fn 要绑定到本作用域的 IRFunction 实例
|
||||
*/
|
||||
void attachFunction(IRFunction fn) {
|
||||
this.fn = fn;
|
||||
}
|
||||
|
||||
/**
|
||||
* 声明一个新变量，并为其分配一个新的虚拟寄存器。
|
||||
* 在当前作用域中声明一个新变量，并为其分配一个新的虚拟寄存器。
|
||||
* 调用绑定的 IRFunction.newRegister() 生成寄存器后保存到映射表中。
|
||||
*
|
||||
* @param name 变量名
|
||||
* @param name 变量名称，作为映射键使用
|
||||
*/
|
||||
void declare(String name) {
|
||||
IRVirtualRegister reg = fn.newRegister();
|
||||
@ -46,30 +51,33 @@ final class IRBuilderScope {
|
||||
}
|
||||
|
||||
/**
|
||||
* 声明或导入一个已有寄存器到当前作用域。
|
||||
* 在当前作用域中声明或导入一个已有的虚拟寄存器，并将其与指定变量名绑定。
|
||||
* 该方法可用于将外部或前一作用域的寄存器导入到本作用域。
|
||||
*
|
||||
* @param name 变量名
|
||||
* @param reg 对应的虚拟寄存器
|
||||
* @param name 变量名称，作为映射键使用
|
||||
* @param reg 要绑定到该名称的 IRVirtualRegister 实例
|
||||
*/
|
||||
void declare(String name, IRVirtualRegister reg) {
|
||||
vars.put(name, reg);
|
||||
}
|
||||
|
||||
/**
|
||||
* 更新已声明变量对应的虚拟寄存器。
|
||||
* 更新已存在变量的虚拟寄存器绑定关系。若变量已声明，则替换其对应的寄存器；
|
||||
* 若尚未声明，则等同于声明新变量。
|
||||
*
|
||||
* @param name 变量名
|
||||
* @param reg 新的虚拟寄存器
|
||||
* @param name 变量名称，作为映射键使用
|
||||
* @param reg 新的 IRVirtualRegister 实例，用于替换旧绑定
|
||||
*/
|
||||
void put(String name, IRVirtualRegister reg) {
|
||||
vars.put(name, reg);
|
||||
}
|
||||
|
||||
/**
|
||||
* 根据变量名查找其对应的虚拟寄存器。
|
||||
* 根据变量名称在当前作用域中查找对应的虚拟寄存器。
|
||||
*
|
||||
* @param name 变量名
|
||||
* @return 对应的 IRVirtualRegister，若未声明则返回 null
|
||||
* @param name 需要查询的变量名称
|
||||
* @return 如果该名称已绑定寄存器，则返回对应的 IRVirtualRegister；
|
||||
* 如果未声明，则返回 null
|
||||
*/
|
||||
IRVirtualRegister lookup(String name) {
|
||||
return vars.get(name);
|
||||
|
||||
@ -5,71 +5,74 @@ import org.jcnc.snow.compiler.ir.core.IRInstruction;
|
||||
import org.jcnc.snow.compiler.ir.value.IRVirtualRegister;
|
||||
|
||||
/**
|
||||
* IRContext 封装了当前函数的 IRFunction 实例和作用域管理（IRBuilderScope），
|
||||
* 并提供分配寄存器和添加 IR 指令的便利方法。
|
||||
* IRContext 类负责封装当前正在构建的 IRFunction 实例
|
||||
* 以及与之配套的作用域管理（IRBuilderScope），
|
||||
* 并简化虚拟寄存器分配与 IR 指令添加操作。
|
||||
*
|
||||
* <p>主要功能：
|
||||
* <p>本类提供以下核心功能：
|
||||
* <ul>
|
||||
* <li>持有正在构建的 IRFunction 对象；</li>
|
||||
* <li>管理变量名到虚拟寄存器的映射作用域；</li>
|
||||
* <li>分配新的虚拟寄存器；</li>
|
||||
* <li>将生成的 IRInstruction 自动添加到 IRFunction。</li>
|
||||
* <li>持有并操作当前 IRFunction 对象；</li>
|
||||
* <li>管理变量名与虚拟寄存器的映射关系；</li>
|
||||
* <li>分配新的虚拟寄存器实例；</li>
|
||||
* <li>将生成的 IRInstruction 自动添加到 IRFunction 中；</li>
|
||||
* </ul>
|
||||
*/
|
||||
public class IRContext {
|
||||
/**
|
||||
* 正在构建的 IRFunction 对象
|
||||
* 当前正在构建的 IRFunction 对象，所有指令将添加至此
|
||||
*/
|
||||
private final IRFunction function;
|
||||
/**
|
||||
* 管理变量和寄存器映射的作用域
|
||||
*/
|
||||
private final IRBuilderScope IRBuilderScope;
|
||||
|
||||
/**
|
||||
* 构造 IRContext，并绑定要构建的 IRFunction。
|
||||
* 用于管理当前函数作用域内变量与虚拟寄存器的映射
|
||||
*/
|
||||
private final IRBuilderScope scope;
|
||||
|
||||
/**
|
||||
* 构造一个新的 IRContext，并将指定的 IRFunction 与作用域关联。
|
||||
*
|
||||
* @param function 要构建的 IRFunction 对象
|
||||
* @param function 要构建的 IRFunction 实例
|
||||
*/
|
||||
public IRContext(IRFunction function) {
|
||||
this.function = function;
|
||||
this.IRBuilderScope = new IRBuilderScope();
|
||||
// 将 IRFunction 与作用域关联，以便指令生成时使用
|
||||
this.IRBuilderScope.attachFunction(function);
|
||||
this.scope = new IRBuilderScope();
|
||||
// 关联作用域与 IRFunction，以便在声明变量时申请寄存器
|
||||
this.scope.attachFunction(function);
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取当前 IRFunction。
|
||||
* 获取当前正在构建的 IRFunction 对象。
|
||||
*
|
||||
* @return 当前正在构建的 IRFunction 对象
|
||||
* @return 当前 IRFunction 实例
|
||||
*/
|
||||
public IRFunction getFunction() {
|
||||
return function;
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取当前作用域，用于变量声明和查找。
|
||||
* 获取当前函数的变量与寄存器映射作用域。
|
||||
*
|
||||
* @return 作用域对象 IRBuilderScope
|
||||
* <p>包内可见：仅限 builder 包内部使用。
|
||||
*
|
||||
* @return IRBuilderScope 实例
|
||||
*/
|
||||
/* 包内可见：仅在 builder 包内部使用 IRBuilderScope */
|
||||
IRBuilderScope getScope() {
|
||||
return IRBuilderScope;
|
||||
return scope;
|
||||
}
|
||||
|
||||
/**
|
||||
* 分配一个新的虚拟寄存器。
|
||||
* 为当前函数分配一个新的虚拟寄存器。
|
||||
*
|
||||
* @return 新分配的 IRVirtualRegister 对象
|
||||
* @return 分配到的 IRVirtualRegister 对象
|
||||
*/
|
||||
public IRVirtualRegister newRegister() {
|
||||
return function.newRegister();
|
||||
}
|
||||
|
||||
/**
|
||||
* 将给定的 IRInstruction 添加到 IRFunction 中。
|
||||
* 将指定的 IRInstruction 添加到当前 IRFunction 的指令列表中。
|
||||
*
|
||||
* @param instr 要添加的 IR 指令
|
||||
* @param instr 要添加的 IRInstruction 实例
|
||||
*/
|
||||
public void addInstruction(IRInstruction instr) {
|
||||
function.add(instr);
|
||||
|
||||
@ -10,66 +10,70 @@ import org.jcnc.snow.compiler.parser.ast.base.StatementNode;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* IRProgramBuilder 用于将 AST 根节点列表构建为 IRProgram。
|
||||
* 本类负责将解析生成的 AST 根节点列表转换为可执行的 IRProgram。
|
||||
*
|
||||
* <p>功能：
|
||||
* <p>主要职责：
|
||||
* <ul>
|
||||
* <li>遍历顶层节点，识别模块、函数或顶层语句；</li>
|
||||
* <li>将函数节点转换为 IRFunction 并添加到 IRProgram；</li>
|
||||
* <li>对脚本式顶层语句自动包装为特殊的 _start 函数。</li>
|
||||
* <li>遍历输入的顶层节点，识别 ModuleNode、FunctionNode 及脚本式顶层 StatementNode；</li>
|
||||
* <li>对 ModuleNode 中的所有函数节点调用 FunctionBuilder 构建 IRFunction 并添加至 IRProgram；</li>
|
||||
* <li>对单独的 FunctionNode 节点直接构建并纳入 IRProgram；</li>
|
||||
* <li>对顶层脚本式 StatementNode 自动封装为名称固定的“_start”函数，再行构建并纳入 IRProgram；</li>
|
||||
* <li>对不支持的节点类型抛出 IllegalStateException，以确保编译流程严谨。</li>
|
||||
* </ul>
|
||||
*/
|
||||
public final class IRProgramBuilder {
|
||||
|
||||
/**
|
||||
* 构建一个完整的 IRProgram。
|
||||
* 构建完整的 IRProgram 实例。
|
||||
*
|
||||
* @param roots AST 根节点列表，可包含 ModuleNode、FunctionNode 或 StatementNode
|
||||
* @return 构建好的 IRProgram 实例
|
||||
* @throws IllegalStateException 当遇到不支持的顶层节点时抛出
|
||||
* @param roots 含 ModuleNode、FunctionNode 或 StatementNode 的顶层 AST 根节点列表
|
||||
* @return 包含所有转换后 IRFunction 的 IRProgram 对象
|
||||
* @throws IllegalStateException 遇到不支持的顶层节点类型时抛出
|
||||
*/
|
||||
public IRProgram buildProgram(List<Node> roots) {
|
||||
IRProgram irProgram = new IRProgram();
|
||||
for (Node node : roots) {
|
||||
switch (node) {
|
||||
case ModuleNode moduleNode ->
|
||||
// 模块节点：将模块内的所有函数加入程序
|
||||
// 模块节点：批量构建并添加模块内所有函数
|
||||
moduleNode.functions().forEach(f -> irProgram.add(buildFunction(f)));
|
||||
case FunctionNode f ->
|
||||
// 顶层函数节点
|
||||
irProgram.add(buildFunction(f));
|
||||
case FunctionNode functionNode ->
|
||||
// 顶层函数节点：直接构建并添加
|
||||
irProgram.add(buildFunction(functionNode));
|
||||
case StatementNode statementNode ->
|
||||
// 顶层脚本语句，包装为 _start 函数
|
||||
// 脚本式顶层语句：封装为“_start”函数后构建并添加
|
||||
irProgram.add(buildFunction(wrapTopLevel(statementNode)));
|
||||
case null, default -> throw new IllegalStateException("Unsupported top-level node: " + node);
|
||||
default ->
|
||||
// 严格校验节点类型，遇不支持者立即失败
|
||||
throw new IllegalStateException("Unsupported top-level node: " + node);
|
||||
}
|
||||
}
|
||||
return irProgram;
|
||||
}
|
||||
|
||||
/**
|
||||
* 使用 FunctionBuilder 构建 IRFunction。
|
||||
* 利用 FunctionBuilder 将 FunctionNode 转换为 IRFunction。
|
||||
*
|
||||
* @param functionNode AST 中的 FunctionNode
|
||||
* @return 构建完成的 IRFunction
|
||||
* @param functionNode 待构建的 AST FunctionNode
|
||||
* @return 构建完成的 IRFunction 实例
|
||||
*/
|
||||
private IRFunction buildFunction(FunctionNode functionNode) {
|
||||
return new FunctionBuilder().build(functionNode);
|
||||
}
|
||||
|
||||
/**
|
||||
* 将顶层脚本式语句包装为名为 _start 的 FunctionNode。
|
||||
* 将单个脚本式顶层 StatementNode 封装为名称固定的“_start”函数节点。
|
||||
*
|
||||
* <p>构造参数说明：
|
||||
* <p>封装规则：
|
||||
* <ul>
|
||||
* <li>函数名固定为 "_start"；</li>
|
||||
* <li>返回类型设为 null，表示类型推断或默认处理；</li>
|
||||
* <li>函数名固定为“_start”；</li>
|
||||
* <li>返回类型设为 null，由后续流程处理；</li>
|
||||
* <li>参数列表为空；</li>
|
||||
* <li>函数体仅包含给定的单条语句。</li>
|
||||
* <li>函数主体仅包含传入的单条语句。</li>
|
||||
* </ul>
|
||||
*
|
||||
* @param stmt 要包装的顶层语句节点
|
||||
* @return 新建的 FunctionNode
|
||||
* @param stmt 待封装的顶层脚本语句节点
|
||||
* @return 生成的 FunctionNode，用于后续 IRFunction 构建
|
||||
*/
|
||||
private FunctionNode wrapTopLevel(StatementNode stmt) {
|
||||
return new FunctionNode("_start", null, String.valueOf(List.of()), List.of(stmt));
|
||||
|
||||
@ -10,7 +10,7 @@ import org.jcnc.snow.compiler.ir.value.IRVirtualRegister;
|
||||
/**
|
||||
* InstructionFactory 统一管理 IR 指令的创建，并自动将生成的指令添加到上下文中。
|
||||
*
|
||||
* <p>提供的功能包括：
|
||||
* <p>主要功能包括：
|
||||
* <ul>
|
||||
* <li>生成加载常量指令（LoadConstInstruction）；</li>
|
||||
* <li>生成二元运算指令（BinaryOperationInstruction）；</li>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user