aboutsummaryrefslogtreecommitdiff
path: root/docs/pages
diff options
context:
space:
mode:
Diffstat (limited to 'docs/pages')
-rw-r--r--docs/pages/1-getting-started.md2
-rw-r--r--docs/pages/10-help.md6
-rw-r--r--docs/pages/13-hook.md2
-rw-r--r--docs/pages/14-testing.md4
-rw-r--r--docs/pages/2-define-a-dispatcher.md4
-rw-r--r--docs/pages/4-render-result.md4
-rw-r--r--docs/pages/6-argument-parse-picker.md10
-rw-r--r--docs/pages/8-setup-and-resources.md6
-rw-r--r--docs/pages/9-error-handling.md4
-rw-r--r--docs/pages/advanced/1-completion.md4
-rw-r--r--docs/pages/concepts/1-the-pipeline.md4
-rw-r--r--docs/pages/concepts/4-program-collect.md2
-rw-r--r--docs/pages/other/features.md73
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: