clap-help

目的和功能

clap-help 打印基于 clap 的终端应用程序的 --help 消息。

与 clap 包的原始帮助渲染器的区别

• 更易读，得益于宽度感知布局
• 更紧凑：比原始版本少 2 到 3 倍的行数
• 选项以平衡的表格形式渲染，优化了终端宽度
• 简介被解释为 Markdown，允许列表、表格、代码块等
• 选项文档被解释为 Markdown
• 皮肤自动选择亮色或暗色终端
• 可自定义的 termimad 皮肤
• 您可以自定义部分模板、删除它们、重新排序它们、添加部分

注意：尚不支持子命令。

示例

bacon 程序使用 clap-help，包括简介文本、更清晰的选项表、示例以及与应用程序一致的皮肤

如何实现： https://github.com/Canop/bacon/blob/main/src/args.rs.

用法

基本用法

您的程序需要一个定义了 clap Command。

这里以 clap-derive 为例

#[derive(Parser, Debug)]
#[command(name="area", author, version, about, disable_help_flag = true)]
struct Args {

    /// Print help
    #[arg(long)]
    help: bool,

    /// Height, that is the distance between bottom and top
    #[arg(short, long, default_value = "9")]
    height: u16,

    /// Width, from there, to there, eg `4` or `5`
    #[arg(short, long, default_value = "3")]
    width: u16,

    /// Kill all birds to improve computation
    #[arg(short, long)]
    kill_birds: bool,

    /// Computation strategy
    #[arg(long, default_value = "fast")]
    strategy: Strategy,

    /// Bird separator
    #[arg(short, long, value_name = "SEP")]
    separator: Option<String>,

    /// Root Directory
    pub root: Option<std::path::PathBuf>,
}

注意

• 禁用了 clap 的标准帮助行为的 disable_help_flag = true
• 显式的 help 参数。这里只使用 #[arg(long)] 因为 -h 被用于更重要的事情，但您通常会使用 #[arg(short, long)]。

帮助介绍（使用说明之前的部分）被定义为字符串，将作为Markdown进行解析。它可以包含表格、列表、粗体、斜体、内联代码、代码块等。

static INTRO: &str = "

Compute `height x width`
*You can do it either precisely (enough) or fast (I mean not too slow)*.
";

程序启动时，应检查 help 标志的值，并在必要时打印帮助信息。

let args = Args::parse();
if args.help {
    Printer::new(Args::command())
        .with("introduction", INTRO)
        .without("author")
        .print_help();
    return;
}

在浅色终端中渲染的帮助信息

在深色终端中的相同帮助信息

完整的示例在 /examples/area 中，可以通过以下命令查看：cargo run --example area -- --help

添加自定义部分

通过几个示例，帮助信息通常更容易理解。您可以在简介中写几个，或者您可以在选项之后的后续部分添加它们。

也可以利用模板系统，这在 with-examples 示例中已经实现，以得到这个结果

下面是如何实现的

static EXAMPLES_TEMPLATE: &str = "
**Examples:**

${examples
**${example-number})** ${example-title}: `${example-cmd}`
${example-comments}
}
";

let mut printer = clap_help::Printer::new(Args::command())
    .with("introduction", INTRO_TEMPLATE)
    .without("author");
printer.template_keys_mut().push("examples");
printer.set_template("examples", EXAMPLES_TEMPLATE);
for (i, example) in EXAMPLES.iter().enumerate() {
    printer
        .expander_mut()
        .sub("examples")
        .set("example-number", i + 1)
        .set("example-title", example.title)
        .set("example-cmd", example.cmd)
        .set_md("example-comments", example.comments);
}
printer.print_help();

示例的完整代码

更改皮肤

如果您的程序有一些图形标识，您可能希望将其扩展到帮助信息中。

您可以更改颜色，最好使用更兼容的 ANSI 颜色代码。

请参阅 examples/custom 中的示例，主要特点是

更改的策略是

• 重新定义 bold、italic 和 inline_code 样式，以更改它们的文字颜色，删除代码的背景，并删除 italic 的斜体属性
• 使用 TEMPLATE_OPTIONS_MERGED_VALUE 模板选项

以下是相关代码的片段

static INTRO: &str = "

Compute `height x width`
More info at *https://dystroy.org*
";

let mut printer = Printer::new(Args::command())
    .without("author")
    .with("introduction", INTRO)
    .with("options", clap_help::TEMPLATE_OPTIONS_MERGED_VALUE);
let skin = printer.skin_mut();
skin.headers[0].compound_style.set_fg(ansi(202));
skin.bold.set_fg(ansi(202));
skin.italic = termimad::CompoundStyle::with_fg(ansi(45));
skin.inline_code = termimad::CompoundStyle::with_fg(ansi(223));
skin.table_border_chars = termimad::ROUNDED_TABLE_BORDER_CHARS;
printer.print_help();

完整的示例在 /examples/custom 中，可以通过以下命令查看：cargo run --example custom -- --help

请注意，并非所有的定制都是可能的或容易的。有些可能很容易但不是很明显。如有需要，请加入聊天提问。