Struct Printer

Source

pub struct Printer<'t> {
    pub full_width: bool,
    pub max_width: Option<usize>,
    /* private fields */
}

Expand description

An object which you can configure to print the help of a command

For example, changing the color of bold text and using an alternate template for the options section:

use clap::{CommandFactory, Parser, ValueEnum};
use clap_help::Printer;

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

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

    /// Comma separated list of features
    #[clap(long, value_name = "features")]
    pub features: Option<String>,
}

fn main() {
    let args = Args::parse();
    if args.help {
        let mut printer = clap_help::Printer::new(Args::command())
            .with("options", clap_help::TEMPLATE_OPTIONS_MERGED_VALUE);
        printer.skin_mut().bold.set_fg(termimad::ansi(204));
        printer.print_help();
        return;
    }
    // rest of the program
}

Fields§

§full_width: bool§max_width: Option<usize>

Implementations§

Source §

impl<'t> Printer<'t>

Source

pub fn new(cmd: Command) -> Self

Examples found in repository ?

examples/area/main.rs (line 53)

49fn main() {
50    let args = Args::parse();
51
52    if args.help {
53        Printer::new(Args::command())
54            .with("introduction", INTRO)
55            .without("author")
56            .print_help();
57        return;
58    }
59
60    let (w, h) = (args.width, args.height);
61    println!("Computation strategy: {:?}", args.strategy);
62    println!("{w} x {h} = {}", w * h);
63}

More examples

Hide additional examples

examples/with-additional-option/main.rs (line 27)

26pub fn print_help() {
27    let mut printer = clap_help::Printer::new(Args::command())
28        .without("author");
29    printer
30        .expander_mut()
31        .sub("option-lines")
32        .set("short", "-z")
33        .set("long", "--zeta")
34        .set("value", "ZETA")
35        .set("help", "Set the index of the last letter of the greek alphabet");
36    printer.print_help();
37}

examples/with-examples/main.rs (line 57)

55pub fn print_help() {
56    let args = Args::parse();
57    let mut printer = clap_help::Printer::new(Args::command())
58        .with("introduction", INTRO_TEMPLATE)
59        .without("author");
60    if args.ascii {
61        printer.skin_mut().limit_to_ascii();
62    }
63    printer.template_keys_mut().push("examples");
64    printer.set_template("examples", EXAMPLES_TEMPLATE);
65    for (i, example) in EXAMPLES.iter().enumerate() {
66        printer
67            .expander_mut()
68            .sub("examples")
69            .set("example-number", i + 1)
70            .set("example-title", example.title)
71            .set("example-cmd", example.cmd)
72            .set_md("example-comments", example.comments);
73    }
74    printer.print_help();
75}

examples/custom/main.rs (line 55)

51fn main() {
52    let args = Args::parse();
53
54    if args.help {
55        let mut printer = Printer::new(Args::command())
56            .without("author")
57            .with("introduction", INTRO)
58            .with("options", clap_help::TEMPLATE_OPTIONS_MERGED_VALUE);
59        let skin = printer.skin_mut();
60        skin.headers[0].compound_style.set_fg(ansi(202));
61        skin.bold.set_fg(ansi(202));
62        skin.italic = termimad::CompoundStyle::with_fg(ansi(45));
63        skin.inline_code = termimad::CompoundStyle::with_fg(ansi(223));
64        skin.table_border_chars = termimad::ROUNDED_TABLE_BORDER_CHARS;
65        printer.print_help();
66        return;
67    }
68
69    let (w, h) = (args.width, args.height);
70    println!("Computation strategy: {:?}", args.strategy);
71    println!("{w} x {h} = {}", w * h);
72}

Source

pub fn make_skin() -> MadSkin

Build a skin for the detected theme of the terminal (i.e. dark, light, or other)

Source

pub fn with_skin(self, skin: MadSkin) -> Self

Use the provided skin

Source

pub fn with_max_width(self, w: usize) -> Self

Set a maximal width, so that the whole terminal width isn’t used.

This may make some long sentences easier to read on super wide terminals, especially when the whole text is short. Depending on your texts and parameters, you may set up a width of 100 or 150.

Source

pub fn skin_mut(&mut self) -> &mut MadSkin

Give a mutable reference to the current skin (by default the automatically selected one) so that it can be modified

Examples found in repository ?

examples/with-examples/main.rs (line 61)

55pub fn print_help() {
56    let args = Args::parse();
57    let mut printer = clap_help::Printer::new(Args::command())
58        .with("introduction", INTRO_TEMPLATE)
59        .without("author");
60    if args.ascii {
61        printer.skin_mut().limit_to_ascii();
62    }
63    printer.template_keys_mut().push("examples");
64    printer.set_template("examples", EXAMPLES_TEMPLATE);
65    for (i, example) in EXAMPLES.iter().enumerate() {
66        printer
67            .expander_mut()
68            .sub("examples")
69            .set("example-number", i + 1)
70            .set("example-title", example.title)
71            .set("example-cmd", example.cmd)
72            .set_md("example-comments", example.comments);
73    }
74    printer.print_help();
75}

More examples

Hide additional examples

examples/custom/main.rs (line 59)

51fn main() {
52    let args = Args::parse();
53
54    if args.help {
55        let mut printer = Printer::new(Args::command())
56            .without("author")
57            .with("introduction", INTRO)
58            .with("options", clap_help::TEMPLATE_OPTIONS_MERGED_VALUE);
59        let skin = printer.skin_mut();
60        skin.headers[0].compound_style.set_fg(ansi(202));
61        skin.bold.set_fg(ansi(202));
62        skin.italic = termimad::CompoundStyle::with_fg(ansi(45));
63        skin.inline_code = termimad::CompoundStyle::with_fg(ansi(223));
64        skin.table_border_chars = termimad::ROUNDED_TABLE_BORDER_CHARS;
65        printer.print_help();
66        return;
67    }
68
69    let (w, h) = (args.width, args.height);
70    println!("Computation strategy: {:?}", args.strategy);
71    println!("{w} x {h} = {}", w * h);
72}

Source

pub fn set_template(&mut self, key: &'static str, template: &'t str)

Change a template

Examples found in repository ?

examples/with-examples/main.rs (line 64)

55pub fn print_help() {
56    let args = Args::parse();
57    let mut printer = clap_help::Printer::new(Args::command())
58        .with("introduction", INTRO_TEMPLATE)
59        .without("author");
60    if args.ascii {
61        printer.skin_mut().limit_to_ascii();
62    }
63    printer.template_keys_mut().push("examples");
64    printer.set_template("examples", EXAMPLES_TEMPLATE);
65    for (i, example) in EXAMPLES.iter().enumerate() {
66        printer
67            .expander_mut()
68            .sub("examples")
69            .set("example-number", i + 1)
70            .set("example-title", example.title)
71            .set("example-cmd", example.cmd)
72            .set_md("example-comments", example.comments);
73    }
74    printer.print_help();
75}

Source

pub fn with(self, key: &'static str, template: &'t str) -> Self

Change or add a template

Examples found in repository ?

examples/area/main.rs (line 54)

49fn main() {
50    let args = Args::parse();
51
52    if args.help {
53        Printer::new(Args::command())
54            .with("introduction", INTRO)
55            .without("author")
56            .print_help();
57        return;
58    }
59
60    let (w, h) = (args.width, args.height);
61    println!("Computation strategy: {:?}", args.strategy);
62    println!("{w} x {h} = {}", w * h);
63}

More examples

Hide additional examples

examples/with-examples/main.rs (line 58)

55pub fn print_help() {
56    let args = Args::parse();
57    let mut printer = clap_help::Printer::new(Args::command())
58        .with("introduction", INTRO_TEMPLATE)
59        .without("author");
60    if args.ascii {
61        printer.skin_mut().limit_to_ascii();
62    }
63    printer.template_keys_mut().push("examples");
64    printer.set_template("examples", EXAMPLES_TEMPLATE);
65    for (i, example) in EXAMPLES.iter().enumerate() {
66        printer
67            .expander_mut()
68            .sub("examples")
69            .set("example-number", i + 1)
70            .set("example-title", example.title)
71            .set("example-cmd", example.cmd)
72            .set_md("example-comments", example.comments);
73    }
74    printer.print_help();
75}

examples/custom/main.rs (line 57)

51fn main() {
52    let args = Args::parse();
53
54    if args.help {
55        let mut printer = Printer::new(Args::command())
56            .without("author")
57            .with("introduction", INTRO)
58            .with("options", clap_help::TEMPLATE_OPTIONS_MERGED_VALUE);
59        let skin = printer.skin_mut();
60        skin.headers[0].compound_style.set_fg(ansi(202));
61        skin.bold.set_fg(ansi(202));
62        skin.italic = termimad::CompoundStyle::with_fg(ansi(45));
63        skin.inline_code = termimad::CompoundStyle::with_fg(ansi(223));
64        skin.table_border_chars = termimad::ROUNDED_TABLE_BORDER_CHARS;
65        printer.print_help();
66        return;
67    }
68
69    let (w, h) = (args.width, args.height);
70    println!("Computation strategy: {:?}", args.strategy);
71    println!("{w} x {h} = {}", w * h);
72}

Source

pub fn without(self, key: &'static str) -> Self

Unset a template

Examples found in repository ?

examples/area/main.rs (line 55)

49fn main() {
50    let args = Args::parse();
51
52    if args.help {
53        Printer::new(Args::command())
54            .with("introduction", INTRO)
55            .without("author")
56            .print_help();
57        return;
58    }
59
60    let (w, h) = (args.width, args.height);
61    println!("Computation strategy: {:?}", args.strategy);
62    println!("{w} x {h} = {}", w * h);
63}

More examples

Hide additional examples

examples/with-additional-option/main.rs (line 28)

26pub fn print_help() {
27    let mut printer = clap_help::Printer::new(Args::command())
28        .without("author");
29    printer
30        .expander_mut()
31        .sub("option-lines")
32        .set("short", "-z")
33        .set("long", "--zeta")
34        .set("value", "ZETA")
35        .set("help", "Set the index of the last letter of the greek alphabet");
36    printer.print_help();
37}

examples/with-examples/main.rs (line 59)

55pub fn print_help() {
56    let args = Args::parse();
57    let mut printer = clap_help::Printer::new(Args::command())
58        .with("introduction", INTRO_TEMPLATE)
59        .without("author");
60    if args.ascii {
61        printer.skin_mut().limit_to_ascii();
62    }
63    printer.template_keys_mut().push("examples");
64    printer.set_template("examples", EXAMPLES_TEMPLATE);
65    for (i, example) in EXAMPLES.iter().enumerate() {
66        printer
67            .expander_mut()
68            .sub("examples")
69            .set("example-number", i + 1)
70            .set("example-title", example.title)
71            .set("example-cmd", example.cmd)
72            .set_md("example-comments", example.comments);
73    }
74    printer.print_help();
75}

examples/custom/main.rs (line 56)

51fn main() {
52    let args = Args::parse();
53
54    if args.help {
55        let mut printer = Printer::new(Args::command())
56            .without("author")
57            .with("introduction", INTRO)
58            .with("options", clap_help::TEMPLATE_OPTIONS_MERGED_VALUE);
59        let skin = printer.skin_mut();
60        skin.headers[0].compound_style.set_fg(ansi(202));
61        skin.bold.set_fg(ansi(202));
62        skin.italic = termimad::CompoundStyle::with_fg(ansi(45));
63        skin.inline_code = termimad::CompoundStyle::with_fg(ansi(223));
64        skin.table_border_chars = termimad::ROUNDED_TABLE_BORDER_CHARS;
65        printer.print_help();
66        return;
67    }
68
69    let (w, h) = (args.width, args.height);
70    println!("Computation strategy: {:?}", args.strategy);
71    println!("{w} x {h} = {}", w * h);
72}

Source

pub fn template_keys_mut(&mut self) -> &mut Vec<&'static str>

A mutable reference to the list of template keys, so that you can insert new keys, or change their order. Any key without matching template will just be ignored

Examples found in repository ?

examples/with-examples/main.rs (line 63)

55pub fn print_help() {
56    let args = Args::parse();
57    let mut printer = clap_help::Printer::new(Args::command())
58        .with("introduction", INTRO_TEMPLATE)
59        .without("author");
60    if args.ascii {
61        printer.skin_mut().limit_to_ascii();
62    }
63    printer.template_keys_mut().push("examples");
64    printer.set_template("examples", EXAMPLES_TEMPLATE);
65    for (i, example) in EXAMPLES.iter().enumerate() {
66        printer
67            .expander_mut()
68            .sub("examples")
69            .set("example-number", i + 1)
70            .set("example-title", example.title)
71            .set("example-cmd", example.cmd)
72            .set_md("example-comments", example.comments);
73    }
74    printer.print_help();
75}

Source

pub fn template_order_mut(&mut self) -> &mut Vec<&'static str>

👎Deprecated since 0.6.2: use template_keys_mut instead

A mutable reference to the list of template keys, so that you can insert new keys, or change their order. Any key without matching template will just be ignored

Source

pub fn expander_mut(&mut self) -> &mut OwningTemplateExpander<'static>

Give you a mut reference to the expander, so that you can overload the variable of the expander used to fill the templates of the help, or add new variables for your own templates

Examples found in repository ?

examples/with-additional-option/main.rs (line 30)

26pub fn print_help() {
27    let mut printer = clap_help::Printer::new(Args::command())
28        .without("author");
29    printer
30        .expander_mut()
31        .sub("option-lines")
32        .set("short", "-z")
33        .set("long", "--zeta")
34        .set("value", "ZETA")
35        .set("help", "Set the index of the last letter of the greek alphabet");
36    printer.print_help();
37}

More examples

Hide additional examples

examples/with-examples/main.rs (line 67)

55pub fn print_help() {
56    let args = Args::parse();
57    let mut printer = clap_help::Printer::new(Args::command())
58        .with("introduction", INTRO_TEMPLATE)
59        .without("author");
60    if args.ascii {
61        printer.skin_mut().limit_to_ascii();
62    }
63    printer.template_keys_mut().push("examples");
64    printer.set_template("examples", EXAMPLES_TEMPLATE);
65    for (i, example) in EXAMPLES.iter().enumerate() {
66        printer
67            .expander_mut()
68            .sub("examples")
69            .set("example-number", i + 1)
70            .set("example-title", example.title)
71            .set("example-cmd", example.cmd)
72            .set_md("example-comments", example.comments);
73    }
74    printer.print_help();
75}

Source

pub fn print_template(&self, template: &str)

Print the provided template with the printer’s expander

It’s normally more convenient to change template_keys or some templates, unless you want none of the standard templates

Source

pub fn print_help(&self)

Print all the templates, in order

Examples found in repository ?

examples/area/main.rs (line 56)

49fn main() {
50    let args = Args::parse();
51
52    if args.help {
53        Printer::new(Args::command())
54            .with("introduction", INTRO)
55            .without("author")
56            .print_help();
57        return;
58    }
59
60    let (w, h) = (args.width, args.height);
61    println!("Computation strategy: {:?}", args.strategy);
62    println!("{w} x {h} = {}", w * h);
63}

More examples

Hide additional examples

examples/with-additional-option/main.rs (line 36)

26pub fn print_help() {
27    let mut printer = clap_help::Printer::new(Args::command())
28        .without("author");
29    printer
30        .expander_mut()
31        .sub("option-lines")
32        .set("short", "-z")
33        .set("long", "--zeta")
34        .set("value", "ZETA")
35        .set("help", "Set the index of the last letter of the greek alphabet");
36    printer.print_help();
37}

examples/with-examples/main.rs (line 74)

55pub fn print_help() {
56    let args = Args::parse();
57    let mut printer = clap_help::Printer::new(Args::command())
58        .with("introduction", INTRO_TEMPLATE)
59        .without("author");
60    if args.ascii {
61        printer.skin_mut().limit_to_ascii();
62    }
63    printer.template_keys_mut().push("examples");
64    printer.set_template("examples", EXAMPLES_TEMPLATE);
65    for (i, example) in EXAMPLES.iter().enumerate() {
66        printer
67            .expander_mut()
68            .sub("examples")
69            .set("example-number", i + 1)
70            .set("example-title", example.title)
71            .set("example-cmd", example.cmd)
72            .set_md("example-comments", example.comments);
73    }
74    printer.print_help();
75}

examples/custom/main.rs (line 65)

51fn main() {
52    let args = Args::parse();
53
54    if args.help {
55        let mut printer = Printer::new(Args::command())
56            .without("author")
57            .with("introduction", INTRO)
58            .with("options", clap_help::TEMPLATE_OPTIONS_MERGED_VALUE);
59        let skin = printer.skin_mut();
60        skin.headers[0].compound_style.set_fg(ansi(202));
61        skin.bold.set_fg(ansi(202));
62        skin.italic = termimad::CompoundStyle::with_fg(ansi(45));
63        skin.inline_code = termimad::CompoundStyle::with_fg(ansi(223));
64        skin.table_border_chars = termimad::ROUNDED_TABLE_BORDER_CHARS;
65        printer.print_help();
66        return;
67    }
68
69    let (w, h) = (args.width, args.height);
70    println!("Computation strategy: {:?}", args.strategy);
71    println!("{w} x {h} = {}", w * h);
72}