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/11-resource-system.md11
-rw-r--r--docs/_zh_CN/pages/12-exit-code.md7
-rw-r--r--docs/_zh_CN/pages/13-hook.md5
-rw-r--r--docs/_zh_CN/pages/14-testing.md39
-rw-r--r--docs/_zh_CN/pages/2-define-a-dispatcher.md10
-rw-r--r--docs/_zh_CN/pages/3-define-a-chain.md54
-rw-r--r--docs/_zh_CN/pages/4-render-result.md35
-rw-r--r--docs/_zh_CN/pages/5-multiple-commands.md20
-rw-r--r--docs/_zh_CN/pages/6-argument-parse-picker.md64
-rw-r--r--docs/_zh_CN/pages/9-error-handling.md40
-rw-r--r--docs/_zh_CN/pages/advanced/2-structural-renderer.md20
-rw-r--r--docs/_zh_CN/pages/concepts/2-resource.md3
-rw-r--r--docs/_zh_CN/pages/concepts/3-any-output.md6
-rw-r--r--docs/_zh_CN/pages/concepts/4-program-collect.md2
-rw-r--r--docs/_zh_CN/pages/other/features.md59
-rw-r--r--docs/_zh_CN/pages/other/naming_rule.md25
16 files changed, 228 insertions, 172 deletions
diff --git a/docs/_zh_CN/pages/11-resource-system.md b/docs/_zh_CN/pages/11-resource-system.md
index 40d8cd9..b0fbe31 100644
--- a/docs/_zh_CN/pages/11-resource-system.md
+++ b/docs/_zh_CN/pages/11-resource-system.md
@@ -31,11 +31,12 @@ fn main() {
@@@#[derive(Default, Clone)]
@@@struct ResCurrentDir(String);
@@@dispatcher!("pwd", EntryPrintWorkingDir);
-@@@pack!(ResultPath = String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultPath(String);
// 通过 &T 注入只读资源
#[chain]
fn handle_pwd(_args: EntryPrintWorkingDir, cwd: &ResCurrentDir) -> Next {
- ResultPath::new(cwd.0.clone()).to_render()
+ ResultPath(cwd.0.clone()).to_render()
}
#[renderer(buffer)]
@@ -53,7 +54,8 @@ fn render_path(result: ResultPath) {
@@@#[derive(Default, Clone)]
@@@struct ResVisitCount(u32);
@@@dispatcher!("visit", EntryVisit);
-@@@pack!(ResultDone = ());
+@@@#[derive(Grouped, Wrap, Default)]
+@@@pub struct ResultDone(());
#[chain]
fn handle_visit(_args: EntryVisit, counter: &mut ResVisitCount) -> Next {
counter.0 += 1;
@@ -74,7 +76,8 @@ Chain 可以同时注入任意多个资源,框架按类型自动匹配:
@@@#[derive(Default, Clone)] struct ResConfig(String);
@@@#[derive(Default, Clone)] struct ResCounter(u32);
@@@dispatcher!("test", EntryTest);
-@@@pack!(ResultDone = ());
+@@@#[derive(Grouped, Wrap, Default)]
+@@@pub struct ResultDone(());
// 同时注入只读 + 可修改
#[chain]
fn handle_test(_args: EntryTest, config: &ResConfig, counter: &mut ResCounter) -> Next {
diff --git a/docs/_zh_CN/pages/12-exit-code.md b/docs/_zh_CN/pages/12-exit-code.md
index 7c55b60..9270b84 100644
--- a/docs/_zh_CN/pages/12-exit-code.md
+++ b/docs/_zh_CN/pages/12-exit-code.md
@@ -3,9 +3,7 @@
如何使用资源系统管理程序退出码
</p>
-程序退出时给 shell 一个正确的退出码是 CLI 的基本素养
-
-。Mingling 提供了开箱即用的 `ExitCodeSetup`,配合 `ResExitCode` 资源,让退出码控制变得极其简单。
+程序退出时给 shell 一个正确的退出码是 CLI 的基本素养。Mingling 提供了开箱即用的 `ExitCodeSetup`,配合 `ResExitCode` 资源,让退出码控制变得极其简单。
## 启用 ExitCodeSetup
@@ -31,7 +29,8 @@ fn main() {
```rust
@@@use mingling::res::ResExitCode;
@@@use mingling::setup::ExitCodeSetup;
-@@@pack!(EntryCheck = Vec<String>);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct EntryCheck(Vec<String>);
#[chain]
fn handle_check(_args: EntryCheck, ec: &mut ResExitCode) {
// 检查失败的时候修改退出码资源
diff --git a/docs/_zh_CN/pages/13-hook.md b/docs/_zh_CN/pages/13-hook.md
index 811957c..860bd2b 100644
--- a/docs/_zh_CN/pages/13-hook.md
+++ b/docs/_zh_CN/pages/13-hook.md
@@ -55,10 +55,11 @@ Hook 覆盖了管线的完整生命周期:
@@@use mingling::hook::ProgramHook;
@@@
@@@dispatcher!("greet", EntryGreet);
-@@@pack!(ResultName = String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultName(String);
@@@
@@@#[chain] fn handle_greet(args: EntryGreet) -> Next {
-@@@ ResultName::new(args.inner.first().cloned().unwrap_or_default()).to_render()
+@@@ ResultName(args.0.first().cloned().unwrap_or_default()).to_render()
@@@}
@@@#[renderer] fn render_name(r: ResultName) -> RenderResult { RenderResult::new() }
fn main() {
diff --git a/docs/_zh_CN/pages/14-testing.md b/docs/_zh_CN/pages/14-testing.md
index 30f3fc4..13585ee 100644
--- a/docs/_zh_CN/pages/14-testing.md
+++ b/docs/_zh_CN/pages/14-testing.md
@@ -12,7 +12,8 @@ Chain 只是一个接收输入、返回输出的函数,Renderer 也只是接
Renderer 是最容易测试的——调用函数,断言返回结果:
```rust
-@@@pack!(ResultName = String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultName(String);
#[renderer]
fn render_greet(result: ResultName) -> RenderResult {
let mut r = RenderResult::new();
@@ -22,7 +23,7 @@ fn render_greet(result: ResultName) -> RenderResult {
#[test]
fn test_render_name() {
- let result = render_name(ResultName::new("Alice".to_string()));
+ let result = render_name(ResultName("Alice".to_string()));
assert_eq!(result.to_string().as_str(), "Hello, Alice!\n");
}
```
@@ -36,27 +37,29 @@ fn test_render_name() {
```rust
@@@use mingling::{assert_member_id, assert_render_result, unpack_chain_process};
@@@dispatcher!("hello", EntryHello);
-@@@pack!(ResultName = String);
-@@@pack!(ErrorNoName = ());
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultName(String);
+@@@#[derive(Grouped, Wrap, Default)]
+@@@pub struct ErrorNoName(());
@@@#[chain]
@@@fn handle_hello(args: EntryHello) -> Next {
-@@@ let name = args.inner.first().cloned().unwrap_or_default();
+@@@ let name = args.0.first().cloned().unwrap_or_default();
@@@ if name.is_empty() {
@@@ ErrorNoName::default().to_render()
@@@ } else {
-@@@ ResultName::new(name).to_render()
+@@@ ResultName(name).to_render()
@@@ }
@@@}
#[test]
fn test_handle_hello_with_name() {
- let chain_process = handle_hello(EntryGreet::new(vec!["Alice".to_string()])).into();
+ let chain_process = handle_hello(EntryHello(vec!["Alice".to_string()])).into();
// 断言这是一个渲染结果(不是继续 chain)
assert_render_result!(chain_process);
// 断言 member_id 是 ResultName
assert_member_id!(chain_process, ResultName);
// 解包出内部值
let result_name = unpack_chain_process!(chain_process, ResultName);
- assert_eq!(result_name.inner, "Alice");
+ assert_eq!(result_name.0, "Alice");
}
```
@@ -78,11 +81,12 @@ fn test_handle_hello_with_name() {
@@@use mingling::{assert_member_id, unpack_chain_process};
@@@use mingling::macros::entry;
@@@dispatcher!("hello", EntryHello);
-@@@pack!(ResultName = String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultName(String);
@@@#[chain]
@@@fn handle_hello(args: EntryHello) -> Next {
-@@@ let name = args.inner.first().cloned().unwrap_or_default();
-@@@ ResultName::new(name).to_render()
+@@@ let name = args.0.first().cloned().unwrap_or_default();
+@@@ ResultName(name).to_render()
@@@}
#[test]
fn test_with_entry_macro() {
@@ -90,7 +94,7 @@ fn test_with_entry_macro() {
let entry = entry!("--name", "Alice");
let chain_process = handle_hello(entry).into();
let result_name = unpack_chain_process!(chain_process, ResultName);
- assert_eq!(result_name.inner, "Alice");
+ assert_eq!(result_name.0, "Alice");
}
```
@@ -103,23 +107,24 @@ fn test_with_entry_macro() {
@@@#[derive(Default, Clone)]
@@@struct ResPrefix(String);
@@@dispatcher!("hello", EntryHello);
-@@@pack!(ResultGreeting = String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultGreeting(String);
@@@
#[chain]
fn handle_hello(args: EntryHello, prefix: &ResPrefix) -> Next {
- let name = args.inner.first().cloned().unwrap_or_default();
- ResultGreeting::new(format!("{}, {}", prefix.0, name)).to_render()
+ let name = args.0.first().cloned().unwrap_or_default();
+ ResultGreeting(format!("{}, {}", prefix.0, name)).to_render()
}
#[test]
fn test_handle_with_resource() {
// 资源需要在测试中手动传入
let result = handle_hello(
- EntryHello::new(vec!["World".to_string()]),
+ EntryHello(vec!["World".to_string()]),
&ResPrefix("Hello".to_string()),
);
let greeting = unpack_chain_process!(result, ResultGreeting, ThisProgram);
- assert_eq!(greeting.inner, "Hello, World");
+ assert_eq!(greeting.0, "Hello, World");
}
```
diff --git a/docs/_zh_CN/pages/2-define-a-dispatcher.md b/docs/_zh_CN/pages/2-define-a-dispatcher.md
index 7ae26f1..77a1513 100644
--- a/docs/_zh_CN/pages/2-define-a-dispatcher.md
+++ b/docs/_zh_CN/pages/2-define-a-dispatcher.md
@@ -48,17 +48,15 @@ dispatcher!("remote.rm", EntryRemoteRm);
```rust
// 示意,dispatcher! 宏实际生成的代码
-pub struct EntryGreet {
- pub inner: Vec<String>,
-}
+pub struct EntryGreet(pub Vec<String>);
```
-用户在命令行输入 `greet Alice Bob`,`EntryGreet.inner` 就是 `vec!["Alice", "Bob"]`。
+用户在命令行输入 `greet Alice Bob`,`EntryGreet` 包裹的 `Vec<String>`(即字段 `0`)就是 `vec!["Alice", "Bob"]`。
> [!IMPORTANT]
-> Entry 的 `inner` 只包含 **匹配后剩余的参数**。
+> Entry 包裹的参数只包含 **匹配后剩余的参数**。
>
-> 以 `remote add origin` 为例,`remote` 和 `add` 用于匹配命令路径,只有 `origin` 会进入 `EntryRemoteAdd.inner`。
+> 以 `remote add origin` 为例,`remote` 和 `add` 用于匹配命令路径,只有 `origin` 会进入 `EntryRemoteAdd`(即字段 `0`)。
## 进阶:隐式声明
diff --git a/docs/_zh_CN/pages/3-define-a-chain.md b/docs/_zh_CN/pages/3-define-a-chain.md
index c8d8a24..3356b74 100644
--- a/docs/_zh_CN/pages/3-define-a-chain.md
+++ b/docs/_zh_CN/pages/3-define-a-chain.md
@@ -17,14 +17,15 @@
```rust
@@@dispatcher!("greet", EntryGreet);
-pack!(ResultName = String);
+#[derive(Grouped, Wrap)]
+pub struct ResultName(String);
#[chain]
fn handle_greet(args: EntryGreet) -> Next {
// args 就是用户输入经过匹配后剩下的参数
- let name = args.inner.first().cloned().unwrap_or_else(|| "World".to_string());
+ let name = args.0.first().cloned().unwrap_or_else(|| "World".to_string());
// 把结果包装成 Next,告诉调度器下一步去哪
- ResultName::new(name).into()
+ ResultName(name).into()
}
```
@@ -32,7 +33,7 @@ fn handle_greet(args: EntryGreet) -> Next {
Chain 函数签名里写着它需要什么——`args: EntryGreet`
-然后用 `ResultName::new(name)` 返回一个新类型。
+然后用 `ResultName(name)` 返回一个新类型。
这个返回的 `Next` 会展开成 `impl Into<ChainProcess<ThisProgram>>`。
@@ -41,17 +42,30 @@ Chain 函数签名里写着它需要什么——`args: EntryGreet`
>
> 可以去 [任意输出机制](pages/concepts/3-any-output) 章节了解 `ChainProcess`。
-## `pack!` 宏
+## 用 `#[derive]` 定义管线类型
-你大概猜到了,`pack!(ResultName = String)` 定义了一个管线中传递的类型:
+你大概猜到了,`#[derive(Grouped, Wrap)] pub struct ResultName(String);` 定义了一个管线中传递的类型:
```rust
-// pack!(ResultName = String) 大概生成了这样的代码
+// 实际写代码时只需一行 #[derive(Grouped, Wrap)],它大概展开成下面这些实现:
-#[derive(Grouped)]
-pub struct ResultName {
- pub inner: String,
+pub struct ResultName(String);
+
+impl From<String> for ResultName {
+ fn from(inner: String) -> Self {
+ ResultName(inner)
+ }
+}
+
+impl std::ops::Deref for ResultName {
+ type Target = String;
+ fn deref(&self) -> &Self::Target {
+ &self.0
+ }
}
+
+// Grouped 生成 member_id() → ThisProgram::ResultName,
+// 赋予类型路由身份和 Into<ChainProcess> 转换。
```
你可以把它理解为一个 打了标签的 `String`。
@@ -59,7 +73,7 @@ pub struct ResultName {
调度器通过这个标签来精确路由,确保数据不会混淆 —— 比如发给 `RenderGreet` 的数据不会被误传给 `RenderError`。
> [!NOTE]
-> 与简单的类型别名 (`type`) 不同,`pack!` 会生成一个全新的类型,拥有独立的 `TypeId`。
+> 与简单的类型别名 (`type`) 不同,`#[derive(Grouped, Wrap)]` 会定义一个全新的类型,拥有独立的 `TypeId`。
命名上推荐这样的习惯:
@@ -70,25 +84,26 @@ pub struct ResultName {
| 最终结果 | `Result` + 描述 | `ResultGreetSomeone` |
| 错误 | `Error` + 描述 | `ErrorUserNotFound` |
-详见 [命名规范](pages/other/naming_rule),不过现在你只需要记住:**用 `pack!` 给你的数据取一个有意义的名字**。
+详见 [命名规范](pages/other/naming_rule),不过现在你只需要记住:**用 `#[derive(Grouped)]`(可搭配 `Wrap`)给你的数据取一个有意义的名字**。
## 从 Entry 中提取参数
-`EntryGreet` 的 `inner` 是一个 `Vec<String>`,你可以在 Chain 里自由地处理它:
+`EntryGreet` 包裹的 `Vec<String>`(即字段 `0`)你可以在 Chain 里自由地处理它:
```rust
@@@dispatcher!("greet", EntryGreet);
-@@@pack!(ResultName = String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultName(String);
#[chain]
fn handle_greet(args: EntryGreet) -> Next {
// 取第一个参数,没有就用默认值
let name = args
- .inner
+ .0
.first()
.cloned()
.unwrap_or_else(|| "World".to_string());
- ResultName::new(name).into()
+ ResultName(name).into()
}
```
@@ -103,16 +118,17 @@ fn handle_greet(args: EntryGreet) -> Next {
dispatcher!("greet", EntryGreet);
// 2. 声明管线中的数据类型
-pack!(ResultName = String);
+#[derive(Grouped, Wrap)]
+pub struct ResultName(String);
// 3. 处理逻辑
#[chain]
fn handle_greet(args: EntryGreet) -> Next {
- let name = args.inner
+ let name = args.0
.first()
.cloned()
.unwrap_or_else(|| "World".to_string());
- ResultName::new(name).into()
+ ResultName(name).into()
}
fn main() {
diff --git a/docs/_zh_CN/pages/4-render-result.md b/docs/_zh_CN/pages/4-render-result.md
index e3e49f5..ad915ba 100644
--- a/docs/_zh_CN/pages/4-render-result.md
+++ b/docs/_zh_CN/pages/4-render-result.md
@@ -3,7 +3,7 @@
使用 renderer 宏声明渲染器,将结果输出
</p>
-现在,我们创建了 Dispatcher 和 Chain,也通过 `pack!` 产出了一个 Result 类型。最后一步:**把结果展示给用户**。
+现在,我们创建了 Dispatcher 和 Chain,也通过 `#[derive(Grouped, Wrap)]` 产出了一个 Result 类型。最后一步:**把结果展示给用户**。
## `#[renderer]` 宏
@@ -11,7 +11,8 @@
```rust
@@@use mingling::macros::buffer;
-@@@pack!(ResultName = String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultName(String);
#[renderer(buffer)]
fn render_name(name: ResultName) {
r_println!("Hello, {}!", *name);
@@ -27,7 +28,8 @@ Renderer 接收 Chain 产出的结果,然后返回一个 `RenderResult`。在
```rust
use mingling::macros::buffer;
-@@@pack!(ResultName = String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultName(String);
#[renderer(buffer)]
fn render_name(name: ResultName) {
r_println!("Hello, {}!", *name);
@@ -54,17 +56,18 @@ use mingling::macros::buffer;
// 1. 用 Dispatcher 声明命令
dispatcher!("greet", EntryGreet);
-// 2. 用 pack! 声明结果数据
-pack!(ResultName = String);
+// 2. 用 #[derive(Grouped, Wrap)] 声明结果数据
+#[derive(Grouped, Wrap)]
+pub struct ResultName(String);
// 3. 用 Chain 处理逻辑
#[chain]
fn handle_greet(args: EntryGreet) -> Next {
- let name = args.inner
+ let name = args.0
.first()
.cloned()
.unwrap_or_else(|| "World".to_string());
- ResultName::new(name).into()
+ ResultName(name).into()
}
// 4. 用 Renderer 输出结果
@@ -122,10 +125,10 @@ use mingling::macros::buffer;
#[renderer(buffer)]
fn render_entry_fallback(err: EntryFallback) {
- if err.inner.is_empty() {
+ if err.0.is_empty() {
r_println!("Unknown command");
} else {
- r_println!("Command not found: \"{}\"", err.inner.join(" "));
+ r_println!("Command not found: \"{}\"", err.0.join(" "));
}
}
```
@@ -144,13 +147,13 @@ Command not found: "great"
你完成了第一个完整的 Mingling 程序!来回顾一下学到的东西:
-| 概念 | 对应宏/函数 | 一句话 |
-| -------- | ---------------- | -------------------------- |
-| 声明命令 | `dispatcher!` | 告诉程序用户能输入什么 |
-| 处理逻辑 | `#[chain]` | 收到参数后做什么 |
-| 输出结果 | `#[renderer]` | 怎么把结果告诉用户 |
-| 类型包装 | `pack!` | 给你的数据取个有意义的名字 |
-| 程序入口 | `gen_program!()` | 自动生成管线的接线图 |
+| 概念 | 对应宏/函数 | 一句话 |
+| -------- | -------------------------- | -------------------------- |
+| 声明命令 | `dispatcher!` | 告诉程序用户能输入什么 |
+| 处理逻辑 | `#[chain]` | 收到参数后做什么 |
+| 输出结果 | `#[renderer]` | 怎么把结果告诉用户 |
+| 类型包装 | `#[derive(Grouped, Wrap)]` | 给你的数据取个有意义的名字 |
+| 程序入口 | `gen_program!()` | 自动生成管线的接线图 |
在真实项目中你还会用到资源注入、hook、补全、REPL 等高级功能,不过核心骨架永远不变:**Dispatcher → Chain → Renderer**。
diff --git a/docs/_zh_CN/pages/5-multiple-commands.md b/docs/_zh_CN/pages/5-multiple-commands.md
index e0a58e7..9d9d37e 100644
--- a/docs/_zh_CN/pages/5-multiple-commands.md
+++ b/docs/_zh_CN/pages/5-multiple-commands.md
@@ -15,19 +15,21 @@
dispatcher!("greet", EntryGreet);
dispatcher!("add", EntryAdd);
-pack!(ResultGreeting = String);
-pack!(ResultSum = i32);
+#[derive(Grouped, Wrap)]
+pub struct ResultGreeting(String);
+#[derive(Grouped, Wrap)]
+pub struct ResultSum(i32);
#[chain]
fn handle_greet(args: EntryGreet) -> Next {
- let name = args.inner.first().cloned().unwrap_or_else(|| "World".to_string());
- ResultGreeting::new(name).into()
+ let name = args.0.first().cloned().unwrap_or_else(|| "World".to_string());
+ ResultGreeting(name).into()
}
#[chain]
fn handle_add(args: EntryAdd) -> Next {
- let sum: i32 = args.inner.iter().filter_map(|s| s.parse::<i32>().ok()).sum();
- ResultSum::new(sum).into()
+ let sum: i32 = args.0.iter().filter_map(|s| s.parse::<i32>().ok()).sum();
+ ResultSum(sum).into()
}
#[renderer(buffer)]
@@ -70,10 +72,10 @@ dispatcher!("remote.rm", EntryRemoteRm);
## 数据类型的独立性
-注意我们用了两个不同的 `pack!`:
+注意我们用了两个不同的类型:
-- `pack!(ResultGreeting = String)`
-- `pack!(ResultSum = i32)`
+- `#[derive(Grouped, Wrap)] pub struct ResultGreeting(String);`
+- `#[derive(Grouped, Wrap)] pub struct ResultSum(i32);`
它们都是独立的类型,`gen_program!()` 会给它们分配不同的枚举变体。
diff --git a/docs/_zh_CN/pages/6-argument-parse-picker.md b/docs/_zh_CN/pages/6-argument-parse-picker.md
index 7944d0a..6c88423 100644
--- a/docs/_zh_CN/pages/6-argument-parse-picker.md
+++ b/docs/_zh_CN/pages/6-argument-parse-picker.md
@@ -3,7 +3,7 @@
用 Picker 完成基本的参数解析
</p>
-前面教程中我们都是手动从 `EntryGreet.inner`(`Vec<String>`)中提取参数。
+前面教程中我们都是手动从 `EntryGreet.0`(`Vec<String>`)中提取参数。
```rust
@@@ fn main() {
@@ -27,14 +27,15 @@ features = ["picker"]
```rust
// Features: ["picker"]
@@@dispatcher!("greet", EntryGreet);
-@@@pack!(ResultName = String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultName(String);
#[chain]
fn handle_greet_entry(prev: EntryGreet) -> Next {
let name = prev
.pick_or(&arg![String], || "World".to_string())
.unwrap();
- ResultName::new(name).into()
+ ResultName(name).into()
}
```
@@ -45,13 +46,14 @@ fn handle_greet_entry(prev: EntryGreet) -> Next {
```rust
// Features: ["picker"]
@@@dispatcher!("greet", EntryGreet);
-@@@pack!(ResultName = String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultName(String);
@@@#[chain]
@@@fn handle_greet_entry(prev: EntryGreet) -> Next {
let name = prev
.pick_or(&arg![String], || "World".to_string())
.unwrap();
-@@@ResultName::new(name).into()
+@@@ResultName(name).into()
@@@}
```
@@ -60,7 +62,8 @@ let name = prev
```rust
// Features: ["picker"]
@@@dispatcher!("greet", EntryGreet);
-@@@pack!(ResultName = String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultName(String);
@@@#[chain]
@@@fn handle_greet_entry(prev: EntryGreet) {
@@@let name: String =
@@ -81,14 +84,15 @@ let name = prev
```rust
// Features: ["picker"]
@@@dispatcher!("greet", EntryGreet);
-@@@pack!(ResultName = String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultName(String);
#[chain]
fn handle_greet_entry(prev: EntryGreet) -> Next {
let name = prev
.pick_or(&arg![name: String, 'n'], || "World".to_string())
.unwrap();
- ResultName::new(name).into()
+ ResultName(name).into()
}
```
@@ -99,7 +103,8 @@ fn handle_greet_entry(prev: EntryGreet) -> Next {
```rust
// Features: ["picker"]
@@@dispatcher!("greet", EntryGreet);
-@@@pack!(ResultName = String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultName(String);
@@@#[chain]
@@@fn handle_greet_entry(prev: EntryGreet) {
@@@let name: String =
@@ -122,7 +127,8 @@ fn handle_greet_entry(prev: EntryGreet) -> Next {
```rust
// Features: ["picker"]
@@@dispatcher!("test", EntryTest);
-@@@pack!(ResultInfo = (String, u8, u32));
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultInfo((String, u8, u32));
#[chain]
fn handle_test_entry(prev: EntryTest) -> Next {
@@ -132,7 +138,7 @@ fn handle_test_entry(prev: EntryTest) -> Next {
.pick_or_default(&arg![id: u32, 'I'])
.unwrap();
- ResultInfo::new((name, age, id)).into()
+ ResultInfo((name, age, id)).into()
}
```
@@ -150,8 +156,10 @@ fn handle_test_entry(prev: EntryTest) -> Next {
@@@use mingling::macros::buffer;
@@@use mingling::macros::route;
@@@dispatcher!("greet", EntryGreet);
-@@@pack!(ResultName = String);
-@@@pack!(ErrorNoName = ());
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultName(String);
+@@@#[derive(Grouped, Wrap, Default)]
+@@@pub struct ErrorNoName(());
#[chain]
fn handle_greet_entry(prev: EntryGreet) -> Next {
@@ -162,7 +170,7 @@ fn handle_greet_entry(prev: EntryGreet) -> Next {
})
.to_result()
);
- ResultName::new(name).into()
+ ResultName(name).into()
}
#[renderer(buffer)]
@@ -177,12 +185,13 @@ fn render_greet(result: ResultName) {
```rust
// Features: ["picker", "extras"]
-@@@ pack!(ErrorFail = ());
+@@@ #[derive(Grouped, Wrap)]
+@@@ pub struct ErrorFail(());
@@@ use mingling::macros::route;
@@@ use mingling::picker::IntoPicker;
@@@ fn func() -> mingling::ChainProcess<ThisProgram> {
@@@ let args: Vec<String> = vec![];
-let name = route!(args.pick_or_route(&arg![String], || ErrorFail::new(()).to_chain()).to_result());
+let name = route!(args.pick_or_route(&arg![String], || ErrorFail(()).to_chain()).to_result());
@@@ mingling::macros::empty_result!()
@@@ }
```
@@ -191,11 +200,12 @@ let name = route!(args.pick_or_route(&arg![String], || ErrorFail::new(()).to_cha
```rust
// Features: ["picker", "extras"]
-@@@ pack!(ErrorFail = ());
+@@@ #[derive(Grouped, Wrap)]
+@@@ pub struct ErrorFail(());
@@@ use mingling::picker::IntoPicker;
@@@ fn func() -> mingling::ChainProcess<ThisProgram> {
@@@ let args: Vec<String> = vec![];
-let name = match args.pick_or_route(&arg![String], || ErrorFail::new(()).to_chain()).to_result() {
+let name = match args.pick_or_route(&arg![String], || ErrorFail(()).to_chain()).to_result() {
Ok(r) => r,
Err(e) => return e,
};
@@ -210,7 +220,8 @@ let name = match args.pick_or_route(&arg![String], || ErrorFail::new(()).to_chai
```rust
// Features: ["picker"]
@@@dispatcher!("greet", EntryGreet);
-@@@pack!(ResultName = String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultName(String);
#[chain]
fn handle_greet_entry(prev: EntryGreet) -> Next {
@@ -225,7 +236,7 @@ fn handle_greet_entry(prev: EntryGreet) -> Next {
})
.unwrap();
- ResultName::new(name).into()
+ ResultName(name).into()
}
```
@@ -237,7 +248,8 @@ fn handle_greet_entry(prev: EntryGreet) -> Next {
// Features: ["picker"]
@@@use mingling::picker::value::Flag;
@@@dispatcher!("test", EntryTest);
-@@@pack!(ResultDone = ());
+@@@#[derive(Grouped, Wrap, Default)]
+@@@pub struct ResultDone(());
#[chain]
fn handle_entry(prev: EntryTest) -> Next {
@@ -280,12 +292,13 @@ impl SinglePickable for Address {
}
}
@@@dispatcher!("connect", EntryConnect);
-@@@pack!(ResultConnected = Address);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultConnected(Address);
#[chain]
fn handle_connect_entry(prev: EntryConnect) -> Next {
let address: Address = prev.pick_or_default(&arg![Address]).unwrap();
- ResultConnected::new(address).into()
+ ResultConnected(address).into()
}
#[renderer(buffer)]
@@ -333,12 +346,13 @@ impl SinglePickable for Fruits {
}
}
@@@dispatcher!("eat", EntryEat);
-@@@pack!(ResultFruit = Fruits);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultFruit(Fruits);
#[chain]
fn handle_eat_entry(prev: EntryEat) -> Next {
let fruit: Fruits = prev.pick_or_default(&arg![Fruits]).unwrap();
- ResultFruit::new(fruit).into()
+ ResultFruit(fruit).into()
}
#[renderer(buffer)]
diff --git a/docs/_zh_CN/pages/9-error-handling.md b/docs/_zh_CN/pages/9-error-handling.md
index dce48d1..463b829 100644
--- a/docs/_zh_CN/pages/9-error-handling.md
+++ b/docs/_zh_CN/pages/9-error-handling.md
@@ -20,17 +20,19 @@
```rust
@@@dispatcher!("greet", EntryGreet);
-pack!(ResultGreeting = String);
-pack!(ErrorNameEmpty = String);
+#[derive(Grouped, Wrap)]
+pub struct ResultGreeting(String);
+#[derive(Grouped, Wrap)]
+pub struct ErrorNameEmpty(String);
#[chain]
fn handle_greet(args: EntryGreet) -> Next {
- let name = args.inner.first().cloned().unwrap_or_default();
+ let name = args.0.first().cloned().unwrap_or_default();
if name.is_empty() {
- ErrorNameEmpty::new("name is required".to_string()).to_render()
+ ErrorNameEmpty("name is required".to_string()).to_render()
} else {
- ResultGreeting::new(name).to_render()
+ ResultGreeting(name).to_render()
}
}
```
@@ -40,9 +42,11 @@ fn handle_greet(args: EntryGreet) -> Next {
```rust
@@@use mingling::macros::buffer;
@@@dispatcher!("greet", EntryGreet);
-@@@pack!(ResultGreeting = String);
-@@@pack!(ErrorNameEmpty = String);
-@@@#[chain] fn handle_greet(args: EntryGreet) -> Next { ResultGreeting::new(args.inner.first().cloned().unwrap_or_default()).to_render() }
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ResultGreeting(String);
+@@@#[derive(Grouped, Wrap)]
+@@@pub struct ErrorNameEmpty(String);
+@@@#[chain] fn handle_greet(args: EntryGreet) -> Next { ResultGreeting(args.0.first().cloned().unwrap_or_default()).to_render() }
#[renderer(buffer)]
fn render_greet(result: ResultGreeting) {
@@ -63,16 +67,18 @@ fn render_error_name_empty(err: ErrorNameEmpty) {
@@@use mingling::macros::buffer;
dispatcher!("greet", EntryGreet);
-pack!(ResultGreeting = String);
-pack!(ErrorNameEmpty = String);
+#[derive(Grouped, Wrap)]
+pub struct ResultGreeting(String);
+#[derive(Grouped, Wrap)]
+pub struct ErrorNameEmpty(String);
#[chain]
fn handle_greet(args: EntryGreet) -> Next {
- let name = args.inner.first().cloned().unwrap_or_default();
+ let name = args.0.first().cloned().unwrap_or_default();
if name.is_empty() {
- ErrorNameEmpty::new("name is required".to_string()).to_render()
+ ErrorNameEmpty("name is required".to_string()).to_render()
} else {
- ResultGreeting::new(name).to_render()
+ ResultGreeting(name).to_render()
}
}
@@ -104,14 +110,14 @@ Hello, Alice!
Error: name is required
```
-## 关于 `pack_err!`
+## 关于错误类型
-如果你启用了 `extras`,还可以用 `pack_err!` 快速声明带有自动 `name` 字段的错误类型:
+不需要额外上下文、只起“标记”作用的错误类型,可以直接用 `#[derive(Grouped, Default)]` 声明:
```rust
// Features: ["extras"]
-pack_err!(ErrorNotFound);
-// 生成: struct ErrorNotFound { pub name: String }
+#[derive(Grouped, Default)]
+pub struct ErrorNotFound;
```
详见 [特性列表](pages/other/features)。
diff --git a/docs/_zh_CN/pages/advanced/2-structural-renderer.md b/docs/_zh_CN/pages/advanced/2-structural-renderer.md
index f2e1717..f678e2f 100644
--- a/docs/_zh_CN/pages/advanced/2-structural-renderer.md
+++ b/docs/_zh_CN/pages/advanced/2-structural-renderer.md
@@ -21,7 +21,7 @@ features = ["structural_renderer"]
## 基本用法
-启用 `StructuralRendererSetup` 后,用 `pack_structural!` 替代 `pack!` 来声明支持结构化输出的类型:
+启用 `StructuralRendererSetup` 后,用 `#[derive(StructuralData)]`(搭配 `serde::Serialize`、`Grouped` 和 `Wrap`)来声明支持结构化输出的类型:
```rust
// Features: ["structural_renderer"]
@@ -29,16 +29,18 @@ features = ["structural_renderer"]
// serde = "1"
@@@use mingling::macros::buffer;
@@@use mingling::setup::StructuralRendererSetup;
+@@@use mingling::StructuralData;
@@@dispatcher!("render", EntryRender);
-// pack_structural! 等价于 pack! + StructuralData
-pack_structural!(ResultInfo = (String, i32));
+// #[derive(Grouped, Wrap)] + StructuralData + serde::Serialize 等价于旧版的 pack_structural!
+#[derive(serde::Serialize, StructuralData, Grouped, Wrap)]
+pub struct ResultInfo((String, i32));
#[chain]
fn handle_render(args: EntryRender) -> Next {
- let name = args.inner.first().cloned().unwrap_or_default();
- let age = args.inner.get(1).and_then(|s| s.parse().ok()).unwrap_or(0);
- ResultInfo::new((name, age)).into()
+ let name = args.0.first().cloned().unwrap_or_default();
+ let age = args.0.get(1).and_then(|s| s.parse().ok()).unwrap_or(0);
+ ResultInfo((name, age)).into()
}
#[renderer(buffer)]
@@ -61,7 +63,7 @@ fn render_info(r: ResultInfo) {
## 自定义输出结构
-`pack_structural!` 的默认输出包含 `inner` 字段。要完全控制输出结构,可以用 `#[derive(StructuralData, Serialize, Grouped)]` 手动定义类型:
+用 `#[derive(Grouped, Wrap)]` 包装的元组结构体默认输出包含 `inner` 字段。要完全控制输出结构,可以用 `#[derive(StructuralData, Serialize, Grouped)]` 手动定义类型:
```rust
// Features: ["structural_renderer"]
@@ -82,8 +84,8 @@ struct Info {
#[chain]
fn handle_render(args: EntryRender) -> Next {
- let name = args.inner.first().cloned().unwrap_or_default();
- let age = args.inner.get(1).and_then(|s| s.parse().ok()).unwrap_or(0);
+ let name = args.0.first().cloned().unwrap_or_default();
+ let age = args.0.get(1).and_then(|s| s.parse().ok()).unwrap_or(0);
Info { name, age }.to_render()
}
diff --git a/docs/_zh_CN/pages/concepts/2-resource.md b/docs/_zh_CN/pages/concepts/2-resource.md
index 1052254..154fa7d 100644
--- a/docs/_zh_CN/pages/concepts/2-resource.md
+++ b/docs/_zh_CN/pages/concepts/2-resource.md
@@ -34,7 +34,8 @@
```rust
@@@ use mingling::res::ResExitCode;
-@@@ pack!(ErrorFileNotFound = ());
+@@@ #[derive(Grouped, Wrap)]
+@@@ pub struct ErrorFileNotFound(());
#[chain]
fn handle_error_file_not_found(
error: ErrorFileNotFound,
diff --git a/docs/_zh_CN/pages/concepts/3-any-output.md b/docs/_zh_CN/pages/concepts/3-any-output.md
index 118e856..1a2164c 100644
--- a/docs/_zh_CN/pages/concepts/3-any-output.md
+++ b/docs/_zh_CN/pages/concepts/3-any-output.md
@@ -20,7 +20,7 @@ AnyOutput<G>
这里的 `G` 就是 `gen_program!()` 生成的程序枚举(也就是你熟知的 `ThisProgram`)。
-每个被 `pack!` 或 `#[derive(Grouped)]` 标记的类型都被分配到这个枚举的一个变体。
+每个被 `#[derive(Grouped)]`(可搭配 `Wrap`)标记的类型都被分配到这个枚举的一个变体。
## ChainProcess:数据 + 路由
@@ -48,7 +48,7 @@ trait Grouped<G> {
}
```
-当你用 `pack!(ResultName = String)` 时,宏自动为 `ResultName` 实现 `Grouped`,`member_id()` 返回枚举中对应的变体。调度器一看 `member_id`,就去找对应的 Chain 或 Renderer。
+当你用 `#[derive(Grouped, Wrap)] pub struct ResultName(String);` 时,派生宏自动为 `ResultName` 实现 `Grouped`,`member_id()` 返回枚举中对应的变体。调度器一看 `member_id`,就去找对应的 Chain 或 Renderer。
`to_chain()` 和 `to_render()` 本质上是 `AnyOutput` 的快捷方法,分别构造 `ChainProcess::Ok(any, Chain)` 和 `ChainProcess::Ok(any, Renderer)`。
@@ -66,7 +66,7 @@ trait Grouped<G> {
> [!TIP]
> 日常开发中你不需要手动操作 `AnyOutput` 或 `ChainProcess`。
>
-> `pack!`、`#[chain]`、`#[renderer]` 这些宏帮你处理了所有的包装和解包。
+> `#[derive(Grouped)]`、`#[chain]`、`#[renderer]` 这些宏帮你处理了所有的包装和解包。
<p align="center" style="font-size: 0.85em; color: gray;">
Written by @Weicao-CatilGrass
diff --git a/docs/_zh_CN/pages/concepts/4-program-collect.md b/docs/_zh_CN/pages/concepts/4-program-collect.md
index a0236f6..616f645 100644
--- a/docs/_zh_CN/pages/concepts/4-program-collect.md
+++ b/docs/_zh_CN/pages/concepts/4-program-collect.md
@@ -9,7 +9,7 @@
### 1. 生成枚举
-扫描当前模块中所有 `pack!`、`#[chain]`、`#[renderer]` 等宏标记的类型,为每个类型生成一个枚举变体。
+扫描当前模块中所有 `#[derive(Grouped)]`、`#[chain]`、`#[renderer]` 等宏标记的类型,为每个类型生成一个枚举变体。
这个枚举就是 `AnyOutput<G>` 中 `G` 的类型 —— 调度器靠枚举变体来区分管线中传递的不同数据。
diff --git a/docs/_zh_CN/pages/other/features.md b/docs/_zh_CN/pages/other/features.md
index 30231ce..5fa7c86 100644
--- a/docs/_zh_CN/pages/other/features.md
+++ b/docs/_zh_CN/pages/other/features.md
@@ -80,11 +80,12 @@ features = ["build_full"]
```rust
// Features: ["async"]
-pack!(StateFoo = ());
+#[derive(Grouped, Wrap)]
+pub struct StateFoo(());
#[chain]
async fn handle_state_foo(foo: StateFoo) -> Next {
- StateFoo::new(()).into()
+ StateFoo(()).into()
}
```
@@ -151,14 +152,13 @@ build_comp_scripts("myprogram").unwrap();
例如,允许 `dispatcher!("greet")` 的缩写形式,自动生成 `CMDGreet` / `EntryGreet`。
-| 宏 | 说明 |
-| ------------------------------------------------------- | -------------------------------------- |
-| `empty_result!()` | 链中提前返回空结果的简写 |
-| `entry!(Type, ["a", "b"])` | 构造入口类型的测试数据 |
-| `group!(Type)` | 将外部类型注册为组成员,无需修改其定义 |
-| `pack_err!(ErrorType)` / `pack_err!(ErrorType = Inner)` | 创建带自动 `name` 字段的错误类型 |
-| `#[program_setup]` | 声明程序初始化函数 |
-| `dispatcher!("cmd.path")` **缩写形式** | 省略 `EntryStruct`,入口类型名自动推导 |
+| 宏 | 说明 |
+| -------------------------------------- | -------------------------------------- |
+| `empty_result!()` | 链中提前返回空结果的简写 |
+| `entry!(Type, ["a", "b"])` | 构造入口类型的测试数据 |
+| `group!(Type)` | 将外部类型注册为组成员,无需修改其定义 |
+| `#[program_setup]` | 声明程序初始化函数 |
+| `dispatcher!("cmd.path")` **缩写形式** | 省略 `EntryStruct`,入口类型名自动推导 |
<details>
<summary> Details </summary>
@@ -168,10 +168,13 @@ build_comp_scripts("myprogram").unwrap();
```rust
// Features: ["extras"]
-pack!(StatePrev1 = ());
-pack!(StatePrev2 = ());
+#[derive(Grouped, Wrap)]
+pub struct StatePrev1(());
+#[derive(Grouped, Wrap)]
+pub struct StatePrev2(());
-pack!(StateNext = ());
+#[derive(Grouped, Wrap)]
+pub struct StateNext(());
#[chain]
fn handle_state_prev2(_p: StatePrev2) {
@@ -186,7 +189,7 @@ fn handle_state_prev1(_p: StatePrev1) -> Next {
// 当需要 Next 且不需要返回值,便可以使用它
empty_result!()
} else {
- StateNext::new(()).into()
+ StateNext(()).into()
}
}
```
@@ -217,7 +220,8 @@ fn no_error_setup(program: &mut Program<ThisProgram>) {
// Features: ["extras"]
use mingling::macros::entry;
-pack!(EntryHello = Vec<String>);
+#[derive(Grouped, Wrap)]
+pub struct EntryHello(Vec<String>);
fn main() {
let result: Next = handle_hello(entry!("--name", "Bob")).into();
@@ -231,7 +235,7 @@ fn handle_hello(args: EntryHello) {}
### `group!`
将外部类型注册为程序组成员,无需修改原始类型的定义。
-类型名会直接作为枚举变体,与 `pack!` 或 `#[derive(Grouped)]` 一致。
+类型名会直接作为枚举变体,与 `#[derive(Grouped)]` 一致。
```rust
// Features: ["extras"]
@@ -243,26 +247,23 @@ use std::num::ParseIntError;
group!(std::num::ParseIntError);
```
-### `pack_err!`
+### 定义错误类型
-创建带自动 `name: String` 字段的错误结构体,字段值自动设为结构体名的蛇形命名。
-可选择包裹一个内部类型以携带额外上下文。
+0.5.0 起 `pack_err!` 已移除,错误类型直接用 derive 声明:
+不携带额外上下文时用 `#[derive(Grouped, Default)]`(仅作标记),或
+用 `#[derive(Grouped, Wrap)]` 包裹一个内部类型以携带上下文。
```rust
// Features: ["extras"]
use std::path::PathBuf;
-// 简单形式——仅包含 name 字段:
-pack_err!(ErrorNotFound);
-// 生成:
-// struct ErrorNotFound { pub name: String }
-// impl Default for ErrorNotFound { ... }
+// 简单形式——只作为标记使用:
+#[derive(Grouped, Default)]
+pub struct ErrorNotFound;
-// 带类型的形式——包含额外的 info 字段:
-pack_err!(ErrorNotDir = PathBuf);
-// 生成:
-// struct ErrorNotDir { pub name: String, pub info: PathBuf }
-// impl ErrorNotDir { pub fn new(info: PathBuf) -> Self { ... } }
+// 带类型的形式——包裹一个内部类型以携带上下文:
+#[derive(Grouped, Wrap)]
+pub struct ErrorNotDir(PathBuf);
```
</details>
diff --git a/docs/_zh_CN/pages/other/naming_rule.md b/docs/_zh_CN/pages/other/naming_rule.md
index 1bca8f6..7694f56 100644
--- a/docs/_zh_CN/pages/other/naming_rule.md
+++ b/docs/_zh_CN/pages/other/naming_rule.md
@@ -94,7 +94,7 @@ Result + 内容
| `ResultGreetSomeone` | 问候结果 |
| `ResultFruitList` | 水果列表结果 |
-结果结构体期望被 Renderer 消费,内部结构应该为了渲染美观而设计。一般用 `#[derive(Grouped)]` 代替 `pack!()` 包装,以获得更灵活的字段控制。
+结果结构体期望被 Renderer 消费,内部结构应该为了渲染美观而设计。一般用 `#[derive(Grouped)]` 标注结构体,以获得更灵活的字段控制。
### 错误
@@ -146,7 +146,8 @@ Error + 描述
| 资源(可变) | `counter`、`cache`、`session` 等 |
```rust
-@@@ pack!(EntryRemoteAdd = Vec<String>);
+@@@ #[derive(Grouped, Wrap)]
+@@@ pub struct EntryRemoteAdd(Vec<String>);
@@@ #[derive(Default, Clone)]
@@@ struct ResDatabase { }
@@@ #[derive(Default, Clone)]
@@ -168,9 +169,12 @@ fn handle_remote_add(args: EntryRemoteAdd, cwd: &ResCurrentDir, db: &mut ResData
@@@ #[derive(Default, Clone)]
@@@ struct ResDatabase { }
@@@ impl ResDatabase { fn has_remote(&self, remote: &String) -> bool { true } }
-@@@ pack!(StateOperationRemotes = String);
-@@@ pack!(ResultRemoteAdded = String);
-@@@ pack!(ErrorRepositoryNotFound = String);
+@@@ #[derive(Grouped, Wrap, Default)]
+@@@ pub struct StateOperationRemotes(String);
+@@@ #[derive(Grouped, Wrap)]
+@@@ pub struct ResultRemoteAdded(String);
+@@@ #[derive(Grouped, Wrap)]
+@@@ pub struct ErrorRepositoryNotFound(String);
// 分发器
dispatcher!("remote.add", EntryRemoteAdd);
@@ -183,23 +187,24 @@ fn handle_remote_add(args: EntryRemoteAdd) -> Next {
// 状态 → 错误或结果
#[chain]
fn handle_state_operation_remotes(state: StateOperationRemotes, db: &ResDatabase) -> Next {
- if db.has_remote(&state.inner) {
- ErrorRepositoryNotFound::new(state.inner).to_render()
+ if db.has_remote(&state.0) {
+ ErrorRepositoryNotFound(state.0).to_render()
} else {
- ResultRemoteAdded::new(state.inner).to_render()
+ ResultRemoteAdded(state.0).to_render()
}
}
// 结果渲染
+
#[renderer(buffer)]
fn render_remote_added(result: ResultRemoteAdded) {
- r_println!("Remote added: {}", result.inner);
+ r_println!("Remote added: {}", result.0);
}
// 错误渲染
#[renderer(buffer)]
fn render_error_repository_not_found(err: ErrorRepositoryNotFound) {
- r_println!("Error: remote '{}' not found", err.inner);
+ r_println!("Error: remote '{}' not found", err.0);
}
```