usage/docs/cli/
mod.rs

1use crate::{Spec, SpecCommand};
2use std::sync::LazyLock;
3use tera::Tera;
4
5pub fn render_help(spec: &Spec, cmd: &SpecCommand, long: bool) -> String {
6    // Convert to docs models to get layout calculations
7    let docs_spec = crate::docs::models::Spec::from(spec.clone());
8    let docs_cmd = crate::docs::models::SpecCommand::from(cmd);
9
10    let mut ctx = tera::Context::new();
11    ctx.insert("spec", &docs_spec);
12    ctx.insert("cmd", &docs_cmd);
13    ctx.insert("long", &long);
14    let template = if long {
15        "spec_template_long.tera"
16    } else {
17        "spec_template_short.tera"
18    };
19    TERA.render(template, &ctx).unwrap().trim().to_string() + "\n"
20}
21
22static TERA: LazyLock<Tera> = LazyLock::new(|| {
23    let mut tera = Tera::default();
24
25    #[rustfmt::skip]
26    tera.add_raw_templates([
27        ("spec_template_short.tera", include_str!("templates/spec_template_short.tera")),
28        ("spec_template_long.tera", include_str!("templates/spec_template_long.tera")),
29    ]).unwrap();
30
31    // Register ljust filter for left-justifying text with padding
32    tera.register_filter(
33        "ljust",
34        |value: &tera::Value, args: &std::collections::HashMap<String, tera::Value>| {
35            let value = value.as_str().unwrap_or("");
36            let width = args.get("width").and_then(|v| v.as_u64()).unwrap_or(0) as usize;
37            let result = format!("{:<width$}", value, width = width);
38            Ok(result.into())
39        },
40    );
41
42    tera
43});
44
45#[cfg(test)]
46mod tests {
47    use super::*;
48    use insta::assert_snapshot;
49
50    #[test]
51    fn test_render_help_with_env() {
52        let spec = crate::spec! { r#"
53bin "testcli"
54flag "--color" env="MYCLI_COLOR" help="Enable color output"
55flag "--verbose" env="MYCLI_VERBOSE" help="Verbose output"
56flag "--debug" help="Debug mode"
57        "# }
58        .unwrap();
59
60        assert_snapshot!(render_help(&spec, &spec.cmd, false), @r"
61        Usage: testcli [FLAGS]
62
63        Flags:
64          --color  Enable color output [env: MYCLI_COLOR]
65          --verbose  Verbose output [env: MYCLI_VERBOSE]
66          --debug  Debug mode
67        ");
68
69        assert_snapshot!(render_help(&spec, &spec.cmd, true), @r"
70        Usage: testcli [FLAGS]
71
72        Flags:
73          --color    Enable color output
74            [env: MYCLI_COLOR]
75          --verbose  Verbose output
76            [env: MYCLI_VERBOSE]
77          --debug    Debug mode
78        ");
79    }
80
81    #[test]
82    fn test_render_help_with_arg_env() {
83        let spec = crate::spec! { r#"
84bin "testcli"
85arg "<input>" env="MY_INPUT" help="Input file"
86arg "<output>" env="MY_OUTPUT" help="Output file"
87arg "<extra>" help="Extra arg without env"
88arg "[default]" help="Arg with default value" default="default value"
89        "# }
90        .unwrap();
91
92        assert_snapshot!(render_help(&spec, &spec.cmd, false), @r"
93        Usage: testcli <ARGS>…
94
95        Arguments:
96          <input>  Input file [env: MY_INPUT]
97          <output>  Output file [env: MY_OUTPUT]
98          <extra>  Extra arg without env
99          [default]  Arg with default value (default: default value)
100        ");
101
102        assert_snapshot!(render_help(&spec, &spec.cmd, true), @r"
103        Usage: testcli <ARGS>…
104
105        Arguments:
106          <input>    Input file
107            [env: MY_INPUT]
108          <output>   Output file
109            [env: MY_OUTPUT]
110          <extra>    Extra arg without env
111          [default]  Arg with default value
112            (default: default value)
113        ");
114    }
115
116    #[test]
117    fn test_render_help_with_before_after_help() {
118        let spec = crate::spec! { r#"
119bin "testcli"
120before_help "This text appears before the help"
121after_help "This text appears after the help"
122flag "--verbose" help="Enable verbose output"
123        "# }
124        .unwrap();
125
126        assert_snapshot!(render_help(&spec, &spec.cmd, false), @r"
127        This text appears before the help
128
129        Usage: testcli [--verbose]
130
131        Flags:
132          --verbose  Enable verbose output
133
134        This text appears after the help
135        ");
136    }
137
138    #[test]
139    fn test_render_help_with_before_after_help_long() {
140        let spec = crate::spec! { r#"
141bin "testcli"
142before_help "short before"
143before_help_long "This is the long version of before help"
144after_help "short after"
145after_help_long "This is the long version of after help"
146flag "--verbose" help="Enable verbose output"
147        "# }
148        .unwrap();
149
150        assert_snapshot!(render_help(&spec, &spec.cmd, false), @r"
151        short before
152
153        Usage: testcli [--verbose]
154
155        Flags:
156          --verbose  Enable verbose output
157
158        short after
159        ");
160
161        assert_snapshot!(render_help(&spec, &spec.cmd, true), @r"
162        This is the long version of before help
163
164        Usage: testcli [--verbose]
165
166        Flags:
167          --verbose  Enable verbose output
168
169        This is the long version of after help
170        ");
171    }
172
173    #[test]
174    fn test_render_help_with_examples() {
175        let spec = crate::spec! { r#"
176bin "testcli"
177flag "--verbose" help="Enable verbose output"
178example "testcli --verbose" header="Run with verbose output"
179example "testcli" header="Run normally" help="Just runs the tool"
180        "# }
181        .unwrap();
182
183        assert_snapshot!(render_help(&spec, &spec.cmd, false), @r"
184        Usage: testcli [--verbose]
185
186        Flags:
187          --verbose  Enable verbose output
188
189        Examples:
190          Run with verbose output:
191            $ testcli --verbose
192          Run normally:
193            $ testcli
194        ");
195
196        assert_snapshot!(render_help(&spec, &spec.cmd, true), @r"
197        Usage: testcli [--verbose]
198
199        Flags:
200          --verbose  Enable verbose output
201
202        Examples:
203          Run with verbose output:
204            $ testcli --verbose
205          Run normally:
206            Just runs the tool
207            $ testcli
208        ");
209    }
210
211    #[test]
212    fn test_render_help_with_version() {
213        let spec = crate::spec! { r#"
214bin "testcli"
215name "TestCLI"
216version "1.2.3"
217flag "--verbose" help="Enable verbose output"
218        "# }
219        .unwrap();
220
221        assert_snapshot!(render_help(&spec, &spec.cmd, false), @r"
222        TestCLI 1.2.3
223        Usage: testcli [--verbose]
224
225        Flags:
226          --verbose  Enable verbose output
227        ");
228    }
229
230    #[test]
231    fn test_render_help_with_author_license() {
232        let spec = crate::spec! { r#"
233bin "testcli"
234author "Test Author"
235license "MIT"
236flag "--verbose" help="Enable verbose output"
237        "# }
238        .unwrap();
239
240        // Short help should not show author/license
241        assert_snapshot!(render_help(&spec, &spec.cmd, false), @r"
242        Usage: testcli [--verbose]
243
244        Flags:
245          --verbose  Enable verbose output
246        ");
247
248        // Long help should show author/license at the bottom
249        assert_snapshot!(render_help(&spec, &spec.cmd, true), @r"
250        Usage: testcli [--verbose]
251
252        Flags:
253          --verbose  Enable verbose output
254
255        Author: Test Author
256        License: MIT
257        ");
258    }
259
260    #[test]
261    fn test_render_help_with_deprecated_command() {
262        let spec = crate::spec! { r#"
263bin "testcli"
264cmd "old-cmd" help="Do something" deprecated="use new-cmd instead"
265cmd "new-cmd" help="Do something better"
266        "# }
267        .unwrap();
268
269        assert_snapshot!(render_help(&spec, &spec.cmd, false), @r"
270        Usage: testcli <SUBCOMMAND>
271
272        Commands:
273          new-cmd  Do something better
274          old-cmd [deprecated: use new-cmd instead]  Do something
275          help  Print this message or the help of the given subcommand(s)
276        ");
277    }
278}
usage/docs/cli/mod.rs

usage/docs/cli/
mod.rs
