diff options
Diffstat (limited to 'docs/pages')
| -rw-r--r-- | docs/pages/10-help.md | 4 | ||||
| -rw-r--r-- | docs/pages/11-resource-system.md | 6 | ||||
| -rw-r--r-- | docs/pages/13-hook.md | 2 | ||||
| -rw-r--r-- | docs/pages/14-testing.md | 6 | ||||
| -rw-r--r-- | docs/pages/2-define-a-dispatcher.md | 10 | ||||
| -rw-r--r-- | docs/pages/3-define-a-chain.md | 8 | ||||
| -rw-r--r-- | docs/pages/4-render-result.md | 2 | ||||
| -rw-r--r-- | docs/pages/5-multiple-commands.md | 8 | ||||
| -rw-r--r-- | docs/pages/6-argument-parse-picker.md | 24 | ||||
| -rw-r--r-- | docs/pages/7-argument-parse-clap.md | 4 | ||||
| -rw-r--r-- | docs/pages/9-error-handling.md | 6 | ||||
| -rw-r--r-- | docs/pages/advanced/1-completion.md | 2 | ||||
| -rw-r--r-- | docs/pages/advanced/2-structural-renderer.md | 4 | ||||
| -rw-r--r-- | docs/pages/other/features.md | 2 | ||||
| -rw-r--r-- | docs/pages/other/naming_rule.md | 28 |
15 files changed, 57 insertions, 59 deletions
diff --git a/docs/pages/10-help.md b/docs/pages/10-help.md index 3d4b3b8..b378a61 100644 --- a/docs/pages/10-help.md +++ b/docs/pages/10-help.md @@ -14,7 +14,7 @@ Write a help function directly for an Entry: ```rust @@@use mingling::macros::help; @@@use mingling::macros::buffer; -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); #[help(buffer)] fn help_greet(_entry: EntryGreet) { r_println!("Usage: greet [name]"); @@ -51,7 +51,7 @@ For `--help` to work properly, add `BasicProgramSetup` in `main`: ```rust @@@use mingling::macros::help; @@@use mingling::setup::BasicProgramSetup; -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); fn main() { let mut program = ThisProgram::new(); program.with_setup(BasicProgramSetup); diff --git a/docs/pages/11-resource-system.md b/docs/pages/11-resource-system.md index 0e2bd19..3a4dc36 100644 --- a/docs/pages/11-resource-system.md +++ b/docs/pages/11-resource-system.md @@ -30,7 +30,7 @@ In a Chain or Renderer, simply declare the resource in the parameter list: @@@use mingling::macros::buffer; @@@#[derive(Default, Clone)] @@@struct ResCurrentDir(String); -@@@dispatcher!("pwd", CMDPrintWorkingDir => EntryPrintWorkingDir); +@@@dispatcher!("pwd", EntryPrintWorkingDir); @@@pack!(ResultPath = String); // Inject read-only resource via &T #[chain] @@ -52,7 +52,7 @@ Use `&mut T` to inject a mutable resource: @@@use mingling::macros::buffer; @@@#[derive(Default, Clone)] @@@struct ResVisitCount(u32); -@@@dispatcher!("visit", CMDVisit => EntryVisit); +@@@dispatcher!("visit", EntryVisit); @@@pack!(ResultDone = ()); #[chain] fn handle_visit(_args: EntryVisit, counter: &mut ResVisitCount) -> Next { @@ -73,7 +73,7 @@ A Chain can inject any number of resources at once — the framework matches the ```rust @@@#[derive(Default, Clone)] struct ResConfig(String); @@@#[derive(Default, Clone)] struct ResCounter(u32); -@@@dispatcher!("test", CMDTest => EntryTest); +@@@dispatcher!("test", EntryTest); @@@pack!(ResultDone = ()); // Inject both read-only and mutable resources #[chain] diff --git a/docs/pages/13-hook.md b/docs/pages/13-hook.md index c525998..90df379 100644 --- a/docs/pages/13-hook.md +++ b/docs/pages/13-hook.md @@ -54,7 +54,7 @@ Each hook callback receives a corresponding `Hook*Info` struct containing contex @@@use mingling::prelude::*; @@@use mingling::hook::ProgramHook; @@@ -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); @@@pack!(ResultName = String); @@@ @@@#[chain] fn handle_greet(args: EntryGreet) -> Next { diff --git a/docs/pages/14-testing.md b/docs/pages/14-testing.md index 86171bf..9f6b6ed 100644 --- a/docs/pages/14-testing.md +++ b/docs/pages/14-testing.md @@ -35,7 +35,7 @@ Testing a Chain is slightly more complex because its return value is `Next` (act ```rust @@@use mingling::{assert_member_id, assert_render_result, unpack_chain_process}; -@@@dispatcher!("hello", CMDHello => EntryHello); +@@@dispatcher!("hello", EntryHello); @@@pack!(ResultName = String); @@@pack!(ErrorNoName = ()); @@@#[chain] @@ -77,7 +77,7 @@ If `extras` is enabled, you can use `entry!` to quickly construct an Entry: @@@use mingling::{assert_member_id, unpack_chain_process}; @@@use mingling::macros::entry; -@@@dispatcher!("hello", CMDHello => EntryHello); +@@@dispatcher!("hello", EntryHello); @@@pack!(ResultName = String); @@@#[chain] @@@fn handle_hello(args: EntryHello) -> Next { @@ -102,7 +102,7 @@ If a Chain uses resources, you need to provide resource instances in the test: @@@use mingling::{assert_render_result, unpack_chain_process}; @@@#[derive(Default, Clone)] @@@struct ResPrefix(String); -@@@dispatcher!("hello", CMDHello => EntryHello); +@@@dispatcher!("hello", EntryHello); @@@pack!(ResultGreeting = String); @@@ #[chain] diff --git a/docs/pages/2-define-a-dispatcher.md b/docs/pages/2-define-a-dispatcher.md index 432d7db..efd744d 100644 --- a/docs/pages/2-define-a-dispatcher.md +++ b/docs/pages/2-define-a-dispatcher.md @@ -19,13 +19,13 @@ The `dispatcher!` macro generates two types at once: The syntax is a fixed three-part pattern: ```rust -dispatcher!("command path", DispatcherType => EntryType); +dispatcher!("command path", EntryType); ``` Here's a concrete example: ```rust -dispatcher!("greet", CMDGreet => EntryGreet); +dispatcher!("greet", EntryGreet); ``` > [!NOTE] @@ -36,8 +36,8 @@ dispatcher!("greet", CMDGreet => EntryGreet); If your program has a hierarchy — e.g., `remote add`, `remote rm` — just separate the command name with dots: ```rust -dispatcher!("remote.add", CMDRemoteAdd => EntryRemoteAdd); -dispatcher!("remote.rm", CMDRemoteRm => EntryRemoteRm); +dispatcher!("remote.add", EntryRemoteAdd); +dispatcher!("remote.rm", EntryRemoteRm); ``` When the user types `remote add` in the terminal, Mingling matches `remote` and `add` as two levels in sequence. @@ -68,7 +68,7 @@ The above is the standard syntax. If you enable the `extras` feature, you can be // Features: ["extras"] // Omit CMDType and EntryType, names are auto-derived dispatcher!("greet"); -// dispatcher!("greet", CMDGreet => EntryGreet); +// dispatcher!("greet", EntryGreet); ``` This syntax auto-generates `CMDGreet` and `EntryGreet`, with the same effect as the explicit declaration. diff --git a/docs/pages/3-define-a-chain.md b/docs/pages/3-define-a-chain.md index 1134dbf..dca299e 100644 --- a/docs/pages/3-define-a-chain.md +++ b/docs/pages/3-define-a-chain.md @@ -3,7 +3,7 @@ Use the <code>chain</code> macro to declare a chain and handle Entry input </p> -In the previous section, we declared `dispatcher!("greet", CMDGreet => EntryGreet)`. +In the previous section, we declared `dispatcher!("greet", EntryGreet)`. Now when a user types `greet`, it gets matched and wrapped into `EntryGreet`. @@ -16,7 +16,7 @@ We need a Chain to process it. `#[chain]` marks a handler function. The format is straightforward: ```rust -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); pack!(ResultName = String); #[chain] @@ -77,7 +77,7 @@ See [Naming Convention](pages/other/naming_rule) for details, but for now just r `EntryGreet`'s `inner` is a `Vec<String>`, which you can freely process inside a Chain: ```rust -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); @@@pack!(ResultName = String); #[chain] fn handle_greet(args: EntryGreet) -> Next { @@ -100,7 +100,7 @@ Now let's connect the Dispatcher and Chain: ```rust // 1. Declare the command -dispatcher!("greet", CMDGreet => EntryGreet); +dispatcher!("greet", EntryGreet); // 2. Declare the pipeline data type pack!(ResultName = String); diff --git a/docs/pages/4-render-result.md b/docs/pages/4-render-result.md index a50c509..fdf8b12 100644 --- a/docs/pages/4-render-result.md +++ b/docs/pages/4-render-result.md @@ -52,7 +52,7 @@ Putting all three tutorials together, here's your first complete Mingling progra use mingling::macros::buffer; // 1. Declare commands with a Dispatcher -dispatcher!("greet", CMDGreet => EntryGreet); +dispatcher!("greet", EntryGreet); // 2. Declare result data with pack! pack!(ResultName = String); diff --git a/docs/pages/5-multiple-commands.md b/docs/pages/5-multiple-commands.md index b92cb95..a5c09b0 100644 --- a/docs/pages/5-multiple-commands.md +++ b/docs/pages/5-multiple-commands.md @@ -12,8 +12,8 @@ Work in the same project: ```rust @@@use mingling::macros::buffer; // Declare two commands -dispatcher!("greet", CMDGreet => EntryGreet); -dispatcher!("add", CMDAdd => EntryAdd); +dispatcher!("greet", EntryGreet); +dispatcher!("add", EntryAdd); pack!(ResultGreeting = String); pack!(ResultSum = i32); @@ -62,8 +62,8 @@ Sum: 6 Multi-level commands work the same way—each dot-separated level is just part of the name: ```rust -dispatcher!("remote.add", CMDRemoteAdd => EntryRemoteAdd); -dispatcher!("remote.rm", CMDRemoteRm => EntryRemoteRm); +dispatcher!("remote.add", EntryRemoteAdd); +dispatcher!("remote.rm", EntryRemoteRm); ``` Each subcommand's Entry, Chain, and Renderer are completely independent and don't interfere. diff --git a/docs/pages/6-argument-parse-picker.md b/docs/pages/6-argument-parse-picker.md index d7d38af..9da56d5 100644 --- a/docs/pages/6-argument-parse-picker.md +++ b/docs/pages/6-argument-parse-picker.md @@ -26,7 +26,7 @@ Now let's see how `Picker` is written: ```rust // Features: ["parser"] -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); @@@pack!(ResultName = String); #[chain] @@ -42,7 +42,7 @@ For the code above: ```rust // Features: ["parser"] -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); @@@pack!(ResultName = String); @@@#[chain] @@@fn handle_greet_entry(prev: EntryGreet) -> Next { @@ -55,7 +55,7 @@ Its semantics are: ```rust // Features: ["parser"] -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); @@@pack!(ResultName = String); @@@#[chain] @@@fn handle_greet_entry(prev: EntryGreet) { @@ -76,7 +76,7 @@ If your program needs to parse flag arguments (e.g. `greet --name Alice`), do th ```rust // Features: ["parser"] -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); @@@pack!(ResultName = String); #[chain] @@ -90,7 +90,7 @@ Its semantics: ```rust // Features: ["parser"] -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); @@@pack!(ResultName = String); @@@#[chain] @@@fn handle_greet_entry(prev: EntryGreet) { @@ -113,7 +113,7 @@ For a single pick, `.unpack()` returns the value directly; for multiple picks, i ```rust // Features: ["parser"] -@@@dispatcher!("test", CMDTest => EntryTest); +@@@dispatcher!("test", EntryTest); @@@pack!(ResultInfo = (String, u8, u32)); #[chain] @@ -141,7 +141,7 @@ Here's a simple example: // Features: ["parser", "extras"] @@@use mingling::macros::buffer; @@@use mingling::macros::route; -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); @@@pack!(ResultName = String); @@@pack!(ErrorNoName = ()); @@ -200,7 +200,7 @@ After picking user input with `pick`, you can use `after` to process it immediat ```rust // Features: ["parser"] -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); @@@pack!(ResultName = String); #[chain] @@ -226,7 +226,7 @@ Similarly, you can use `after_or_route` to handle input format errors: // Features: ["parser", "extras"] @@@use mingling::macros::buffer; @@@use mingling::macros::route; -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); @@@pack!(ResultName = String); @@@pack!(ErrorNameTooLong = usize); @@ -276,7 +276,7 @@ Implicit mode is generally sufficient, but for important confirmations, explicit ```rust // Features: ["parser"] @@@use mingling::parser::Yes; -@@@dispatcher!("test", CMDTest => EntryTest); +@@@dispatcher!("test", EntryTest); @@@pack!(ResultDone = ()); #[chain] @@ -329,7 +329,7 @@ impl Pickable for Address { Some(Address { ip, port }) } } -@@@dispatcher!("connect", CMDConnect => EntryConnect); +@@@dispatcher!("connect", EntryConnect); @@@pack!(ResultConnected = Address); #[chain] @@ -369,7 +369,7 @@ pub enum Fruits { } impl PickableEnum for Fruits {} -@@@dispatcher!("eat", CMDEat => EntryEat); +@@@dispatcher!("eat", EntryEat); @@@pack!(ResultFruit = Fruits); #[chain] diff --git a/docs/pages/7-argument-parse-clap.md b/docs/pages/7-argument-parse-clap.md index ee1e96f..8b2ad0c 100644 --- a/docs/pages/7-argument-parse-clap.md +++ b/docs/pages/7-argument-parse-clap.md @@ -27,7 +27,7 @@ Add `#[dispatcher_clap]` on a `clap::Parser` struct to auto-generate a Dispatche @@@ use mingling::macros::dispatcher_clap; @@@ use mingling::macros::buffer; #[derive(Default, clap::Parser, Grouped)] -#[dispatcher_clap("greet", CMDGreet, help = true, error = ErrorGreetParsed)] +#[dispatcher_clap("greet", help = true, error = ErrorGreetParsed)] pub struct EntryGreet { #[clap(default_value = "World")] name: String, @@ -63,7 +63,7 @@ If you need `--help` support, register `BasicProgramSetup` in main and set the c @@@use mingling::setup::BasicProgramSetup; @@@use mingling::macros::dispatcher_clap; @@@#[derive(Default, clap::Parser, Grouped)] -@@@#[dispatcher_clap("greet", CMDGreet)] +@@@#[dispatcher_clap("greet", )] @@@pub struct EntryGreet { @@@ name: String, @@@} diff --git a/docs/pages/9-error-handling.md b/docs/pages/9-error-handling.md index 389e394..eefc0f0 100644 --- a/docs/pages/9-error-handling.md +++ b/docs/pages/9-error-handling.md @@ -19,7 +19,7 @@ Error values can also take either path—you can render the error msg directly, ## Distinguish Errors with Dedicated Types ```rust -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); pack!(ResultGreeting = String); pack!(ErrorNameEmpty = String); @@ -39,7 +39,7 @@ Then write separate Renderers: ```rust @@@use mingling::macros::buffer; -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@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() } @@ -61,7 +61,7 @@ Each Renderer does its own job; what the user sees depends on what the Chain ret ```rust @@@use mingling::macros::buffer; -dispatcher!("greet", CMDGreet => EntryGreet); +dispatcher!("greet", EntryGreet); pack!(ResultGreeting = String); pack!(ErrorNameEmpty = String); diff --git a/docs/pages/advanced/1-completion.md b/docs/pages/advanced/1-completion.md index f70d415..55b8b1d 100644 --- a/docs/pages/advanced/1-completion.md +++ b/docs/pages/advanced/1-completion.md @@ -40,7 +40,7 @@ Use `#[completion(EntryType)]` to define completion logic for an Entry: @@@use mingling::prelude::*; @@@use mingling::{ShellContext, Suggest, SuggestItem}; @@@use std::collections::BTreeSet; -@@@dispatcher!("greet", CMDGreet => EntryGreet); +@@@dispatcher!("greet", EntryGreet); #[completion(EntryGreet)] fn complete_greet(ctx: &ShellContext) -> Suggest { diff --git a/docs/pages/advanced/2-structural-renderer.md b/docs/pages/advanced/2-structural-renderer.md index 489baba..e444ee6 100644 --- a/docs/pages/advanced/2-structural-renderer.md +++ b/docs/pages/advanced/2-structural-renderer.md @@ -29,7 +29,7 @@ After enabling `StructuralRendererSetup`, use `pack_structural!` instead of `pac // serde = "1" @@@use mingling::macros::buffer; @@@use mingling::setup::StructuralRendererSetup; -@@@dispatcher!("render", CMDRender => EntryRender); +@@@dispatcher!("render", EntryRender); // pack_structural! is equivalent to pack! + StructuralData pack_structural!(ResultInfo = (String, i32)); @@ -72,7 +72,7 @@ The default output from `pack_structural!` includes an `inner` field. For full c @@@use mingling::setup::StructuralRendererSetup; @@@use mingling::StructuralData; @@@use serde::Serialize; -@@@dispatcher!("render", CMDRender => EntryRender); +@@@dispatcher!("render", EntryRender); #[derive(Serialize, StructuralData, Grouped)] struct Info { diff --git a/docs/pages/other/features.md b/docs/pages/other/features.md index 7615118..4552d30 100644 --- a/docs/pages/other/features.md +++ b/docs/pages/other/features.md @@ -158,7 +158,7 @@ For example, allows the shorthand form `dispatcher!("greet")`, which auto-genera | `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 `CMDStruct => EntryStruct`, names are auto-derived | +| `dispatcher!("cmd.path")` **shorthand** | Omit `EntryStruct`, the entry name is auto-derived | <details> <summary> Details </summary> diff --git a/docs/pages/other/naming_rule.md b/docs/pages/other/naming_rule.md index 1175ae0..770fd10 100644 --- a/docs/pages/other/naming_rule.md +++ b/docs/pages/other/naming_rule.md @@ -40,19 +40,17 @@ Name + Setup ### Dispatcher -Dispatchers are the entry points of commands, corresponding one-to-one with `Node` names. Node names use `.` to separate levels, dispatcher names use the `CMD` prefix with PascalCase. +Dispatchers are the entry points of commands. The command name uses `.` to separate hierarchy levels and matches the arguments typed by the user. ``` -CMD + Command Hierarchy +command name ``` -| Node | Dispatcher | -| ------------ | ----------------- | -| `greet` | `CMDGreet` | -| `remote.add` | `CMDRemoteAdd` | -| `remote.rm` | `CMDRemoteRemove` | - -Even if a node is an abbreviation, the dispatcher name should use the full name. For example, the node is `remote.rm`, but the dispatcher is `CMDRemoteRemove`, not `CMDRemoteRm`. +| Command | +| ------------ | +| `greet` | +| `remote.add` | +| `remote.rm` | ### Entry @@ -62,11 +60,11 @@ Entries are the pipeline starting types created by dispatchers, wrapping `Vec<St Entry + Command Hierarchy ``` -| Dispatcher | Entry | -| ----------------- | ------------------- | -| `CMDGreet` | `EntryGreet` | -| `CMDRemoteAdd` | `EntryRemoteAdd` | -| `CMDRemoteRemove` | `EntryRemoteRemove` | +| Command | Entry | +| ------------ | ------------------- | +| `greet` | `EntryGreet` | +| `remote.add` | `EntryRemoteAdd` | +| `remote.rm` | `EntryRemoteRemove` | ### State @@ -174,7 +172,7 @@ fn handle_remote_add(args: EntryRemoteAdd, cwd: &ResCurrentDir, db: &mut ResData @@@ pack!(ResultRemoteAdded = String); @@@ pack!(ErrorRepositoryNotFound = String); // Dispatcher -dispatcher!("remote.add", CMDRemoteAdd => EntryRemoteAdd); +dispatcher!("remote.add", EntryRemoteAdd); // Entry → State #[chain] |
