From be74c5f6ae45e528625a3ae6ebe25fd86b8449c0 Mon Sep 17 00:00:00 2001 From: Weicao-CatilGrass <1992414357@qq.com> Date: Fri, 12 Jun 2026 21:28:41 +0800 Subject: Add naming conventions documentation and update sidebar --- docs/_sidebar.md | 2 + docs/_zh_CN/_sidebar.md | 2 - docs/_zh_CN/pages/other/naming_rule.md | 96 ++++++++-------- docs/pages/other/.name | 1 + docs/pages/other/naming_rule.md | 200 +++++++++++++++++++++++++++++++++ docs/play/sources/zh_CN/_template.md | 4 +- 6 files changed, 253 insertions(+), 52 deletions(-) create mode 100644 docs/pages/other/.name create mode 100644 docs/pages/other/naming_rule.md (limited to 'docs') diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 40968ba..e910178 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1 +1,3 @@ - [Welcome!](README) +* Other + * [Naming Conventions](pages/other/naming_rule) diff --git a/docs/_zh_CN/_sidebar.md b/docs/_zh_CN/_sidebar.md index 12e7f94..20615d5 100644 --- a/docs/_zh_CN/_sidebar.md +++ b/docs/_zh_CN/_sidebar.md @@ -1,5 +1,3 @@ - [Welcome!](README) -* [介绍](pages/1-intro) -* [初次上手！](pages/2-step1) * 其他 * [命名规范](pages/other/naming_rule) diff --git a/docs/_zh_CN/pages/other/naming_rule.md b/docs/_zh_CN/pages/other/naming_rule.md index 59dc9cd..18ebf3f 100644 --- a/docs/_zh_CN/pages/other/naming_rule.md +++ b/docs/_zh_CN/pages/other/naming_rule.md @@ -19,11 +19,11 @@ Res + 名称 ``` -| 示例 | 说明 | -|------|------| +| 示例 | 说明 | +| --------------- | ------------ | | `ResCurrentDir` | 当前工作目录 | -| `ResExitCode` | 进程退出码 | -| `ResREPL` | REPL 状态 | +| `ResExitCode` | 进程退出码 | +| `ResREPL` | REPL 状态 | ### 构建 @@ -33,10 +33,10 @@ Res + 名称 名称 + Setup ``` -| 示例 | 说明 | -|------|------| -| `BasicSetup` | 基础初始化（`--quiet`、`--help`、`--confirm`） | -| `GeneralRendererSetup` | 通用渲染器初始化（`--json`、`--yaml` 等） | +| 示例 | 说明 | +| ---------------------- | ---------------------------------------------- | +| `BasicSetup` | 基础初始化（`--quiet`、`--help`、`--confirm`） | +| `GeneralRendererSetup` | 通用渲染器初始化（`--json`、`--yaml` 等） | ### 分发器 @@ -46,11 +46,11 @@ Res + 名称 CMD + 命令层级 ``` -| 节点 | 分发器 | -|------|--------| -| `greet` | `CMDGreet` | -| `remote.add` | `CMDRemoteAdd` | -| `remote.rm` | `CMDRemoteRemove` | +| 节点 | 分发器 | +| ------------ | ----------------- | +| `greet` | `CMDGreet` | +| `remote.add` | `CMDRemoteAdd` | +| `remote.rm` | `CMDRemoteRemove` | 即使节点是缩写，分发器的名称也要写全名。例如节点是 `remote.rm`，分发器是 `CMDRemoteRemove`，不是 `CMDRemoteRm`。 @@ -62,10 +62,10 @@ CMD + 命令层级 Entry + 命令层级 ``` -| 分发器 | 入口 | -|--------|------| -| `CMDGreet` | `EntryGreet` | -| `CMDRemoteAdd` | `EntryRemoteAdd` | +| 分发器 | 入口 | +| ----------------- | ------------------- | +| `CMDGreet` | `EntryGreet` | +| `CMDRemoteAdd` | `EntryRemoteAdd` | | `CMDRemoteRemove` | `EntryRemoteRemove` | ### 状态 @@ -76,10 +76,10 @@ Entry + 命令层级 State + 描述 ``` -| 示例 | 说明 | -|------|------| +| 示例 | 说明 | +| ----------------------- | -------------------- | | `StateOperationRemotes` | 正在操作远程仓库列表 | -| `StateCheckRepository` | 正在检查仓库状态 | +| `StateCheckRepository` | 正在检查仓库状态 | 典型的管线链：`EntryRemoteAdd → StateOperationRemotes → StateCheckRepository` @@ -91,10 +91,10 @@ State + 描述 Result + 内容 ``` -| 示例 | 说明 | -|------|------| -| `ResultGreetSomeone` | 问候结果 | -| `ResultFruitList` | 水果列表结果 | +| 示例 | 说明 | +| -------------------- | ------------ | +| `ResultGreetSomeone` | 问候结果 | +| `ResultFruitList` | 水果列表结果 | 结果结构体期望被 Renderer 消费，内部结构应该为了渲染美观而设计。一般用 `#[derive(Groupped)]` 代替 `pack!()` 包装，以获得更灵活的字段控制。 @@ -106,33 +106,31 @@ Result + 内容 Error + 描述 ``` -| 示例 | 说明 | -|------|------| +| 示例 | 说明 | +| ------------------------- | ---------- | | `ErrorRepositoryNotFound` | 仓库未找到 | `StateOperationRemotes → ErrorRepositoryNotFound` - - ## 函数命名 ### Chain 函数 -| 处理类型 | 命名模式 | 示例 | -|----------|----------|------| -| Entry | `handle_` + entry 名（snake_case） | `handle_remote_add(prev: EntryRemoteAdd)` | -| State | `handle_state_` + state 名（snake_case） | `handle_state_operation_remotes(prev: StateOperationRemotes)` | -| Error | `handle_error_` + error 名（snake_case） | `handle_error_repository_not_found(prev: ErrorRepositoryNotFound)` | -| Result | ❌ 不要为 Result 写 chain | — | +| 处理类型 | 命名模式 | 示例 | +| -------- | ---------------------------------------- | ------------------------------------------------------------------ | +| Entry | `handle_` + entry 名（snake_case） | `handle_remote_add(prev: EntryRemoteAdd)` | +| State | `handle_state_` + state 名（snake_case） | `handle_state_operation_remotes(prev: StateOperationRemotes)` | +| Error | `handle_error_` + error 名（snake_case） | `handle_error_repository_not_found(prev: ErrorRepositoryNotFound)` | +| Result | ❌ 不要为 Result 写 chain | — | ### Renderer 函数 -| 处理类型 | 命名模式 | 示例 | -|----------|----------|------| -| Entry | `render_entry_` + entry 名 | `render_entry_remote_add(prev: EntryRemoteAdd)` | -| State | ❌ 不要为 State 写 renderer | — | -| Error | `render_error_` + error 名 | `render_error_repository_not_found(prev: ErrorRepositoryNotFound)` | -| Result | `render_` + result 名 | `render_greet_someone(prev: ResultGreetSomeone)` | +| 处理类型 | 命名模式 | 示例 | +| -------- | --------------------------- | ------------------------------------------------------------------ | +| Entry | `render_entry_` + entry 名 | `render_entry_remote_add(prev: EntryRemoteAdd)` | +| State | ❌ 不要为 State 写 renderer | — | +| Error | `render_error_` + error 名 | `render_error_repository_not_found(prev: ErrorRepositoryNotFound)` | +| Result | `render_` + result 名 | `render_greet_someone(prev: ResultGreetSomeone)` | **原则**：不要为不会被用户看到或不需要独立渲染的中间类型写 renderer。 @@ -140,16 +138,17 @@ Error + 描述 ## 函数签名参数命名 -| 类型 | 推荐参数名 | -|------|------------| -| Entry | `args` | -| State | `prev`（或具名如 `remotes`） | -| Result | `result`（或具名如 `fruits`） | -| Error | `err` | -| 资源（不可变） | `cwd`、`db`、`config` 等 | -| 资源（可变） | `counter`、`cache`、`session` 等 | +| 类型 | 推荐参数名 | +| -------------- | -------------------------------- | +| Entry | `args` | +| State | `prev`（或具名如 `remotes`） | +| Result | `result`（或具名如 `fruits`） | +| Error | `err` | +| 资源（不可变） | `cwd`、`db`、`config` 等 | +| 资源（可变） | `counter`、`cache`、`session` 等 | ```rust +// NOT VERIFIED #[chain] fn handle_remote_add(args: EntryRemoteAdd, cwd: &ResCurrentDir, db: &mut ResDatabase) -> Next { // args: 入口数据 @@ -163,6 +162,7 @@ fn handle_remote_add(args: EntryRemoteAdd, cwd: &ResCurrentDir, db: &mut ResData ## 完整示例 ```rust +// NOT VERIFIED // 分发器 dispatcher!("remote.add", CMDRemoteAdd => EntryRemoteAdd); diff --git a/docs/pages/other/.name b/docs/pages/other/.name new file mode 100644 index 0000000..01ea8a0 --- /dev/null +++ b/docs/pages/other/.name @@ -0,0 +1 @@ +Other diff --git a/docs/pages/other/naming_rule.md b/docs/pages/other/naming_rule.md new file mode 100644 index 0000000..9443481 --- /dev/null +++ b/docs/pages/other/naming_rule.md @@ -0,0 +1,200 @@ +

Naming Conventions

+

+ Keep your Mingling project types and function names organized +

+ +## Preface + +Good naming is the foundation of large CLI projects. Mingling's pipeline pattern introduces several new types (Entry, State, Result, Error, Resource). Without consistent conventions, projects quickly end up with generic names like `Data`, `Info`, or `Context` that make it impossible to tell different responsibilities apart. + +The naming conventions below come from real-world usage in production projects. They are not enforced by the framework, but following them is highly recommended. + +## Type Naming + +### Resource + +Resources are global instances shared with all chains and renderers through the resource injection system. + +``` +Res + Name +``` + +| Example | Description | +| --------------- | ------------------------- | +| `ResCurrentDir` | Current working directory | +| `ResExitCode` | Process exit code | +| `ResREPL` | REPL state | + +### Setup + +Setups are initialization steps executed at program startup, registered via `with_setup`. + +``` +Name + Setup +``` + +| Example | Description | +| ---------------------- | ---------------------------------------------------------- | +| `BasicSetup` | Basic initialization (`--quiet`, `--help`, `--confirm`) | +| `GeneralRendererSetup` | General renderer initialization (`--json`, `--yaml`, etc.) | + +### Dispatcher + +Dispatchers are the entry points of commands, corresponding one-to-one with `Node` names. Node names use `.` to separate levels, dispatcher names use the `CMD` prefix with PascalCase. + +``` +CMD + Command Hierarchy +``` + +| Node | Dispatcher | +| ------------ | ----------------- | +| `greet` | `CMDGreet` | +| `remote.add` | `CMDRemoteAdd` | +| `remote.rm` | `CMDRemoteRemove` | + +Even if a node is an abbreviation, the dispatcher name should use the full name. For example, the node is `remote.rm`, but the dispatcher is `CMDRemoteRemove`, not `CMDRemoteRm`. + +### Entry + +Entries are the pipeline starting types created by dispatchers, wrapping `Vec`. + +``` +Entry + Command Hierarchy +``` + +| Dispatcher | Entry | +| ----------------- | ------------------- | +| `CMDGreet` | `EntryGreet` | +| `CMDRemoteAdd` | `EntryRemoteAdd` | +| `CMDRemoteRemove` | `EntryRemoteRemove` | + +### State + +States are intermediate pipeline types between Entry and Result, representing data after partial processing. + +``` +State + Description +``` + +| Example | Description | +| ----------------------- | ----------------------------- | +| `StateOperationRemotes` | Operating on remote repo list | +| `StateCheckRepository` | Checking repository status | + +Typical pipeline chain: `EntryRemoteAdd → StateOperationRemotes → StateCheckRepository` + +### Result + +Results are the final types sent to the Renderer via `to_render()` in the pipeline. + +``` +Result + Content +``` + +| Example | Description | +| -------------------- | ----------------- | +| `ResultGreetSomeone` | Greeting result | +| `ResultFruitList` | Fruit list result | + +Result structs are expected to be consumed by the Renderer, and their internal structure should be designed for rendering aesthetics. Generally use `#[derive(Groupped)]` instead of `pack!()` wrapping for more flexible field control. + +### Error + +Errors are different from Results. Errors can be sent via `to_chain()` or `to_render()` to route execution to the error handling path. + +``` +Error + Description +``` + +| Example | Description | +| ------------------------- | -------------------- | +| `ErrorRepositoryNotFound` | Repository not found | + +`StateOperationRemotes → ErrorRepositoryNotFound` + +## Function Naming + +### Chain Functions + +| Processing Type | Naming Pattern | Example | +| --------------- | ----------------------------------------- | ------------------------------------------------------------------ | +| Entry | `handle_` + entry name (snake_case) | `handle_remote_add(prev: EntryRemoteAdd)` | +| State | `handle_state_` + state name (snake_case) | `handle_state_operation_remotes(prev: StateOperationRemotes)` | +| Error | `handle_error_` + error name (snake_case) | `handle_error_repository_not_found(prev: ErrorRepositoryNotFound)` | +| Result | ❌ Do not write chains for Result | — | + +### Renderer Functions + +| Processing Type | Naming Pattern | Example | +| --------------- | ----------------------------------- | ------------------------------------------------------------------ | +| Entry | `render_entry_` + entry name | `render_entry_remote_add(prev: EntryRemoteAdd)` | +| State | ❌ Do not write renderers for State | — | +| Error | `render_error_` + error name | `render_error_repository_not_found(prev: ErrorRepositoryNotFound)` | +| Result | `render_` + result name | `render_greet_someone(prev: ResultGreetSomeone)` | + +**Principle**: Do not write renderers for intermediate types that users won't see or that don't need independent rendering. + +--- + +## Function Signature Parameter Naming + +| Type | Recommended Parameter Name | +| -------------------- | --------------------------------------- | +| Entry | `args` | +| State | `prev` (or descriptive like `remotes`) | +| Result | `result` (or descriptive like `fruits`) | +| Error | `err` | +| Resource (immutable) | `cwd`, `db`, `config`, etc. | +| Resource (mutable) | `counter`, `cache`, `session`, etc. | + +```rust +// NOT VERIFIED +#[chain] +fn handle_remote_add(args: EntryRemoteAdd, cwd: &ResCurrentDir, db: &mut ResDatabase) -> Next { + // args: entry data + // cwd: injected immutable resource + // db: injected mutable resource +} +``` + +--- + +## Complete Example + +```rust +// NOT VERIFIED +// Dispatcher +dispatcher!("remote.add", CMDRemoteAdd => EntryRemoteAdd); + +// Entry → State +#[chain] +fn handle_remote_add(args: EntryRemoteAdd) -> Next { + StateOperationRemotes::new(...).to_chain() +} + +// State → Error or Result +#[chain] +fn handle_state_operation_remotes(state: StateOperationRemotes, db: &ResDatabase) -> Next { + if db.has_remote(&state.name) { + ErrorRepositoryNotFound::new(...).to_render() + } else { + ResultRemoteAdded::new(...).to_render() + } +} + +// Result rendering +#[renderer] +fn render_remote_added(result: ResultRemoteAdded) { + r_println!("Remote added: {}", result.name); +} + +// Error rendering +#[renderer] +fn render_error_repository_not_found(err: ErrorRepositoryNotFound) { + r_println!("Error: remote '{}' not found", err.name); +} +``` + +

+ Written by @Weicao-CatilGrass +

diff --git a/docs/play/sources/zh_CN/_template.md b/docs/play/sources/zh_CN/_template.md index 29fed62..14e5a1e 100644 --- a/docs/play/sources/zh_CN/_template.md +++ b/docs/play/sources/zh_CN/_template.md @@ -3,7 +3,7 @@ ```bash 代码 <<<<<<<<<< "提示" ``` - + --- 消息2 @@ -11,5 +11,5 @@ ```bash 代码 <<<<<<<<<< "提示" ``` - + --- -- cgit