diff options
| author | 魏曹先生 <1992414357@qq.com> | 2026-06-30 18:05:05 +0800 |
|---|---|---|
| committer | 魏曹先生 <1992414357@qq.com> | 2026-06-30 18:05:05 +0800 |
| commit | 13408e79b940e9a33ca593ed30d1b20c54e01234 (patch) | |
| tree | 282549991a3f31791401ca2f3255b9318679d2e9 /docs/pages/10-help.md | |
| parent | 29867ab5c0b40378a33318d989c809f90fc7d3aa (diff) | |
feat(docs): add Chinese and English documentation for Mingling tutorials
Add comprehensive documentation covering Declare a Dispatcher, Declare a
Chain, Rendering Results, Multi-Command Program, Argument Parsing with
Picker and Clap, Program Setup, Error Handling, Help Info, Resource
System, Exit Code Control, Hook System, Testing, Completion, Structural
Rendering, and Core Concepts
Diffstat (limited to 'docs/pages/10-help.md')
| -rw-r--r-- | docs/pages/10-help.md | 69 |
1 files changed, 69 insertions, 0 deletions
diff --git a/docs/pages/10-help.md b/docs/pages/10-help.md new file mode 100644 index 0000000..2f3b74f --- /dev/null +++ b/docs/pages/10-help.md @@ -0,0 +1,69 @@ +<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) { + r_println!("Usage: greet [name]"); + r_println!("Say hello to someone."); +} +``` + +> [!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) { + r_println!("Usage: my-cli <command>"); + r_println!("Commands:"); + r_println!(" greet Say hello"); +} +``` + +> [!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> |
