From 09435a6719b78ed51ce8bd708bd430dec4abd9c2 Mon Sep 17 00:00:00 2001 From: Weicao-CatilGrass <1992414357@qq.com> Date: Wed, 27 May 2026 14:31:26 +0800 Subject: Fix indentation and update Chinese documentation content --- docs/_zh_CN/pages/1-intro.md | 36 +++---- docs/_zh_CN/pages/2-step1.md | 6 +- docs/play/sources/zh_CN/2-writing3.md | 190 ++++++++++++++++++++++++---------- 3 files changed, 156 insertions(+), 76 deletions(-) diff --git a/docs/_zh_CN/pages/1-intro.md b/docs/_zh_CN/pages/1-intro.md index 4e3106c..eea766b 100644 --- a/docs/_zh_CN/pages/1-intro.md +++ b/docs/_zh_CN/pages/1-intro.md @@ -5,11 +5,11 @@ ## 前言 - 首先，非常感谢您愿意尝试和体验 **Mingling** +首先，非常感谢您愿意尝试和体验 **Mingling** - 因为这是一个早期框架，所以尚不成熟。 +因为这是一个早期框架，所以尚不成熟。 - 若您在使用过程中遇到任何问题，欢迎提交 [Issue](https://github.com/catilgrass/mingling/issues)，我们乐意解决。 +若您在使用过程中遇到任何问题，欢迎提交 [Issue](https://github.com/catilgrass/mingling/issues)，我们乐意解决。
@@ -29,39 +29,39 @@ ## Mingling 是什么？ - **Mingling** 是一款 Rust 命令行开发框架，更准确地说，它是一款在调度、执行、渲染等方面提供高度抽象的框架。 +**Mingling** 是一款 Rust 命令行开发框架，更准确地说，它是一款在调度、执行、渲染等方面提供高度抽象的框架。 - 它的核心逻辑是 **"转换"** —— 您输入的命令行参数（`Vec`）会经过一系列的类型转换，最终变成您想要的结果。用一张图来说明： +它的核心逻辑是 **"转换"** —— 您输入的命令行参数（`Vec`）会经过一系列的类型转换，最终变成您想要的结果。用一张图来说明：
- **这意味着**，您的执行逻辑和渲染逻辑是完全分离的：所有的状态、数据和结构都是类型，它们都只是转换过程中的一个环节，清晰又灵活。 +**这意味着**，您的执行逻辑和渲染逻辑是完全分离的：所有的状态、数据和结构都是类型，它们都只是转换过程中的一个环节，清晰又灵活。 ## 它适合什么样的项目？ - 如果您正在开发一个**子命令多、嵌套层次深、横切关注点多**，并且对**执行效率和动态补全**有要求的命令行工具，那么 **Mingling** 会是一个很好的选择。 +如果您正在开发一个**子命令多、嵌套层次深、横切关注点多**，并且对**执行效率和动态补全**有要求的命令行工具，那么 **Mingling** 会是一个很好的选择。 - 这些能力得益于它高度抽象的宏系统，以及几乎全部在编译期完成的构建逻辑，让您在运行时能获得出色的性能。 +这些能力得益于它高度抽象的宏系统，以及几乎全部在编译期完成的构建逻辑，让您在运行时能获得出色的性能。 ## Mingling 能做些什么？ - **Mingling** 专注于命令行流程的调度与编排，为您提供以下能力： +**Mingling** 专注于命令行流程的调度与编排，为您提供以下能力： - 1. **核心调度** — 通过类型转换优雅地编排业务逻辑 - 2. **纯函数设计** — 所有行为都是纯函数，可以直接测试 - 3. **无限嵌套** — 支持无限嵌套的子命令系统，再复杂的结构也能驾驭 - 4. **动态补全** — 为任意子命令插入完全动态的补全逻辑 **\[`comp`\]** - 5. **帮助文档** — 为任意子命令插入帮助文档，让用户轻松上手 +1. **核心调度** — 通过类型转换优雅地编排业务逻辑 +2. **纯函数设计** — 所有行为都是纯函数，可以直接测试 +3. **无限嵌套** — 支持无限嵌套的子命令系统，再复杂的结构也能驾驭 +4. **动态补全** — 为任意子命令插入完全动态的补全逻辑 **\[`comp`\]** +5. **帮助文档** — 为任意子命令插入帮助文档，让用户轻松上手 ## Mingling 不做些什么？ - **Mingling** 专注于命令行**流程的调度与编排**，因此它不会提供以下功能（您可以自由搭配其他库来实现）： +**Mingling** 专注于命令行**流程的调度与编排**，因此它不会提供以下功能（您可以自由搭配其他库来实现）： - 1. ❌ 彩色文字、进度条等外观功能 - 2. ❌ 国际化、本地化功能 - 3. ❌ TUI 界面功能 +1. ❌ 彩色文字、进度条等外观功能 +2. ❌ 国际化、本地化功能 +3. ❌ TUI 界面功能

Written by @Weicao-CatilGrass diff --git a/docs/_zh_CN/pages/2-step1.md b/docs/_zh_CN/pages/2-step1.md index 56f4b3c..251f23b 100644 --- a/docs/_zh_CN/pages/2-step1.md +++ b/docs/_zh_CN/pages/2-step1.md @@ -68,18 +68,17 @@ features = [""] ### 💡 关于 `r_println!` 宏 `r_println!` 宏并不是对 `println!` 的包装 -它是为 `#[renderer]` 宏中 **隐式注入** 的 `&mut RenderResult` 值提供。 +它是为 `#[renderer]` 宏中 **隐式注入** 的 `&mut RenderResult` 值提供的便捷访问方案。 在 `r_println!` 调用时，不会立刻向 stdout 输出信息，而是会被累计到 `&mut RenderResult` 中，在程序结束时整体输出。 - ## 六、编译并运行 现在您已经完成了 `list` 命令，现在可以使用 `cargo run` 运行您的程序： @@ -133,6 +132,7 @@ fn render_fruits(result: ResultFruits) { gen_program!(); ``` +

diff --git a/docs/play/sources/zh_CN/2-writing3.md b/docs/play/sources/zh_CN/2-writing3.md index e2038e3..252caab 100644 --- a/docs/play/sources/zh_CN/2-writing3.md +++ b/docs/play/sources/zh_CN/2-writing3.md @@ -7,10 +7,15 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } -gen_program!(); +gen_program!(); ``` --- @@ -22,12 +27,17 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } <<<<<<<<<< "我们将在此处编写渲染器代码" -gen_program!(); +gen_program!(); ``` --- @@ -39,12 +49,17 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } #[renderer] <<<<<<<<<< "和 #[chain] 类似，渲染器函数叫 #[renderer]" -gen_program!(); +gen_program!(); ``` --- @@ -56,13 +71,18 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } -#[renderer] +#[renderer] fn render_fruits( <<<<<<<<<< "编写函数体" -gen_program!(); +gen_program!(); ``` --- @@ -74,13 +94,18 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } -#[renderer] +#[renderer] fn render_fruits(result: ResultFruits <<<<<<<<<< "声明接收 ResultFruits 类型" -gen_program!(); +gen_program!(); ``` --- @@ -92,13 +117,18 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } -#[renderer] +#[renderer] fn render_fruits(result: ResultFruits) {} <<<<<<<<<< "一般情况下，渲染器什么都不用返回" -gen_program!(); +gen_program!(); ``` --- @@ -110,15 +140,20 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } -#[renderer] +#[renderer] fn render_fruits(result: ResultFruits) { <<<<<<<<<< "接下来在此处编写渲染逻辑" -} +} -gen_program!(); +gen_program!(); ``` --- @@ -130,15 +165,20 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } -#[renderer] +#[renderer] fn render_fruits(result: ResultFruits) { let vec: &Vec = <<<<<<<<<< "首先我们先解包 ResultFruits" -} +} -gen_program!(); +gen_program!(); ``` --- @@ -150,15 +190,20 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } -#[renderer] +#[renderer] fn render_fruits(result: ResultFruits) { let vec: &Vec = <<<<<<<<<< "pack! 宏会自动为 ResultFruits 实现 AsRef trait" -} +} -gen_program!(); +gen_program!(); ``` --- @@ -170,15 +215,20 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } -#[renderer] +#[renderer] fn render_fruits(result: ResultFruits) { let vec: &Vec = result.as_ref(); <<<<<<<<<< "所以此处可以使用 as_ref()" -} +} -gen_program!(); +gen_program!(); ``` --- @@ -190,15 +240,20 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } -#[renderer] +#[renderer] fn render_fruits(result: ResultFruits) { let vec: &Vec = &*result; <<<<<<<<<< "当然，deref 也可以解包 ResultFruits" -} +} -gen_program!(); +gen_program!(); ``` --- @@ -210,16 +265,21 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } -#[renderer] +#[renderer] fn render_fruits(result: ResultFruits) { - let vec: &Vec = &*result; + let vec: &Vec = &*result; for fruit in vec { <<<<<<<<<< "接下来，循环遍历 ResultFruits 中的水果字符串" -} +} -gen_program!(); +gen_program!(); ``` --- @@ -231,18 +291,23 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } -#[renderer] +#[renderer] fn render_fruits(result: ResultFruits) { - let vec: &Vec = &*result; + let vec: &Vec = &*result; for fruit in vec { <<<<<<<<<< "在循环中打印内容" } } -gen_program!(); +gen_program!(); ``` --- @@ -254,18 +319,23 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } -#[renderer] +#[renderer] fn render_fruits(result: ResultFruits) { - let vec: &Vec = &*result; + let vec: &Vec = &*result; for fruit in vec { r_println!("{}", fruit) <<<<<<<<<< "使用 r_println 在循环中打印内容" } } -gen_program!(); +gen_program!(); ``` --- @@ -277,18 +347,23 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } -#[renderer] +#[renderer] fn render_fruits(result: ResultFruits) { - let vec: &Vec = &*result; + let vec: &Vec = &*result; for fruit in vec { r_println!("{}", fruit) } } -gen_program!(); +gen_program!(); ``` --- @@ -302,16 +377,21 @@ pack!(ResultFruits = Vec); #[chain] fn handle_entry_list(_prev: EntryList) -> Next { - // ... + let fruits = vec![ + "Apple".to_string(), + "Banana".to_string(), + "Orange".to_string(), + ]; + ResultFruits::new(fruits) } #[renderer] fn render_fruits(result: ResultFruits) { - let vec: &Vec = &*result; + let vec: &Vec = &*result; for fruit in vec { r_println!("{}", fruit) } } -gen_program!(); +gen_program!(); ``` -- cgit