aboutsummaryrefslogtreecommitdiff
path: root/docs/_zh_CN/pages
diff options
context:
space:
mode:
Diffstat (limited to 'docs/_zh_CN/pages')
-rw-r--r--docs/_zh_CN/pages/1-getting-started.md6
-rw-r--r--docs/_zh_CN/pages/10-help.md6
-rw-r--r--docs/_zh_CN/pages/13-hook.md2
-rw-r--r--docs/_zh_CN/pages/14-testing.md4
-rw-r--r--docs/_zh_CN/pages/2-define-a-dispatcher.md4
-rw-r--r--docs/_zh_CN/pages/4-render-result.md4
-rw-r--r--docs/_zh_CN/pages/6-argument-parse-picker.md10
-rw-r--r--docs/_zh_CN/pages/8-setup-and-resources.md6
-rw-r--r--docs/_zh_CN/pages/9-error-handling.md4
-rw-r--r--docs/_zh_CN/pages/advanced/1-completion.md4
-rw-r--r--docs/_zh_CN/pages/concepts/1-the-pipeline.md4
-rw-r--r--docs/_zh_CN/pages/concepts/4-program-collect.md2
-rw-r--r--docs/_zh_CN/pages/other/features.md72
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 字段: