blob: 4c20928be6e5b027353ec90da2599d18d0b975cc (
plain) (
blame)
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
|
use crate::RenderResult;
/// Mingling's program help request.
///
/// It provides help capability to a program by binding an entry type. When [`Program`](https://docs.rs/mingling/latest/mingling/struct.Program.html)'s `user_context.help` is `true`,
/// the first Entry produced by [`Dispatcher`](https://docs.rs/mingling/latest/mingling/trait.Dispatcher.html) will be sent into [`HelpRequest`] and rendered into a [`RenderResult`] for the user.
///
/// # Manual impl
///
/// Normally, [`HelpRequest`] is generated by [`#[help]`](https://docs.rs/mingling/latest/mingling/macros/attr.help.html),
/// but if you need to implement it manually, please follow the example below:
///
/// ```
/// # use mingling_core::HelpRequest;
/// # use mingling_core::RenderResult;
/// # use mingling_core::MockProgramCollect as ThisProgram;
/// struct GreetHelp;
/// struct EntryGreet;
///
/// impl HelpRequest for GreetHelp {
/// type Entry = EntryGreet;
///
/// fn render_help(p: Self::Entry) -> RenderResult {
/// let mut result = RenderResult::new();
/// result.eprintln("USAGE: greet <PARAM...>");
/// result
/// }
/// }
///
/// // Register help with the program
/// // mingling::register_help!(EntryGreet, GreetHelp);
/// ```
pub trait HelpRequest {
/// The entry type corresponding to this help request.
///
/// This associated type indicates which entry the help request will handle. When the program needs to display help,
/// the first entry produced by the `Dispatcher` will be passed to the corresponding help request for processing.
type Entry;
/// Render the entry as help information.
///
/// This function receives an entry of type [`Self::Entry`] and renders it into a [`RenderResult`].
/// Implementors should output help content (such as usage instructions, parameter descriptions, etc.)
/// into the [`RenderResult`].
///
/// # Return
/// Returns a [`RenderResult`] containing the help text, ready to be displayed directly to the user by the caller.
fn render_help(p: Self::Entry) -> RenderResult;
}
|
