chkc-help 1.0.0

a small help screen generator for clap
Documentation 
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
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146

//! typed snapshot of clap data that the renderer can turn into markdown.

use clap::builder::OsStr;

use crate::doc_registry::CommandDoc;

/// everything we need to print help for a command path.
#[derive(Debug, Clone)]
pub struct HelpPage {
    /// Name of the binary / application (e.g. "git")
    pub app_name: String,

    /// Application version (from clap metadata).
    pub version: Option<String>,

    /// Full command path (e.g. "commit main")
    pub path: String,

    /// One-line summary (from clap)
    pub summary: Option<String>,

    /// Optional longer description
    pub description: Option<String>,

    /// Usage string (from clap)
    pub usage: String,

    /// Positional arguments
    pub positionals: Vec<HelpArg>,

    /// Flags and options
    pub options: Vec<HelpOption>,

    /// Subcommands (for category-level help)
    pub subcommands: Vec<HelpSubcommand>,

    /// Examples
    pub examples: Vec<String>,

    /// Notes / tips / caveats
    pub notes: Vec<String>,
}

/// a flag/option with optional value and default info.
#[derive(Debug, Clone)]
pub struct HelpOption {
    pub short: Option<char>,
    pub long: Option<String>,
    pub value: Option<String>,
    pub description: String,
    pub default: String,
}

/// positional argument.
#[derive(Debug, Clone)]
pub struct HelpArg {
    pub name: String,
    pub description: Option<String>,
    pub required: bool,
    pub multiple: bool,
}

/// child command for category-level help.
#[derive(Debug, Clone)]
pub struct HelpSubcommand {
    pub name: String,
    pub summary: Option<String>,
}

impl HelpPage {
    /// build a page straight from a `clap::Command`.
    pub fn from_clap(
        app_name: &str,
        version: Option<&str>,
        path: &str,
        cmd: &clap::Command,
    ) -> Self {
        let positionals = cmd
            .get_positionals()
            .map(|arg| HelpArg {
                name: arg.get_id().to_string(),
                description: arg.get_help().map(|s| s.to_string()),
                required: arg.is_required_set(),
                multiple: arg
                    .get_num_args()
                    .map(|n| n.min_values() != n.max_values() || 1 < n.min_values())
                    .unwrap_or_default(),
            })
            .collect();

        let options = cmd
            .get_arguments()
            .filter(|a| !a.is_positional())
            .map(|arg| HelpOption {
                short: arg.get_short(),
                long: arg.get_long().map(str::to_string),
                value: if arg.get_action().takes_values() {
                    arg.get_value_names()
                        .and_then(|v| v.first())
                        .map(|v| v.to_string())
                } else {
                    None
                },
                description: arg.get_help().unwrap_or_default().to_string(),
                default: arg
                    .get_default_values()
                    .join(&OsStr::from(", "))
                    .to_str()
                    .unwrap_or_default()
                    .to_string(),
            })
            .collect();

        let subcommands = cmd
            .get_subcommands()
            .map(|sc| HelpSubcommand {
                name: sc.get_name().to_string(),
                summary: sc.get_about().map(|s| s.to_string()),
            })
            .collect();

        Self {
            app_name: app_name.to_string(),
            version: version.map(|s| s.to_string()),
            path: path.to_string(),
            summary: cmd.get_about().map(|s| s.to_string()),
            description: cmd.get_long_about().map(|s| s.to_string()),
            usage: cmd.clone().render_usage().to_string(),
            positionals,
            options,
            subcommands,
            examples: Vec::new(),
            notes: Vec::new(),
        }
    }

    /// merge data from a [`CommandDoc`], falling back to clap metadata when missing.
    pub fn with_docs(mut self, doc: Option<&CommandDoc>) -> Self {
        if let Some(doc) = doc {
            self.description = doc.description.clone().or(self.description);
            self.examples = doc.examples.clone();
            self.notes = doc.notes.clone();
        }
        self
    }
}