docs: document run: false, error handling and global flags

Author: so1ve

docs/.vitepress/config/en.ts

@@ -2,9 +2,9 @@ import { join } from "node:path";
 
 import { defineConfig } from "vitepress";
 
-import { getPluginNavigation } from "./plugin-navigation";
+import { getNavigation } from "../utils/navigation";
 
-const pluginNavigation = await getPluginNavigation(
+const pluginNavigation = await getNavigation(
 	join(import.meta.dirname, "..", "..", "official-plugins"),
 	"/official-plugins",
 );
@@ -40,18 +40,30 @@ export const enConfig = defineConfig({
 						text: "Commands",
 						link: "/commands",
 					},
-					{
-						text: "Interceptors",
-						link: "/interceptors",
-					},
 					{
 						text: "Context",
 						link: "/context",
 					},
+					{
+						text: "Global Flags",
+						link: "/global-flags",
+					},
+					{
+						text: "Interceptors",
+						link: "/interceptors",
+					},
 					{
 						text: "Plugins",
 						link: "/plugins",
 					},
+					{
+						text: "Error Handling",
+						link: "/error-handling",
+					},
+					{
+						text: "Advanced Usage",
+						link: "/advanced",
+					},
 				],
 			},
 			{

docs/.vitepress/config/zh.ts

@@ -2,9 +2,9 @@ import { join } from "node:path";
 
 import { defineConfig } from "vitepress";
 
-import { getPluginNavigation } from "./plugin-navigation";
+import { getNavigation } from "../utils/navigation";
 
-const pluginNavigation = await getPluginNavigation(
+const pluginNavigation = await getNavigation(
 	join(import.meta.dirname, "..", "..", "zh", "official-plugins"),
 	"/zh/official-plugins",
 );
@@ -40,18 +40,30 @@ export const zhConfig = defineConfig({
 						text: "命令",
 						link: "/zh/commands",
 					},
-					{
-						text: "拦截器",
-						link: "/zh/interceptors",
-					},
 					{
 						text: "上下文",
 						link: "/zh/context",
 					},
+					{
+						text: "全局选项",
+						link: "/zh/global-flags",
+					},
+					{
+						text: "拦截器",
+						link: "/zh/interceptors",
+					},
 					{
 						text: "插件",
 						link: "/zh/plugins",
 					},
+					{
+						text: "错误处理",
+						link: "/zh/error-handling",
+					},
+					{
+						text: "进阶用法",
+						link: "/zh/advanced",
+					},
 				],
 			},
 			{

…s/.vitepress/config/plugin-navigation.ts docs/.vitepress/utils/navigation.tsdocs/.vitepress/config/plugin-navigation.ts renamed to docs/.vitepress/utils/navigation.ts docs/.vitepress/config/plugin-navigation.ts renamed to docs/.vitepress/utils/navigation.ts

@@ -18,7 +18,7 @@ function extractTitleFromMarkdown(content: string): string | null {
 	return titleMatch ? titleMatch[1].trim() : null;
 }
 
-export async function getPluginTitles(
+export async function getTitles(
 	path: string,
 ): Promise<{ filename: string; title: string }[]> {
 	try {
@@ -55,13 +55,13 @@ export async function getPluginTitles(
 	}
 }
 
-export async function getPluginNavigation(
+export async function getNavigation(
 	path: string,
 	webRoot: string,
 ): Promise<{ text: string; link: string }[]> {
-	const pluginTitles = await getPluginTitles(path);
+	const titles = await getTitles(path);
 
-	return pluginTitles.map(({ filename, title }) => {
+	return titles.map(({ filename, title }) => {
 		const link =
 			filename === "index.md"
 				? webRoot

docs/advanced.md

@@ -0,0 +1,36 @@
+---
+title: Advanced Usage
+---
+
+# Advanced Usage
+
+## Passing Custom Arguments
+
+Clerc allows you to pass a custom array of arguments instead of using the default `process.argv` / `Deno.args`. This is useful for testing or specific environments.
+
+```ts
+Clerc.create().parse(["node", "my-cli", "greet"]); // Pass a custom array of arguments
+```
+
+Alternatively, you can also pass an argument object:
+
+```ts
+Clerc.create().parse({
+	argv: ["greet"],
+});
+```
+
+## Parse Only Without Execution
+
+Sometimes you may want to parse commands and flags without immediately executing the command handler. Clerc provides an option to achieve this:
+
+```ts
+const result = Clerc.create().parse({
+	run: false, // Parse only, do not execute
+});
+```
+
+When you need to run, you can call:
+
+```ts
+result.run(); // Execute the parsed command

docs/error-handling.md

@@ -0,0 +1,24 @@
+---
+title: Error Handling
+---
+
+# Error Handling
+
+Clerc supports registering an error handler function to handle errors that occur during command parsing, command runtime, and other processes.
+
+## Example
+
+```ts
+Clerc.create()
+	.scriptName("my-cli")
+	.description("My CLI application")
+	.version("1.0.0")
+	.errorHandler((error: any) => {
+		console.error("An error occurred:", error.message);
+		// You can perform other actions as needed, such as logging the error or cleaning up resources
+	})
+	.command("run", "Run the application")
+	.on("run", (ctx) => {
+		throw new Error("Testing error handling");
+	})
+	.parse();

docs/global-flags.md

@@ -0,0 +1,26 @@
+---
+title: Global Flags
+---
+
+# Global Flags
+
+Clerc supports registering one or more global flags that can be used across all commands.
+
+## Example
+
+```ts
+Clerc.create()
+	.scriptName("my-cli")
+	.description("My CLI application")
+	.version("1.0.0")
+	.globalFlag("verbose", "Enable verbose output", {
+		type: Boolean,
+	}) // Global flag
+	.command("run", "Run the application")
+	.on("run", (ctx) => {
+		if (ctx.flags.verbose) {
+			console.log("Verbose mode enabled");
+		}
+		console.log("Running the application...");
+	})
+	.parse();

docs/zh/advanced.md

@@ -0,0 +1,37 @@
+---
+title: 进阶用法
+---
+
+# 进阶用法
+
+## 传入自定义参数
+
+Clerc 允许您传入自定义参数数组，而不是默认使用 `process.argv` / `Deno.args`。这在测试或特定环境下非常有用。
+
+```ts
+Clerc.create().parse(["node", "my-cli", "greet"]); // 传入自定义参数数组
+```
+
+或者您也可以传入一个参数对象：
+
+```ts
+Clerc.create().parse({
+	argv: ["greet"],
+});
+```
+
+## 仅解析命令，不执行
+
+有时您可能只想解析命令和选项，而不立即执行命令处理程序。Clerc 提供了一个选项来实现这一点：
+
+```ts
+const result = Clerc.create().parse({
+	run: false, // 仅解析，不执行
+});
+```
+
+在需要运行时，您可以调用：
+
+```ts
+result.run(); // 运行解析后的命令
+```

docs/zh/error-handling.md

@@ -0,0 +1,25 @@
+---
+title: 错误处理
+---
+
+# 错误处理
+
+Clerc 支持注册一个错误处理函数，用于处理捕获的命令解析、命令运行时等过程中发生的错误。
+
+## 示例
+
+```ts
+Clerc.create()
+	.scriptName("my-cli")
+	.description("My CLI application")
+	.version("1.0.0")
+	.errorHandler((error: any) => {
+		console.error("发生错误：", error.message);
+		// 您可以根据需要执行其他操作，例如记录错误、清理资源等
+	})
+	.command("run", "Run the application")
+	.on("run", (ctx) => {
+		throw new Error("测试错误处理");
+	})
+	.parse();
+```

docs/zh/global-flags.md

@@ -0,0 +1,27 @@
+---
+title: 全局选项
+---
+
+# 全局选项
+
+Clerc 支持全局注册一个或多个选项，这些选项可以在所有命令中使用。
+
+## 示例
+
+```ts
+Clerc.create()
+	.scriptName("my-cli")
+	.description("My CLI application")
+	.version("1.0.0")
+	.globalFlag("verbose", "Enable verbose output", {
+		type: Boolean,
+	}) // 全局选项
+	.command("run", "Run the application")
+	.on("run", (ctx) => {
+		if (ctx.flags.verbose) {
+			console.log("Verbose mode enabled");
+		}
+		console.log("Running the application...");
+	})
+	.parse();
+```