From 1d52cc12293fb9b63cfddbe74f19f8d71cf9e202 Mon Sep 17 00:00:00 2001 From: Luke Date: Tue, 24 Jun 2025 09:28:09 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20cli=20=E5=91=BD?= =?UTF-8?q?=E4=BB=A4=E7=9A=84=E6=B3=A8=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- src/main/java/module-info.java | 4 ++- .../jcnc/snow/cli/commands/BuildCommand.java | 1 - .../snow/cli/{ => commands}/CLICommand.java | 4 ++- .../jcnc/snow/cli/commands/CleanCommand.java | 1 - .../snow/cli/commands/CompileCommand.java | 35 ++++++++++++++++--- .../jcnc/snow/cli/commands/InitCommand.java | 2 -- .../snow/cli/commands/InstallCommand.java | 1 - .../snow/cli/commands/PublishCommand.java | 1 - .../jcnc/snow/cli/commands/RunCommand.java | 30 ++++++++++++++-- .../snow/cli/commands/VersionCommand.java | 1 - .../org/jcnc/snow/cli/utils/CLIUtils.java | 2 +- 11 files changed, 65 insertions(+), 17 deletions(-) rename src/main/java/org/jcnc/snow/cli/{ => commands}/CLICommand.java (94%) diff --git a/src/main/java/module-info.java b/src/main/java/module-info.java index aa5369c..cf13eb0 100644 --- a/src/main/java/module-info.java +++ b/src/main/java/module-info.java @@ -1,5 +1,7 @@ +import org.jcnc.snow.cli.commands.CLICommand; + module org.jcnc.snow.compiler { - uses org.jcnc.snow.cli.CLICommand; + uses CLICommand; requires java.desktop; requires java.logging; exports org.jcnc.snow.compiler.ir.core; diff --git a/src/main/java/org/jcnc/snow/cli/commands/BuildCommand.java b/src/main/java/org/jcnc/snow/cli/commands/BuildCommand.java index f8b9c45..13019f9 100644 --- a/src/main/java/org/jcnc/snow/cli/commands/BuildCommand.java +++ b/src/main/java/org/jcnc/snow/cli/commands/BuildCommand.java @@ -1,6 +1,5 @@ package org.jcnc.snow.cli.commands; -import org.jcnc.snow.cli.CLICommand; import org.jcnc.snow.pkg.dsl.CloudDSLParser; import org.jcnc.snow.pkg.lifecycle.LifecycleManager; import org.jcnc.snow.pkg.lifecycle.LifecyclePhase; diff --git a/src/main/java/org/jcnc/snow/cli/CLICommand.java b/src/main/java/org/jcnc/snow/cli/commands/CLICommand.java similarity index 94% rename from src/main/java/org/jcnc/snow/cli/CLICommand.java rename to src/main/java/org/jcnc/snow/cli/commands/CLICommand.java index 0874cf1..5001d4d 100644 --- a/src/main/java/org/jcnc/snow/cli/CLICommand.java +++ b/src/main/java/org/jcnc/snow/cli/commands/CLICommand.java @@ -1,4 +1,6 @@ -package org.jcnc.snow.cli; +package org.jcnc.snow.cli.commands; + +import org.jcnc.snow.cli.SnowCLI; /** * 所有 CLI 子命令（如 compile、run 等）都必须实现的命令接口。 diff --git a/src/main/java/org/jcnc/snow/cli/commands/CleanCommand.java b/src/main/java/org/jcnc/snow/cli/commands/CleanCommand.java index 8f42b65..184501e 100644 --- a/src/main/java/org/jcnc/snow/cli/commands/CleanCommand.java +++ b/src/main/java/org/jcnc/snow/cli/commands/CleanCommand.java @@ -1,6 +1,5 @@ package org.jcnc.snow.cli.commands; -import org.jcnc.snow.cli.CLICommand; import org.jcnc.snow.pkg.lifecycle.LifecycleManager; import org.jcnc.snow.pkg.lifecycle.LifecyclePhase; import org.jcnc.snow.pkg.tasks.CleanTask; diff --git a/src/main/java/org/jcnc/snow/cli/commands/CompileCommand.java b/src/main/java/org/jcnc/snow/cli/commands/CompileCommand.java index 6cc11e2..634e27b 100644 --- a/src/main/java/org/jcnc/snow/cli/commands/CompileCommand.java +++ b/src/main/java/org/jcnc/snow/cli/commands/CompileCommand.java @@ -1,6 +1,5 @@ package org.jcnc.snow.cli.commands; -import org.jcnc.snow.cli.CLICommand; import org.jcnc.snow.pkg.dsl.CloudDSLParser; import org.jcnc.snow.pkg.model.Project; import org.jcnc.snow.pkg.tasks.CompileTask; @@ -11,20 +10,40 @@ import java.nio.file.Paths; * CLI 命令：编译当前项目。 *

* 负责读取项目描述文件并委托给 {@link CompileTask}， + * 将 .snow 文件编译为 .water 字节码。 *

+ * + * 
+ * 用法示例：
+ * $ snow compile -o main -d src/
+ * $ snow compile run entry.snow
+ *
*/ public final class CompileCommand implements CLICommand { + /** + * 返回命令名称，用于 CLI 调用。 + * + * @return 命令名称，如 "compile" + */ @Override public String name() { return "compile"; } + /** + * 返回命令简介，用于 CLI 帮助或命令列表展示。 + * + * @return 命令描述字符串 + */ @Override public String description() { return "Compile .snow source files into VM byte-code (.water)."; } + /** + * 打印命令用法信息。 + */ @Override public void printUsage() { System.out.println("Usage:"); @@ -32,14 +51,22 @@ public final class CompileCommand implements CLICommand { System.out.println("Options:"); System.out.println(" run compile then run"); System.out.println(" -o specify output base name (without .water suffix)"); - System.out.println(" -d recursively compile all .snow files in directory"); } + System.out.println(" -d recursively compile all .snow files in directory"); + } + /** + * 执行编译任务。 + * + * @param args CLI 传入的参数数组 + * @return 执行结果码（0 表示成功） + * @throws Exception 执行过程中出现错误时抛出 + */ @Override public int execute(String[] args) throws Exception { - // 解析云项目描述文件（默认为工作目录下的 cloud.snow） + // 解析云项目描述文件（默认为工作目录下的 project.cloud） Project project = CloudDSLParser.parse(Paths.get("project.cloud")); // 委托给 CompileTask 处理核心编译逻辑 new CompileTask(project, args).run(); return 0; } -} \ No newline at end of file +} diff --git a/src/main/java/org/jcnc/snow/cli/commands/InitCommand.java b/src/main/java/org/jcnc/snow/cli/commands/InitCommand.java index 62a80b3..0e600a4 100644 --- a/src/main/java/org/jcnc/snow/cli/commands/InitCommand.java +++ b/src/main/java/org/jcnc/snow/cli/commands/InitCommand.java @@ -1,7 +1,5 @@ package org.jcnc.snow.cli.commands; -import org.jcnc.snow.cli.CLICommand; - import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.Paths; diff --git a/src/main/java/org/jcnc/snow/cli/commands/InstallCommand.java b/src/main/java/org/jcnc/snow/cli/commands/InstallCommand.java index 7cd0a2b..248c1db 100644 --- a/src/main/java/org/jcnc/snow/cli/commands/InstallCommand.java +++ b/src/main/java/org/jcnc/snow/cli/commands/InstallCommand.java @@ -1,6 +1,5 @@ package org.jcnc.snow.cli.commands; -import org.jcnc.snow.cli.CLICommand; import org.jcnc.snow.pkg.dsl.CloudDSLParser; import org.jcnc.snow.pkg.model.Project; import org.jcnc.snow.pkg.resolver.DependencyResolver; diff --git a/src/main/java/org/jcnc/snow/cli/commands/PublishCommand.java b/src/main/java/org/jcnc/snow/cli/commands/PublishCommand.java index 2073f91..64275bf 100644 --- a/src/main/java/org/jcnc/snow/cli/commands/PublishCommand.java +++ b/src/main/java/org/jcnc/snow/cli/commands/PublishCommand.java @@ -1,6 +1,5 @@ package org.jcnc.snow.cli.commands; -import org.jcnc.snow.cli.CLICommand; import org.jcnc.snow.pkg.dsl.CloudDSLParser; import org.jcnc.snow.pkg.lifecycle.LifecycleManager; import org.jcnc.snow.pkg.lifecycle.LifecyclePhase; diff --git a/src/main/java/org/jcnc/snow/cli/commands/RunCommand.java b/src/main/java/org/jcnc/snow/cli/commands/RunCommand.java index c81e6f8..962de82 100644 --- a/src/main/java/org/jcnc/snow/cli/commands/RunCommand.java +++ b/src/main/java/org/jcnc/snow/cli/commands/RunCommand.java @@ -1,7 +1,5 @@ - package org.jcnc.snow.cli.commands; -import org.jcnc.snow.cli.CLICommand; import org.jcnc.snow.pkg.tasks.RunTask; /** @@ -10,32 +8,58 @@ import org.jcnc.snow.pkg.tasks.RunTask; * 仅解析参数并委托给 {@link RunTask}， * 将 VM 运行逻辑下沉至 pkg 层，保持 CLI 无状态、薄封装。 *

+ * + * 
+ * 用法示例：
+ * $ snow run main.water
+ *
*/ public final class RunCommand implements CLICommand { + /** + * 返回命令名称，用于 CLI 调用。 + * + * @return 命令名称，如 "run" + */ @Override public String name() { return "run"; } + /** + * 返回命令简介，用于 CLI 帮助或命令列表展示。 + * + * @return 命令描述字符串 + */ @Override public String description() { return "Run the compiled VM bytecode file (.water)"; } + /** + * 执行运行任务。 + * + * @param args CLI 传入的参数数组 + * @return 执行结果码（0 表示成功，非 0 表示失败） + * @throws Exception 执行过程中出现错误时抛出 + */ @Override public int execute(String[] args) throws Exception { if (args.length == 0) { printUsage(); return 1; } + // 委托给 RunTask 执行字节码运行逻辑 new RunTask(args).run(); return 0; } + /** + * 打印命令用法信息。 + */ @Override public void printUsage() { System.out.println("Usage:"); - System.out.println(" snow run [vm-options]"); + System.out.println(" snow run "); } } diff --git a/src/main/java/org/jcnc/snow/cli/commands/VersionCommand.java b/src/main/java/org/jcnc/snow/cli/commands/VersionCommand.java index c8f3af8..a7627e5 100644 --- a/src/main/java/org/jcnc/snow/cli/commands/VersionCommand.java +++ b/src/main/java/org/jcnc/snow/cli/commands/VersionCommand.java @@ -1,6 +1,5 @@ package org.jcnc.snow.cli.commands; -import org.jcnc.snow.cli.CLICommand; import org.jcnc.snow.cli.SnowCLI; /** diff --git a/src/main/java/org/jcnc/snow/cli/utils/CLIUtils.java b/src/main/java/org/jcnc/snow/cli/utils/CLIUtils.java index 462ead8..02c6766 100644 --- a/src/main/java/org/jcnc/snow/cli/utils/CLIUtils.java +++ b/src/main/java/org/jcnc/snow/cli/utils/CLIUtils.java @@ -1,6 +1,6 @@ package org.jcnc.snow.cli.utils; -import org.jcnc.snow.cli.CLICommand; +import org.jcnc.snow.cli.commands.CLICommand; import java.util.List; import java.util.Map;