diff options
Diffstat (limited to 'docs/pages')
| -rw-r--r-- | docs/pages/1-getting-started.md | 2 | ||||
| -rw-r--r-- | docs/pages/10-help.md | 6 | ||||
| -rw-r--r-- | docs/pages/13-hook.md | 2 | ||||
| -rw-r--r-- | docs/pages/14-testing.md | 4 | ||||
| -rw-r--r-- | docs/pages/2-define-a-dispatcher.md | 4 | ||||
| -rw-r--r-- | docs/pages/4-render-result.md | 4 | ||||
| -rw-r--r-- | docs/pages/6-argument-parse-picker.md | 10 | ||||
| -rw-r--r-- | docs/pages/8-setup-and-resources.md | 6 | ||||
| -rw-r--r-- | docs/pages/9-error-handling.md | 4 | ||||
| -rw-r--r-- | docs/pages/advanced/1-completion.md | 4 | ||||
| -rw-r--r-- | docs/pages/concepts/1-the-pipeline.md | 4 | ||||
| -rw-r--r-- | docs/pages/concepts/4-program-collect.md | 2 | ||||
| -rw-r--r-- | docs/pages/other/features.md | 73 |
13 files changed, 93 insertions, 32 deletions
diff --git a/docs/pages/1-getting-started.md b/docs/pages/1-getting-started.md index 2f31d69..8c81100 100644 --- a/docs/pages/1-getting-started.md +++ b/docs/pages/1-getting-started.md @@ -19,7 +19,7 @@ features = [] ## Enable Features -**Mingling** has all features disabled by default and does **not** provide an all-in-one feature like `full`. +**Mingling** by default only enables `core` and `macros`; the rest need to be enabled as needed. Some features **directly affect the entire lifecycle behavior**, so you need to enable them as needed, e.g.: diff --git a/docs/pages/10-help.md b/docs/pages/10-help.md index 1e3ea78..d9cc557 100644 --- a/docs/pages/10-help.md +++ b/docs/pages/10-help.md @@ -27,14 +27,14 @@ fn help_greet(_entry: EntryGreet) { ## Global Help -You can also write help for `ErrorDispatcherNotFound` as the "root help": +You can also write help for `EntryFallback` as the "root help": ```rust @@@use mingling::macros::help; @@@use mingling::macros::buffer; // Triggered when user passes --help directly #[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` is a type generated by `gen_program!()`, representing "no matching command found." Writing `#[help]` for it adds help to the program's root command. +> `EntryFallback` is a type generated by `gen_program!()`, representing "no matching command found." Writing `#[help]` for it adds help to the program's root command. ## Requires Setup diff --git a/docs/pages/13-hook.md b/docs/pages/13-hook.md index 26f8712..d927a9c 100644 --- a/docs/pages/13-hook.md +++ b/docs/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/pages/14-testing.md b/docs/pages/14-testing.md index 65fedc9..86171bf 100644 --- a/docs/pages/14-testing.md +++ b/docs/pages/14-testing.md @@ -70,10 +70,10 @@ What the three test macros do: ## Constructing Data with the entry! Macro -If `extra_macros` is enabled, you can use `entry!` to quickly construct an Entry: +If `extras` is enabled, you can use `entry!` to quickly construct an Entry: ```rust -// Features: ["extra_macros"] +// Features: ["extras"] @@@use mingling::{assert_member_id, unpack_chain_process}; @@@use mingling::macros::entry; diff --git a/docs/pages/2-define-a-dispatcher.md b/docs/pages/2-define-a-dispatcher.md index 804ad1b..1208e64 100644 --- a/docs/pages/2-define-a-dispatcher.md +++ b/docs/pages/2-define-a-dispatcher.md @@ -79,10 +79,10 @@ When the user types `greet Alice Bob` on the command line, `EntryGreet.inner` be ## Advanced: Implicit Declaration -The above is the standard syntax. If you enable the `extra_macros` feature, you can be more concise: +The above is the standard syntax. If you enable the `extras` feature, you can be more concise: ```rust -// Features: ["extra_macros"] +// Features: ["extras"] // Omit CMDType and EntryType, names are auto-derived dispatcher!("greet"); // dispatcher!("greet", CMDGreet => EntryGreet); diff --git a/docs/pages/4-render-result.md b/docs/pages/4-render-result.md index 9e72d09..7b63b45 100644 --- a/docs/pages/4-render-result.md +++ b/docs/pages/4-render-result.md @@ -116,13 +116,13 @@ cargo run -- great ## Adding a Fallback -`gen_program!()` auto-generates an `ErrorDispatcherNotFound` type wrapping `Vec<String>`—it holds the user input that didn't match any command. You just need to write a Renderer for it: +`gen_program!()` auto-generates an `EntryFallback` type wrapping `Vec<String>`—it holds the user input that didn't match any command. You just need to write a Renderer for it: ```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/pages/6-argument-parse-picker.md b/docs/pages/6-argument-parse-picker.md index 01f1c37..d7d38af 100644 --- a/docs/pages/6-argument-parse-picker.md +++ b/docs/pages/6-argument-parse-picker.md @@ -138,7 +138,7 @@ As the saying goes: "never trust your users." To handle missing required params, Here's a simple example: ```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) { With `pick_or_route`, the code becomes more involved: `.unpack()` no longer returns the value directly, but `Result<Value, Route>`. -However, **Mingling**'s `extra_macros` feature provides the `route!` macro for simplified expansion. It's not complex — it just reduces boilerplate: +However, **Mingling**'s `extras` feature provides the `route!` macro for simplified expansion. It's not complex — it just reduces boilerplate: ```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); It expands to: ```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 { Similarly, you can use `after_or_route` to handle input format errors: ```rust -// Features: ["parser", "extra_macros"] +// Features: ["parser", "extras"] @@@use mingling::macros::buffer; @@@use mingling::macros::route; @@@dispatcher!("greet", CMDGreet => EntryGreet); diff --git a/docs/pages/8-setup-and-resources.md b/docs/pages/8-setup-and-resources.md index 3858e99..12c7610 100644 --- a/docs/pages/8-setup-and-resources.md +++ b/docs/pages/8-setup-and-resources.md @@ -8,7 +8,7 @@ When a program needs to do some init work at startup—like parsing global args ## Initialize with Setup ```rust -// Features: ["extra_macros"] +// Features: ["extras"] @@@use mingling::macros::program_setup; @@@use mingling::Program; #[program_setup] @@ -32,14 +32,14 @@ A function annotated with `#[program_setup]` receives `&mut Program<ThisProgram> Register it in `main` via `program.with_setup(...)` to use it. > [!NOTE] -> `#[program_setup]` requires the `extra_macros` feature. Without it, you can manually implement the `ProgramSetup` trait. +> `#[program_setup]` requires the `extras` feature. Without it, you can manually implement the `ProgramSetup` trait. ## Extract Global Args The most common use of Setup is extracting global args. Mingling provides a few helper methods: ```rust -// Features: ["extra_macros"] +// Features: ["extras"] @@@use mingling::macros::program_setup; @@@use mingling::Program; #[program_setup] diff --git a/docs/pages/9-error-handling.md b/docs/pages/9-error-handling.md index f6e05e3..680328c 100644 --- a/docs/pages/9-error-handling.md +++ b/docs/pages/9-error-handling.md @@ -107,10 +107,10 @@ Error: name is required ## About `pack_err!` -If you've enabled `extra_macros`, you can use `pack_err!` to quickly declare an error type with an auto-generated `name` field: +If you've enabled `extras`, you can use `pack_err!` to quickly declare an error type with an auto-generated `name` field: ```rust -// Features: ["extra_macros"] +// Features: ["extras"] pack_err!(ErrorNotFound); // Generates: struct ErrorNotFound { pub name: String } ``` diff --git a/docs/pages/advanced/1-completion.md b/docs/pages/advanced/1-completion.md index a90c3ce..52350db 100644 --- a/docs/pages/advanced/1-completion.md +++ b/docs/pages/advanced/1-completion.md @@ -15,8 +15,8 @@ features = ["comp"] [build-dependencies.mingling] features = [ "comp", - # Enable `builds` for build-time support - "builds" + # Enable `build` for build-time support + "build" ] ``` diff --git a/docs/pages/concepts/1-the-pipeline.md b/docs/pages/concepts/1-the-pipeline.md index e73379d..2ee26d0 100644 --- a/docs/pages/concepts/1-the-pipeline.md +++ b/docs/pages/concepts/1-the-pipeline.md @@ -42,12 +42,12 @@ The matching rule is **prefix matching** on space-separated tokens — the longe graph LR Input["user input"] --> M{"match Dispatcher"} M -->|"matched"| E["call dispatcher.begin(args)<br/>return wrapped Entry"] - M -->|"no match"| NF["build_dispatcher_not_found<br/>generate ErrorDispatcherNotFound"] + M -->|"no match"| NF["build_entry_fallback<br/>generate EntryFallback"] ``` On a match, `dispatcher.begin(args)` is called, returning `ChainProcess::Ok((AnyOutput, _))` — the Entry type wrapping the user's input params. -If no Dispatcher matches, `ErrorDispatcherNotFound` is generated (wrapping the full input), which a Renderer can later handle to display "Command not found". +If no Dispatcher matches, `EntryFallback` is generated (wrapping the full input), which a Renderer can later handle to display "Command not found". ### 2. Help Shortcut diff --git a/docs/pages/concepts/4-program-collect.md b/docs/pages/concepts/4-program-collect.md index a24f115..c5203c3 100644 --- a/docs/pages/concepts/4-program-collect.md +++ b/docs/pages/concepts/4-program-collect.md @@ -21,7 +21,7 @@ This enum is the type of `G` in `AnyOutput<G>` — the scheduler uses enum varia - **`render`** — calls the corresponding `#[renderer]` function by `member_id`, writes to `RenderResult` - **`render_help`** — calls the corresponding `#[help]` function by `member_id` - **`has_chain` / `has_renderer`** — checks whether a variant has a corresponding handler -- **`build_dispatcher_not_found` / `build_renderer_not_found` / `build_empty_result`** — three built-in fallback types for edge cases +- **`build_entry_fallback` / `build_renderer_not_found` / `build_empty_result`** — three built-in fallback types for edge cases This mapping is resolved at runtime via enum matching — only the enum and match branches are generated at compile time; actual function calls happen at runtime. diff --git a/docs/pages/other/features.md b/docs/pages/other/features.md index 7994d4c..55b6cc8 100644 --- a/docs/pages/other/features.md +++ b/docs/pages/other/features.md @@ -3,6 +3,67 @@ <b>Mingling</b>'s complete feature list </p> +# Preset Feature Groups + +Mingling provides a set of **preset feature groups** that make it easy to enable features in whatever combination you need. + +## `mini` + +**Enables features:** `extras`, `picker` + +**Positioning:** Minimal mode, suitable for small CLI tools or projects that need to get started quickly. Includes only the most essential convenience macros and argument parsing capabilities. + +## `advanced` + +**Enables features:** `extras`, `picker`, `repl`, `comp`, `dispatch_tree`, `structural_renderer` + +**Positioning:** Advanced mode, builds on `mini` by adding an interactive REPL environment, code completion, dispatch tree acceleration, and basic structured output capabilities. Suitable for medium-sized command-line applications with a fuller feature set. + +## `full` + +**Enables features:** `extras`, `picker`, `repl`, `clap`, `comp`, `dispatch_tree`, `structural_renderer_full`, `pathf` + +**Positioning:** Full mode, enables all of Mingling's core functionality. In addition to `advanced`, it includes clap integration, the full structural renderer (with all serialization formats), and the experimental path analyzer. Suitable for large, feature-complete command-line applications. + +## `build_advanced` + +**Enables features:** `build`, `comp` + +**Positioning:** Build-time enhanced configuration, used to generate build helpers such as completion scripts at build time (the `comp` feature provides completion script generation). + +> [!NOTE] +> +> This feature group is intended for **build dependencies** only and must be used alongside the `advanced` feature. Enable it in the `[build-dependencies]` section of `Cargo.toml`: + +```toml +[dependencies.mingling] +features = ["advanced"] + +[build-dependencies.mingling] +features = ["build_advanced"] +``` + +## `build_full` + +**Enables features:** `build`, `comp`, `pathf`, `dispatch_tree` + +**Positioning:** Full build-time configuration, extends `build_advanced` with the path analyzer (`pathf`) to automatically resolve type module paths, suitable for projects with complex structures that require automated build-time analysis. + +> [!NOTE] +> +> This feature group is intended for **build dependencies** only and must be used alongside the `full` feature. Enable it in the `[build-dependencies]` section of `Cargo.toml`: + +```toml +[dependencies.mingling] +features = ["full"] + +[build-dependencies.mingling] +features = ["build_full"] +``` + +# Feature Details + + ## Feature `all_serde_fmt` **Description:** @@ -83,7 +144,7 @@ When enabled, Mingling **at compile time** hard-codes the subcommand structure a See [example](https://mingling-rs.github.io/mingling/docs/example-viewer.html?name=example-dispatch-tree) -## Feature `extra_macros` +## Feature `extras` **Description:** @@ -106,7 +167,7 @@ For example, allows the shorthand form `dispatcher!("greet")`, which auto-genera ### `empty_result!()` ```rust -// Features: ["extra_macros"] +// Features: ["extras"] pack!(StatePrev1 = ()); pack!(StatePrev2 = ()); @@ -134,7 +195,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 +215,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 +235,7 @@ Registers an external type as a member of the program group without modifying it The type's simple name is used as the enum variant, just like `pack!` or `#[derive(Grouped)]`. ```rust -// Features: ["extra_macros"] +// Features: ["extras"] use mingling::macros::group; use std::num::ParseIntError; @@ -189,7 +250,7 @@ Creates an error struct with an automatic `name: String` field set to the snake_ of the struct name. Optionally wraps an inner type for additional context. ```rust -// Features: ["extra_macros"] +// Features: ["extras"] use std::path::PathBuf; // Simple form — only a name field: |
