usage/docs/cli/
mod.rs

1use crate::{Spec, SpecCommand};
2use once_cell::sync::Lazy;
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: Lazy<Tera> = Lazy::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}
usage/docs/cli/mod.rs

usage/docs/cli/
mod.rs
