imports = new ArrayList<>();
- // 读取第一个模块名
- // 继续读取逗号分隔的模块名
+
+ // 读取第一个模块名，然后继续读取逗号分隔的模块名
do {
String mod = ctx.getTokens()
.expectType(TokenType.IDENTIFIER)
.getLexeme();
imports.add(new ImportNode(mod));
} while (ctx.getTokens().match(","));
- // 消费行尾
+
+ // 消费行尾换行符
ctx.getTokens().expectType(TokenType.NEWLINE);
+
return imports;
}
-}
\ No newline at end of file
+}
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/module/ModuleParser.java b/src/main/java/org/jcnc/snow/compiler/parser/module/ModuleParser.java
index 8a469e2..5a8a018 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/module/ModuleParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/module/ModuleParser.java
@@ -13,12 +13,24 @@ import java.util.ArrayList;
import java.util.List;
/**
- * 解析 module 块：
- * module: NAME NEWLINE
- * (import… | function… )*
- * end module NEWLINE
+ * 模块解析器，用于解析形如 module 块的顶层结构。
+ * 语法示例：
+ * {@code
+ * module: my.module
+ * import: mod1, mod2
+ * function: ...
+ * end module
+ * }
+ * 支持导入语句和多个函数定义，允许中间包含空行。
*/
public class ModuleParser implements TopLevelParser {
+
+ /**
+ * 解析模块定义块，返回 {@link ModuleNode} 表示模块结构。
+ *
+ * @param ctx 解析上下文。
+ * @return 模块节点，包含模块名、导入列表和函数列表。
+ */
@Override
public ModuleNode parse(ParserContext ctx) {
TokenStream ts = ctx.getTokens();
@@ -32,17 +44,18 @@ public class ModuleParser implements TopLevelParser {
ImportParser importParser = new ImportParser();
FunctionParser funcParser = new FunctionParser();
- // 解析导入和函数，支持空行
+ // 解析模块体：包含 import 和 function 语句
while (true) {
// 跳过空行
if (ts.peek().getType() == TokenType.NEWLINE) {
ts.next();
continue;
}
- // 如果遇到 end，跳出循环
+ // 遇到 "end" 表示模块结束
if ("end".equals(ts.peek().getLexeme())) {
break;
}
+
String lex = ts.peek().getLexeme();
if ("import".equals(lex)) {
imports.addAll(importParser.parse(ctx));
@@ -53,9 +66,11 @@ public class ModuleParser implements TopLevelParser {
}
}
+ // 结束模块块结构
ts.expect("end");
ts.expect("module");
ts.expectType(TokenType.NEWLINE);
+
return new ModuleNode(name, imports, functions);
}
}
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/statement/DeclarationStatementParser.java b/src/main/java/org/jcnc/snow/compiler/parser/statement/DeclarationStatementParser.java
index 38e13f6..ce6c816 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/statement/DeclarationStatementParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/statement/DeclarationStatementParser.java
@@ -7,24 +7,47 @@ import org.jcnc.snow.compiler.parser.context.ParserContext;
import org.jcnc.snow.compiler.parser.expression.PrattExpressionParser;
/**
- * 解析 declare 语句： declare name:type (= expr)? NEWLINE
+ * 解析变量声明语句的解析器。
+ * 支持语法格式：
+ * {@code
+ * declare name:type
+ * declare name:type = expression
+ * }
+ * 每条语句必须以换行（NEWLINE）结束。
*/
public class DeclarationStatementParser implements StatementParser {
+
+ /**
+ * 解析一条 declare 声明语句。
+ *
+ * @param ctx 当前解析上下文。
+ * @return 构造好的 {@link DeclarationNode} AST 节点。
+ */
@Override
public DeclarationNode parse(ParserContext ctx) {
ctx.getTokens().expect("declare");
+
+ // 获取变量名
String name = ctx.getTokens()
- .expectType(TokenType.IDENTIFIER)
- .getLexeme();
+ .expectType(TokenType.IDENTIFIER)
+ .getLexeme();
+
ctx.getTokens().expect(":");
+
+ // 获取变量类型
String type = ctx.getTokens()
- .expectType(TokenType.TYPE)
- .getLexeme();
+ .expectType(TokenType.TYPE)
+ .getLexeme();
+
+ // 可选初始化表达式
ExpressionNode init = null;
if (ctx.getTokens().match("=")) {
init = new PrattExpressionParser().parse(ctx);
}
+
+ // 声明语句必须以 NEWLINE 结束
ctx.getTokens().expectType(TokenType.NEWLINE);
+
return new DeclarationNode(name, type, init);
}
}
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/statement/ExpressionStatementParser.java b/src/main/java/org/jcnc/snow/compiler/parser/statement/ExpressionStatementParser.java
index c0fdca6..128b7b9 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/statement/ExpressionStatementParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/statement/ExpressionStatementParser.java
@@ -10,27 +10,38 @@ import org.jcnc.snow.compiler.parser.context.TokenStream;
import org.jcnc.snow.compiler.parser.expression.PrattExpressionParser;
/**
- * 将任意表达式或赋值当作语句：
- * identifier = expr NEWLINE
- * expr NEWLINE
+ * 表达式语句解析器：将赋值表达式或任意表达式作为语句进行解析。
+ * 支持的形式包括：
+ *
+ * identifier = expression
+ * expression
+ *
+ * 两者都必须以换行（NEWLINE）结尾。
*/
public class ExpressionStatementParser implements StatementParser {
+
+ /**
+ * 解析一个表达式语句，可能是赋值语句或普通表达式。
+ *
+ * @param ctx 当前的解析上下文。
+ * @return 表达式语句节点或赋值语句节点。
+ */
@Override
public StatementNode parse(ParserContext ctx) {
TokenStream ts = ctx.getTokens();
- // 先检测赋值语句：IDENTIFIER '=' ...
+ // 检查是否是赋值形式（identifier = expr）
if (ts.peek().getType() == TokenType.IDENTIFIER
&& ts.peek(1).getLexeme().equals("=")) {
- String varName = ts.next().getLexeme(); // consume identifier
- ts.expect("="); // consume '='
+ String varName = ts.next().getLexeme(); // 消费 identifier
+ ts.expect("="); // 消费 '='
ExpressionNode value = new PrattExpressionParser().parse(ctx);
ts.expectType(TokenType.NEWLINE);
return new AssignmentNode(varName, value);
}
- // 否则当作普通表达式语句
+ // 否则解析为普通表达式语句
ExpressionNode expr = new PrattExpressionParser().parse(ctx);
ts.expectType(TokenType.NEWLINE);
return new ExpressionStatementNode(expr);
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/statement/IfStatementParser.java b/src/main/java/org/jcnc/snow/compiler/parser/statement/IfStatementParser.java
index c1e8102..64bf84a 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/statement/IfStatementParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/statement/IfStatementParser.java
@@ -11,23 +11,41 @@ import java.util.ArrayList;
import java.util.List;
/**
- * 解析 if 语句： if expr then NEWLINE stmts end if NEWLINE
+ * if 语句解析器，支持基本格式：
+ * {@code
+ * if condition then
+ * statements...
+ * end if
+ * }
+ * 不支持 else 分支，仅支持 then 分支。
*/
public class IfStatementParser implements StatementParser {
+
+ /**
+ * 解析 if 表达式，并构造 {@link IfNode}。
+ *
+ * @param ctx 当前解析上下文。
+ * @return 表示 if 语句的 AST 节点。
+ */
@Override
public IfNode parse(ParserContext ctx) {
ctx.getTokens().expect("if");
+
+ // 解析条件表达式
var cond = new PrattExpressionParser().parse(ctx);
+
ctx.getTokens().expect("then");
ctx.getTokens().expectType(TokenType.NEWLINE);
+ // 解析 then 分支的语句块
List thenBranch = new ArrayList<>();
while (!ctx.getTokens().peek().getLexeme().equals("end")) {
- thenBranch.add(
- StatementParserFactory.get(ctx.getTokens().peek().getLexeme()).parse(ctx)
- );
+ String keyword = ctx.getTokens().peek().getLexeme();
+ StatementNode stmt = StatementParserFactory.get(keyword).parse(ctx);
+ thenBranch.add(stmt);
}
+ // 匹配 end if 结束语句
ctx.getTokens().expect("end");
ctx.getTokens().expect("if");
ctx.getTokens().expectType(TokenType.NEWLINE);
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/statement/LoopStatementParser.java b/src/main/java/org/jcnc/snow/compiler/parser/statement/LoopStatementParser.java
index 6dff091..fc855b2 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/statement/LoopStatementParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/statement/LoopStatementParser.java
@@ -14,16 +14,29 @@ import java.util.ArrayList;
import java.util.List;
/**
- * 解析 loop 语句：
- * loop: NEWLINE
- * initializer: … NEWLINE
- * condition: … NEWLINE
- * update: … NEWLINE
- * body: … NEWLINE
- * end body NEWLINE
- * end loop NEWLINE
+ * 用于解析 loop 语句块，支持以下结构：
+ * {@code
+ * loop:
+ * initializer:
+ * declare i:int = 0
+ * condition:
+ * i < 10
+ * update:
+ * i = i + 1
+ * body:
+ * ...语句...
+ * end body
+ * end loop
+ * }
*/
public class LoopStatementParser implements StatementParser {
+
+ /**
+ * 解析一个完整的 loop 语句块，返回 {@link LoopNode}。
+ *
+ * @param ctx 当前的解析上下文。
+ * @return 表示 loop 结构的 AST 节点。
+ */
@Override
public LoopNode parse(ParserContext ctx) {
TokenStream ts = ctx.getTokens();
@@ -53,7 +66,7 @@ public class LoopStatementParser implements StatementParser {
ts.expectType(TokenType.NEWLINE);
skipNewlines(ts);
- // update (专用赋值解析):
+ // update:
ts.expect("update");
ts.expect(":");
ts.expectType(TokenType.NEWLINE);
@@ -90,7 +103,11 @@ public class LoopStatementParser implements StatementParser {
return new LoopNode(initializer, condition, update, body);
}
- /** 连续跳过所有空行（NEWLINE） */
+ /**
+ * 跳过连续的 NEWLINE token，用于容错和格式整洁。
+ *
+ * @param ts 当前的 Token 流。
+ */
private void skipNewlines(TokenStream ts) {
while (ts.peek().getType() == TokenType.NEWLINE) {
ts.next();
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/statement/ReturnStatementParser.java b/src/main/java/org/jcnc/snow/compiler/parser/statement/ReturnStatementParser.java
index 5f34b02..286ca36 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/statement/ReturnStatementParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/statement/ReturnStatementParser.java
@@ -7,19 +7,35 @@ import org.jcnc.snow.compiler.parser.context.ParserContext;
import org.jcnc.snow.compiler.parser.expression.PrattExpressionParser;
/**
- * 解析 return 语句： return expr? NEWLINE
+ * 用于解析 return 语句。
+ * 支持有无返回值两种形式：
+ * {@code
+ * return
+ * return expression
+ * }
+ * 语句必须以换行符（NEWLINE）结束。
*/
public class ReturnStatementParser implements StatementParser {
+
+ /**
+ * 解析 return 语句并构建 {@link ReturnNode}。
+ *
+ * @param ctx 当前解析上下文。
+ * @return 表示 return 语句的 AST 节点。
+ */
@Override
public ReturnNode parse(ParserContext ctx) {
ctx.getTokens().expect("return");
+
ExpressionNode expr = null;
- // 如果下一个不是换行，就解析表达式
+
+ // 如果不是换行，说明有返回值
if (ctx.getTokens().peek().getType() != TokenType.NEWLINE) {
expr = new PrattExpressionParser().parse(ctx);
}
- // 用 expectType 来消费真正的 NEWLINE token
+
ctx.getTokens().expectType(TokenType.NEWLINE);
+
return new ReturnNode(expr);
}
}
diff --git a/src/main/java/org/jcnc/snow/compiler/parser/statement/StatementParser.java b/src/main/java/org/jcnc/snow/compiler/parser/statement/StatementParser.java
index 20e6388..cb78a3e 100644
--- a/src/main/java/org/jcnc/snow/compiler/parser/statement/StatementParser.java
+++ b/src/main/java/org/jcnc/snow/compiler/parser/statement/StatementParser.java
@@ -4,8 +4,16 @@ import org.jcnc.snow.compiler.parser.context.ParserContext;
import org.jcnc.snow.compiler.parser.ast.StatementNode;
/**
- * 语句解析器接口。
+ * 语句解析器接口，用于将解析上下文中的 Token 转换为 {@link StatementNode}。
+ * 各类语句（如声明、赋值、条件、循环、返回等）均应实现该接口。
*/
public interface StatementParser {
+
+ /**
+ * 从给定的解析上下文中解析出一个语句节点。
+ *
+ * @param ctx 当前的解析上下文。
+ * @return 表示语句的 AST 节点。
+ */
StatementNode parse(ParserContext ctx);
}