aboutsummaryrefslogtreecommitdiff
path: root/docs/pages/other
diff options
context:
space:
mode:
author魏曹先生 <1992414357@qq.com>2026-08-17 05:49:19 +0800
committer魏曹先生 <1992414357@qq.com>2026-08-17 05:49:19 +0800
commit57c53affe3542cb6bd4e79ee4c18f20a1bd76b2d (patch)
tree1cd4aef44cb7a45a8cd9d520b598f5f181e24c76 /docs/pages/other
parentef23cd944402939605c78a4a853ef6e33af02c21 (diff)
refactor!: replace pack! macros with derive-based pipeline types
Remove the `pack!`, `pack_err!`, `pack_structural!`, and `pack_err_structural!` macros, replacing all pipeline type definitions with `#[derive(Grouped)]` and `#[derive(Grouped, Wrap)]` attributes. This changes the generated struct shape from named-field structs with an `inner` field to tuple structs accessed via `.0`, and removes the auto-generated `name` and `info` fields from error types.
Diffstat (limited to 'docs/pages/other')
-rw-r--r--docs/pages/other/features.md59
-rw-r--r--docs/pages/other/naming_rule.md24
2 files changed, 44 insertions, 39 deletions
diff --git a/docs/pages/other/features.md b/docs/pages/other/features.md
index 3779390..b2c0ea5 100644
--- a/docs/pages/other/features.md
+++ b/docs/pages/other/features.md
@@ -80,11 +80,12 @@ Enables async runtime support, allowing `#[chain]` to bind `async` functions, e.
```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 @@ Enables an additional set of macros, providing more convenient syntactic sugar a
For example, allows the shorthand form `dispatcher!("greet")`, which auto-generates `CMDGreet` / `EntryGreet`.
-| Macro | Description |
-| ------------------------------------------------------- | --------------------------------------------------------------- |
-| `empty_result!()` | Shorthand for returning an empty result early in a chain |
-| `entry!(Type, ["a", "b"])` | Construct test data for an entry type |
-| `group!(Type)` | Register external types as group members without modifying them |
-| `pack_err!(ErrorType)` / `pack_err!(ErrorType = Inner)` | Create error types with an automatic `name` field |
-| `#[program_setup]` | Declare a program initialization function |
-| `dispatcher!("cmd.path")` **shorthand** | Omit `EntryStruct`, the entry name is auto-derived |
+| Macro | Description |
+| --------------------------------------- | --------------------------------------------------------------- |
+| `empty_result!()` | Shorthand for returning an empty result early in a chain |
+| `entry!(Type, ["a", "b"])` | Construct test data for an entry type |
+| `group!(Type)` | Register external types as group members without modifying them |
+| `#[program_setup]` | Declare a program initialization function |
+| `dispatcher!("cmd.path")` **shorthand** | Omit `EntryStruct`, the entry name is auto-derived |
<details>
<summary> Details </summary>
@@ -168,10 +168,13 @@ For example, allows the shorthand form `dispatcher!("greet")`, which auto-genera
```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 {
// When Next is needed but no return value is required, use this
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!`
Registers an external type as a member of the program group without modifying its definition.
-The type's simple name is used as the enum variant, just like `pack!` or `#[derive(Grouped)]`.
+The type's simple name is used as the enum variant, just like `#[derive(Grouped)]`.
```rust
// Features: ["extras"]
@@ -243,26 +247,23 @@ use std::num::ParseIntError;
group!(std::num::ParseIntError);
```
-### `pack_err!`
+### Declaring Error Types
-Creates an error struct with an automatic `name: String` field set to the snake_case
-of the struct name. Optionally wraps an inner type for additional context.
+Error types are declared with derives — the old `pack_err!` macro was removed in 0.5.0.
+Use `#[derive(Grouped, Default)]` for a unit error (no payload), or
+`#[derive(Grouped, Wrap)]` to wrap an inner type for additional context.
```rust
// Features: ["extras"]
use std::path::PathBuf;
-// Simple form — only a name field:
-pack_err!(ErrorNotFound);
-// Generates:
-// struct ErrorNotFound { pub name: String }
-// impl Default for ErrorNotFound { ... }
+// Unit form — no payload:
+#[derive(Grouped, Default)]
+pub struct ErrorNotFound;
-// Typed form — with additional info field:
-pack_err!(ErrorNotDir = PathBuf);
-// Generates:
-// struct ErrorNotDir { pub name: String, pub info: PathBuf }
-// impl ErrorNotDir { pub fn new(info: PathBuf) -> Self { ... } }
+// Typed form — wraps an inner type:
+#[derive(Grouped, Wrap)]
+pub struct ErrorNotDir(PathBuf);
```
</details>
diff --git a/docs/pages/other/naming_rule.md b/docs/pages/other/naming_rule.md
index 770fd10..fb678aa 100644
--- a/docs/pages/other/naming_rule.md
+++ b/docs/pages/other/naming_rule.md
@@ -94,7 +94,7 @@ Result + Content
| `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(Grouped)]` instead of `pack!()` wrapping for more flexible field control.
+Result structs are expected to be consumed by the Renderer, and their internal structure should be designed for rendering aesthetics. Generally prefer a named-field struct with `#[derive(Grouped)]` over a single-field tuple wrapper (`#[derive(Grouped, Wrap)]`) for more flexible field control.
### Error
@@ -146,7 +146,8 @@ Error + Description
| Resource (mutable) | `counter`, `cache`, `session`, etc. |
```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
dispatcher!("remote.add", EntryRemoteAdd);
@@ -183,10 +187,10 @@ fn handle_remote_add(args: EntryRemoteAdd) -> Next {
// State → Error or Result
#[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()
}
}
@@ -194,13 +198,13 @@ fn handle_state_operation_remotes(state: StateOperationRemotes, db: &ResDatabase
#[renderer(buffer)]
fn render_remote_added(result: ResultRemoteAdded) {
- r_println!("Remote added: {}", result.inner);
+ r_println!("Remote added: {}", result.0);
}
// Error rendering
#[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);
}
```