1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
|
<h1 align="center">Help Info</h1>
<p align="center">
Adding --help support to commands
</p>
A CLI without help info is not a good CLI.
In Mingling, use the `#[help]` macro to add help text to commands.
## Simplest Help
Write a help function directly for an Entry:
```rust
@@@use mingling::macros::help;
@@@dispatcher!("greet", CMDGreet => EntryGreet);
#[help]
fn help_greet(entry: EntryGreet) -> RenderResult {
let mut r = RenderResult::new();
writeln!(r, "Usage: greet [name]").ok();
writeln!(r, "Say hello to someone.").ok();
r
}
```
> [!NOTE]
> Help functions also use `r_println!`, because `#[help]` follows the rendering pipeline — it's a short-circuit render triggered early by the `--help` flag, not logic outside the pipeline.
## Global Help
You can also write help for `ErrorDispatcherNotFound` as the "root help":
```rust
@@@use mingling::macros::help;
// Triggered when user passes --help directly
#[help]
fn help_root(entry: ErrorDispatcherNotFound) -> RenderResult {
let mut r = RenderResult::new();
writeln!(r, "Usage: my-cli <command>").ok();
writeln!(r, "Commands:").ok();
writeln!(r, " greet Say hello").ok();
r
}
```
> [!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.
## Requires Setup
For `--help` to work properly, add `BasicProgramSetup` in `main`:
```rust
@@@use mingling::macros::help;
@@@use mingling::setup::BasicProgramSetup;
@@@dispatcher!("greet", CMDGreet => EntryGreet);
fn main() {
let mut program = ThisProgram::new();
program.with_setup(BasicProgramSetup);
program.with_dispatcher(CMDGreet);
program.exec_and_exit();
}
```
`BasicProgramSetup` includes `HelpFlagSetup`, which simply sets `program.user_context.help` to `true`.
The actual routing to the `#[help]` function is handled by code generated via `gen_program!()` — it checks this flag during dispatch, and if `true`, goes through the help rendering path, bypassing the Chain.
Without `BasicProgramSetup`, `--help` is treated as a normal argument and passed as input to the Entry's Chain.
<p align="center" style="font-size: 0.85em; color: gray;">
Written by @Weicao-CatilGrass
</p>
|
