diff options
Diffstat (limited to 'docs/_zh_CN')
| -rw-r--r-- | docs/_zh_CN/pages/1-getting-started.md | 6 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/10-help.md | 6 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/13-hook.md | 2 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/14-testing.md | 4 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/2-define-a-dispatcher.md | 4 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/4-render-result.md | 4 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/6-argument-parse-picker.md | 10 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/8-setup-and-resources.md | 6 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/9-error-handling.md | 4 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/advanced/1-completion.md | 4 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/concepts/1-the-pipeline.md | 4 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/concepts/4-program-collect.md | 2 | ||||
| -rw-r--r-- | docs/_zh_CN/pages/other/features.md | 72 |
13 files changed, 94 insertions, 34 deletions
diff --git a/docs/_zh_CN/pages/1-getting-started.md b/docs/_zh_CN/pages/1-getting-started.md index 84870b2..6aa6229 100644 --- a/docs/_zh_CN/pages/1-getting-started.md +++ b/docs/_zh_CN/pages/1-getting-started.md @@ -13,19 +13,19 @@ cd my-cli ```toml [dependencies.mingling] -version = "0.3.0" +version = "0.4.0" features = [] ``` ## 启用特性 -**Mingling** 默认所有特性关闭,且不提供类似 `full` 的全开特性。 +**Mingling** 默认只启用 `core` 和 `macros`,其余部分需要按需启用 因为部分特性会 **直接影响整个生命周期的行为**,需要你按需启用,例如: ```toml [dependencies.mingling] -version = "0.3.0" +version = "0.4.0" features = [ "parser", "comp", diff --git a/docs/_zh_CN/pages/10-help.md b/docs/_zh_CN/pages/10-help.md index 1c4e410..a399ae3 100644 --- a/docs/_zh_CN/pages/10-help.md +++ b/docs/_zh_CN/pages/10-help.md @@ -27,14 +27,14 @@ fn help_greet(_entry: EntryGreet) { ## 全局帮助 -你也可以为 `ErrorDispatcherNotFound` 写帮助,作为"根帮助": +你也可以为 `EntryFallback` 写帮助,作为"根帮助": ```rust @@@use mingling::macros::help; @@@use mingling::macros::buffer; // 用户直接输入 --help 时触发 #[help(buffer)] -fn help_root(entry: ErrorDispatcherNotFound) { +fn help_root(entry: EntryFallback) { r_println!("Usage: my-cli <command>"); r_println!("Commands:"); r_println!(" greet Say hello"); @@ -42,7 +42,7 @@ fn help_root(entry: ErrorDispatcherNotFound) { ``` > [!TIP] -> `ErrorDispatcherNotFound` 是 `gen_program!()` 自动生成的类型,代表"没有匹配到任何命令"的情况。为它写 `#[help]` 就是给程序的根命令加帮助。 +> `EntryFallback` 是 `gen_program!()` 自动生成的类型,代表"没有匹配到任何命令"的情况。为它写 `#[help]` 就是给程序的根命令加帮助。 ## 需要 Setup 配合 diff --git a/docs/_zh_CN/pages/13-hook.md b/docs/_zh_CN/pages/13-hook.md index 6d6018a..ad3008a 100644 --- a/docs/_zh_CN/pages/13-hook.md +++ b/docs/_zh_CN/pages/13-hook.md @@ -71,7 +71,7 @@ fn main() { eprintln!("[hook] executing chain for: {}", info.input); }) .on_post_chain(|info| { - eprintln!("[hook] chain output: {}", info.output.member_id); + eprintln!("[hook] chain output: {}", info.output.member_id()); }), ); diff --git a/docs/_zh_CN/pages/14-testing.md b/docs/_zh_CN/pages/14-testing.md index 031be59..3567aef 100644 --- a/docs/_zh_CN/pages/14-testing.md +++ b/docs/_zh_CN/pages/14-testing.md @@ -70,10 +70,10 @@ fn test_handle_hello_with_name() { ## 用 entry! 宏构造数据 -如果启用了 `extra_macros`,可以用 `entry!` 快速构造 Entry: +如果启用了 `extras`,可以用 `entry!` 快速构造 Entry: ```rust -// Features: ["extra_macros"] +// Features: ["extras"] @@@use mingling::{assert_member_id, unpack_chain_process}; @@@use mingling::macros::entry; diff --git a/docs/_zh_CN/pages/2-define-a-dispatcher.md b/docs/_zh_CN/pages/2-define-a-dispatcher.md index 0afd911..b238d9f 100644 --- a/docs/_zh_CN/pages/2-define-a-dispatcher.md +++ b/docs/_zh_CN/pages/2-define-a-dispatcher.md @@ -79,10 +79,10 @@ pub struct EntryGreet { ## 进阶:隐式声明 -以上是标准写法。如果你启用了 `extra_macros` 特性,还可以更简洁: +以上是标准写法。如果你启用了 `extras` 特性,还可以更简洁: ```rust -// Features: ["extra_macros"] +// Features: ["extras"] // 省略 CMDType 和 EntryType,名字自动推导 dispatcher!("greet"); // dispatcher!("greet", CMDGreet => EntryGreet); diff --git a/docs/_zh_CN/pages/4-render-result.md b/docs/_zh_CN/pages/4-render-result.md index 8b29fca..7f66c71 100644 --- a/docs/_zh_CN/pages/4-render-result.md +++ b/docs/_zh_CN/pages/4-render-result.md @@ -116,13 +116,13 @@ cargo run -- great ## 补上 Fallback -`gen_program!()` 自动生成了一个 `ErrorDispatcherNotFound` 类型,包裹 `Vec<String>`——它存的是用户输入的那些没匹配到的命令。你只需要给它写一个 Renderer: +`gen_program!()` 自动生成了一个 `EntryFallback` 类型,包裹 `Vec<String>`——它存的是用户输入的那些没匹配到的命令。你只需要给它写一个 Renderer: ```rust use mingling::macros::buffer; #[renderer(buffer)] -fn render_dispatcher_not_found(err: ErrorDispatcherNotFound) { +fn render_entry_fallback(err: EntryFallback) { if err.inner.is_empty() { r_println!("Unknown command"); } else { diff --git a/docs/_zh_CN/pages/6-argument-parse-picker.md b/docs/_zh_CN/pages/6-argument-parse-picker.md index f0609ed..462a912 100644 --- a/docs/_zh_CN/pages/6-argument-parse-picker.md +++ b/docs/_zh_CN/pages/6-argument-parse-picker.md @@ -138,7 +138,7 @@ fn handle_test_entry(prev: EntryTest) -> Next { 先来看一个简单示例 ```rust -// Features: ["parser", "extra_macros"] +// Features: ["parser", "extras"] @@@use mingling::macros::buffer; @@@use mingling::macros::route; @@@dispatcher!("greet", CMDGreet => EntryGreet); @@ -164,10 +164,10 @@ fn render_greet(result: ResultName) { 若使用 `pick_or_route`,写法会变得相对复杂:因为 `.unpack()` 不再直接返回参数,而是 `Result<Value, Route>`。 -不过 **Mingling** 的 `extra_macros` 特性提供了简化展开的宏 `route!`,它不复杂,只是省略了一部分样板代码: +不过 **Mingling** 的 `extras` 特性提供了简化展开的宏 `route!`,它不复杂,只是省略了一部分样板代码: ```rust -// Features: ["parser", "extra_macros"] +// Features: ["parser", "extras"] @@@ pack!(ErrorFail = ()); @@@ use mingling::macros::route; @@@ fn func() -> mingling::ChainProcess<ThisProgram> { @@ -181,7 +181,7 @@ let name = route!(pick_result); 它展开为: ```rust -// Features: ["parser", "extra_macros"] +// Features: ["parser", "extras"] @@@ pack!(ErrorFail = ()); @@@ fn func() -> mingling::ChainProcess<ThisProgram> { @@@ let args: Vec<String> = vec![]; @@ -223,7 +223,7 @@ fn handle_greet_entry(prev: EntryGreet) -> Next { 同样,你可以使用 `after_or_route` 来处理输入参数的格式错误 ```rust -// Features: ["parser", "extra_macros"] +// Features: ["parser", "extras"] @@@use mingling::macros::buffer; @@@use mingling::macros::route; @@@dispatcher!("greet", CMDGreet => EntryGreet); diff --git a/docs/_zh_CN/pages/8-setup-and-resources.md b/docs/_zh_CN/pages/8-setup-and-resources.md index d38e69d..9ed9894 100644 --- a/docs/_zh_CN/pages/8-setup-and-resources.md +++ b/docs/_zh_CN/pages/8-setup-and-resources.md @@ -8,7 +8,7 @@ ## 用 Setup 做初始化 ```rust -// Features: ["extra_macros"] +// Features: ["extras"] @@@use mingling::macros::program_setup; @@@use mingling::Program; #[program_setup] @@ -32,14 +32,14 @@ fn my_setup(program: &mut Program<ThisProgram>) { 在 `main` 里通过 `program.with_setup(...)` 注册即可使用。 > [!NOTE] -> `#[program_setup]` 需要 `extra_macros` 特性。没有此特性时,可以手动实现 `ProgramSetup` trait。 +> `#[program_setup]` 需要 `extras` 特性。没有此特性时,可以手动实现 `ProgramSetup` trait。 ## 提取全局参数 Setup 里最常用的操作就是提取全局参数。Mingling 提供了几个辅助方法: ```rust -// Features: ["extra_macros"] +// Features: ["extras"] @@@use mingling::macros::program_setup; @@@use mingling::Program; #[program_setup] diff --git a/docs/_zh_CN/pages/9-error-handling.md b/docs/_zh_CN/pages/9-error-handling.md index 4ce61ab..f5055b8 100644 --- a/docs/_zh_CN/pages/9-error-handling.md +++ b/docs/_zh_CN/pages/9-error-handling.md @@ -107,10 +107,10 @@ Error: name is required ## 关于 `pack_err!` -如果你启用了 `extra_macros`,还可以用 `pack_err!` 快速声明带有自动 `name` 字段的错误类型: +如果你启用了 `extras`,还可以用 `pack_err!` 快速声明带有自动 `name` 字段的错误类型: ```rust -// Features: ["extra_macros"] +// Features: ["extras"] pack_err!(ErrorNotFound); // 生成: struct ErrorNotFound { pub name: String } ``` diff --git a/docs/_zh_CN/pages/advanced/1-completion.md b/docs/_zh_CN/pages/advanced/1-completion.md index 3941404..a6500db 100644 --- a/docs/_zh_CN/pages/advanced/1-completion.md +++ b/docs/_zh_CN/pages/advanced/1-completion.md @@ -15,8 +15,8 @@ features = ["comp"] [build-dependencies.mingling] features = [ "comp", - # 启用 `builds` 特性以提供构建期支持 - "builds" + # 启用 `build` 特性以提供构建期支持 + "build" ] ``` diff --git a/docs/_zh_CN/pages/concepts/1-the-pipeline.md b/docs/_zh_CN/pages/concepts/1-the-pipeline.md index b0bb19d..9c74087 100644 --- a/docs/_zh_CN/pages/concepts/1-the-pipeline.md +++ b/docs/_zh_CN/pages/concepts/1-the-pipeline.md @@ -42,12 +42,12 @@ graph TD graph LR Input["用户输入"] --> M{匹配 Dispatcher} M -->|"匹配到"| E["调用 dispatcher.begin(args)<br/>返回包装好的 Entry"] - M -->|"未匹配"| NF["build_dispatcher_not_found<br/>生成 ErrorDispatcherNotFound"] + M -->|"未匹配"| NF["build_entry_fallback<br/>生成 EntryFallback"] ``` 匹配成功后调用 `dispatcher.begin(args)`,返回 `ChainProcess::Ok((AnyOutput, _))`,即包装好用户输入参数的 Entry 类型。 -如果没有匹配到任何 Dispatcher,则生成 `ErrorDispatcherNotFound`(包裹完整的输入参数),后续可以被 Renderer 处理显示 "Command not found"。 +如果没有匹配到任何 Dispatcher,则生成 `EntryFallback`(包裹完整的输入参数),后续可以被 Renderer 处理显示 "Command not found"。 ### 2. Help 短路 diff --git a/docs/_zh_CN/pages/concepts/4-program-collect.md b/docs/_zh_CN/pages/concepts/4-program-collect.md index f5e6b8f..a0236f6 100644 --- a/docs/_zh_CN/pages/concepts/4-program-collect.md +++ b/docs/_zh_CN/pages/concepts/4-program-collect.md @@ -21,7 +21,7 @@ - **`render`** —— 根据 `member_id` 调用对应的 `#[renderer]` 函数,写入 `RenderResult` - **`render_help`** —— 根据 `member_id` 调用对应的 `#[help]` 函数 - **`has_chain` / `has_renderer`** —— 判断某个变体有没有对应的处理函数 -- **`build_dispatcher_not_found` / `build_renderer_not_found` / `build_empty_result`** —— 三个内置降级类型,处理边界情况 +- **`build_entry_fallback` / `build_renderer_not_found` / `build_empty_result`** —— 三个内置降级类型,处理边界情况 这套映射在运行时通过枚举匹配来完成——编译期只生成了枚举和匹配分支,实际的函数调用发生在运行时。 diff --git a/docs/_zh_CN/pages/other/features.md b/docs/_zh_CN/pages/other/features.md index 8bd386c..2d65e47 100644 --- a/docs/_zh_CN/pages/other/features.md +++ b/docs/_zh_CN/pages/other/features.md @@ -3,6 +3,66 @@ <b>Mingling</b> 的所有特性一览 </p> +# 预设特性组 + +Mingling 提供了一系列**预设特性组**,方便用户按需组合启用特性。 + +## `mini` + +**启用特性:** `extras`、`picker` + +**定位:** 精简模式,适合小型 CLI 工具或需要快速起步的项目。仅包含最核心的便捷宏和参数解析能力。 + +## `advanced` + +**启用特性:** `extras`、`picker`、`repl`、`comp`、`dispatch_tree`、`structural_renderer` + +**定位:** 进阶模式,在 `mini` 的基础上加入了交互式 REPL 环境、代码补全、调度树加速以及基础的结构化输出能力,适合功能较完整的中型命令行应用。 + +## `full` + +**启用特性:** `extras`、`picker`、`repl`、`clap`、`comp`、`dispatch_tree`、`structural_renderer_full`、`pathf` + +**定位:** 完整模式,启用 Mingling 的全部核心功能。在 `advanced` 的基础上额外包含 clap 集成、完整的结构化渲染器(含所有序列化格式)以及实验性的路径分析器,适合大型、功能全面的命令行应用。 + +## `build_advanced` + +**启用特性:** `build`、`comp` + +**定位:** 构建期增强配置,用于在项目构建时生成补全脚本等构建辅助材料(`comp` 特性提供补全脚本生成能力)。 + +> [!NOTE] +> +> 此特性组为**构建依赖**专用,需配合 `advanced` 特性使用。请在 `Cargo.toml` 的 `[build-dependencies]` 中启用: + +```toml +[dependencies.mingling] +features = ["advanced"] + +[build-dependencies.mingling] +features = ["build_advanced"] +``` + +## `build_full` + +**启用特性:** `build`、`comp`、`pathf`、`dispatch_tree` + +**定位:** 完整的构建期配置,在 `build_advanced` 的基础上额外包含路径分析器(`pathf`)以自动解析类型模块路径,适合结构复杂、需要自动化构建期分析的项目。 + +> [!NOTE] +> +> 此特性组为**构建依赖**专用,需配合 `full` 特性使用。请在 `Cargo.toml` 的 `[build-dependencies]` 中启用: + +```toml +[dependencies.mingling] +features = ["full"] + +[build-dependencies.mingling] +features = ["build_full"] +``` + +# 特性详解 + ## 特性 `all_serde_fmt` **介绍:** @@ -83,7 +143,7 @@ build_comp_scripts("myprogram").unwrap(); 详见 [示例](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-dispatch-tree) -## 特性 `extra_macros` +## 特性 `extras` **介绍:** @@ -106,7 +166,7 @@ build_comp_scripts("myprogram").unwrap(); ### `empty_result!()` ```rust -// Features: ["extra_macros"] +// Features: ["extras"] pack!(StatePrev1 = ()); pack!(StatePrev2 = ()); @@ -134,7 +194,7 @@ fn handle_state_prev1(_p: StatePrev1) -> Next { ### `#[program_setup]` ```rust -// Features: ["extra_macros"] +// Features: ["extras"] use mingling::{macros::program_setup, Program}; fn main() { @@ -154,7 +214,7 @@ fn no_error_setup(program: &mut Program<ThisProgram>) { ### `entry!` ```rust -// Features: ["extra_macros"] +// Features: ["extras"] use mingling::macros::entry; pack!(EntryHello = Vec<String>); @@ -174,7 +234,7 @@ fn handle_hello(args: EntryHello) {} 类型名会直接作为枚举变体,与 `pack!` 或 `#[derive(Grouped)]` 一致。 ```rust -// Features: ["extra_macros"] +// Features: ["extras"] use mingling::macros::group; use std::num::ParseIntError; @@ -189,7 +249,7 @@ group!(std::num::ParseIntError); 可选择包裹一个内部类型以携带额外上下文。 ```rust -// Features: ["extra_macros"] +// Features: ["extras"] use std::path::PathBuf; // 简单形式——仅包含 name 字段: |
