From c0d47ae3ef3f50abea210a5355b7d7409365fd2b Mon Sep 17 00:00:00 2001 From: Luke Date: Sun, 11 May 2025 23:11:10 +0800 Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=E6=B3=A8=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../compiler/ir/builder/FunctionBuilder.java | 4 +- .../compiler/ir/builder/IRBuilderScope.java | 48 +++++++++------- .../snow/compiler/ir/builder/IRContext.java | 57 ++++++++++--------- .../compiler/ir/builder/IRProgramBuilder.java | 54 ++++++++++-------- .../ir/builder/InstructionFactory.java | 2 +- 5 files changed, 90 insertions(+), 75 deletions(-) diff --git a/src/main/java/org/jcnc/snow/compiler/ir/builder/FunctionBuilder.java b/src/main/java/org/jcnc/snow/compiler/ir/builder/FunctionBuilder.java index 4125d0b..e909c7b 100644 --- a/src/main/java/org/jcnc/snow/compiler/ir/builder/FunctionBuilder.java +++ b/src/main/java/org/jcnc/snow/compiler/ir/builder/FunctionBuilder.java @@ -8,8 +8,8 @@ import org.jcnc.snow.compiler.parser.ast.base.StatementNode; /** * FunctionBuilder 负责将 AST 中的 FunctionNode 构建为可执行的 IRFunction。 - * - *

构建流程： + *

+ * 构建流程： *

    *
  1. 创建 IRFunction 实例并初始化 IRContext；
    2. *
  2. 将函数签名中的参数声明为虚拟寄存器；
    3. diff --git a/src/main/java/org/jcnc/snow/compiler/ir/builder/IRBuilderScope.java b/src/main/java/org/jcnc/snow/compiler/ir/builder/IRBuilderScope.java index 70ab332..168eac2 100644 --- a/src/main/java/org/jcnc/snow/compiler/ir/builder/IRBuilderScope.java +++ b/src/main/java/org/jcnc/snow/compiler/ir/builder/IRBuilderScope.java @@ -7,38 +7,43 @@ import java.util.HashMap; import java.util.Map; /** - * IRBuilderScope 用于管理单个函数的变量名与虚拟寄存器的映射。 + * IRBuilderScope 用于管理单个函数内变量名与虚拟寄存器的映射关系。 * - *

    功能： + *

    主要功能包括： *

    */ final class IRBuilderScope { - /** 存储变量名到 IRVirtualRegister 的映射 */ + /** + * 存储变量名到对应 IRVirtualRegister 的映射。 + * 变量名为键，虚拟寄存器对象为值，用于查找和更新。 + */ private final Map 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); diff --git a/src/main/java/org/jcnc/snow/compiler/ir/builder/IRContext.java b/src/main/java/org/jcnc/snow/compiler/ir/builder/IRContext.java index 3d5edc4..601b73e 100644 --- a/src/main/java/org/jcnc/snow/compiler/ir/builder/IRContext.java +++ b/src/main/java/org/jcnc/snow/compiler/ir/builder/IRContext.java @@ -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 指令添加操作。 * - *

    主要功能： + *

    本类提供以下核心功能： *

      - *
    • 持有正在构建的 IRFunction 对象；
      • - *
    • 管理变量名到虚拟寄存器的映射作用域；
      • - *
    • 分配新的虚拟寄存器；
      • - *
    • 将生成的 IRInstruction 自动添加到 IRFunction。
      • + *
    • 持有并操作当前 IRFunction 对象；
      • + *
    • 管理变量名与虚拟寄存器的映射关系；
      • + *
    • 分配新的虚拟寄存器实例；
      • + *
    • 将生成的 IRInstruction 自动添加到 IRFunction 中；
      • *
    */ 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 + *

    包内可见：仅限 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); diff --git a/src/main/java/org/jcnc/snow/compiler/ir/builder/IRProgramBuilder.java b/src/main/java/org/jcnc/snow/compiler/ir/builder/IRProgramBuilder.java index 27a9267..a1168ec 100644 --- a/src/main/java/org/jcnc/snow/compiler/ir/builder/IRProgramBuilder.java +++ b/src/main/java/org/jcnc/snow/compiler/ir/builder/IRProgramBuilder.java @@ -10,66 +10,70 @@ import org.jcnc.snow.compiler.parser.ast.base.StatementNode; import java.util.List; /** - * IRProgramBuilder 用于将 AST 根节点列表构建为 IRProgram。 + * 本类负责将解析生成的 AST 根节点列表转换为可执行的 IRProgram。 * - *

    功能： + *

    主要职责： *

      - *
    • 遍历顶层节点，识别模块、函数或顶层语句；
      • - *
    • 将函数节点转换为 IRFunction 并添加到 IRProgram；
      • - *
    • 对脚本式顶层语句自动包装为特殊的 _start 函数。
      • + *
    • 遍历输入的顶层节点，识别 ModuleNode、FunctionNode 及脚本式顶层 StatementNode；
      • + *
    • 对 ModuleNode 中的所有函数节点调用 FunctionBuilder 构建 IRFunction 并添加至 IRProgram；
      • + *
    • 对单独的 FunctionNode 节点直接构建并纳入 IRProgram；
      • + *
    • 对顶层脚本式 StatementNode 自动封装为名称固定的“_start”函数，再行构建并纳入 IRProgram；
      • + *
    • 对不支持的节点类型抛出 IllegalStateException，以确保编译流程严谨。
      • *
    */ 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 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”函数节点。 * - *

    构造参数说明： + *

    封装规则： *

      - *
    • 函数名固定为 "_start"；
      • - *
    • 返回类型设为 null，表示类型推断或默认处理；
      • + *
    • 函数名固定为“_start”；
      • + *
    • 返回类型设为 null，由后续流程处理；
      • *
    • 参数列表为空；
      • - *
    • 函数体仅包含给定的单条语句。
      • + *
    • 函数主体仅包含传入的单条语句。
      • *
    * - * @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)); diff --git a/src/main/java/org/jcnc/snow/compiler/ir/builder/InstructionFactory.java b/src/main/java/org/jcnc/snow/compiler/ir/builder/InstructionFactory.java index f303f12..8e4611d 100644 --- a/src/main/java/org/jcnc/snow/compiler/ir/builder/InstructionFactory.java +++ b/src/main/java/org/jcnc/snow/compiler/ir/builder/InstructionFactory.java @@ -10,7 +10,7 @@ import org.jcnc.snow.compiler.ir.value.IRVirtualRegister; /** * InstructionFactory 统一管理 IR 指令的创建，并自动将生成的指令添加到上下文中。 * - *

    提供的功能包括： + *

    主要功能包括： *

      *
    • 生成加载常量指令（LoadConstInstruction）；
      • *
    • 生成二元运算指令（BinaryOperationInstruction）；