diff options
| author | 魏曹先生 <1992414357@qq.com> | 2026-08-17 05:49:19 +0800 |
|---|---|---|
| committer | 魏曹先生 <1992414357@qq.com> | 2026-08-17 05:49:19 +0800 |
| commit | 57c53affe3542cb6bd4e79ee4c18f20a1bd76b2d (patch) | |
| tree | 1cd4aef44cb7a45a8cd9d520b598f5f181e24c76 /docs/pages/other | |
| parent | ef23cd944402939605c78a4a853ef6e33af02c21 (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.md | 59 | ||||
| -rw-r--r-- | docs/pages/other/naming_rule.md | 24 |
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); } ``` |
