Allow good/warning/error/hint color to be customized

[milesj]

Please complete the following tasks

• I have searched the discussions
• I have searched the existing issues

Clap Version

3.0.0-rc.9

Describe your use case

I would like to use colored help/errors/etc in our CLI, but would like to change the colors to match our "brand".

Describe the solution you'd like

Provide a setting for good/warning/error/hint that allows the ANSI color code to be provided, based on the 256 table (or maybe 16m if you're crazy). https://upload.wikimedia.org/wikipedia/commons/1/15/Xterm_256color_chart.svg

It may be better to name the colors based on their actual usage, like arg/bin/label, etc.

Alternatives, if applicable

No response

Additional Context

No response

[epage]

One challenge with this is the API. We can't accept ANSI escape codes because clap3 intentionally added support for non-ANSI Windows terminals. We could copy the enums for color selections but we'd also need styling and the ability to compose them together. We end up starting to duplicate a decent chunk of a terminal styling API which we are hesitant to do (#1790 is a bit more extreme of an example).

We've been instead preferring for feedback on #2963 for improving our defaults and #2914 for allowing people to more thoroughly customize things when those defaults don't work.

It may be better to name the colors based on their actual usage, like arg/bin/label, etc.

We've been moving in that direction. Originally, it was named after the color but the color also implied some other styling with it. The next step is for us to split off --help parts from abusing the existing semantics and giving them their own. Since this is internal, this isn't too much of a priority though will be addressed as part of #2963 and #2389.

would like to change the colors to match our "brand".

Mind elaborating what is "ok" and what runs counter to your "brand"? In what way does it run counter?

[milesj]

@epage That all makes sense. I've had enough experience with ANSI and CLI tools so I totally get it.

As for the branding piece, the colors are shades of purple/blue/teal. Here's an example of the log output.

And this is where the colors are configured if you're curious: https://github.com/milesj/moon/blob/master/crates/logger/src/color.rs

[epage]

If you have any feedback or proposals for #2963, could you post it there?

Also, how important are errors or is the main concern the help?

Also, for anyone finding this issue, something that can help for re-evaluating is examples of precedence for this (like dialoguer) and proposals for how this would work either with older Windows support or why we can justify only supporting ANSI escape codes.

Otherwise, at this time I am closing out this issue, since there is no plan to grow the clap API to support this.

[epage]

Since this was closed, I've started work on https://github.com/epage/anstyle which aims to allow color definitions to be used in an API independent of the implementation which will allow users to define their stylesheet.

Blocked on https://github.com/epage/anstyle/issues/14

[epage]

From reddit

My preferred solution would be that, when customization is figured out, have the existing color behavior as some sort of easy to select "preset".

We could include presets for color schemes to help get people going.

[nyurik]

I recently switch to v4, and the lack of help colors is a bit disheartening - I grew fond of seeing colors in all the "cool new Rust-based Linux tools", and that color is what instantly made these tools stand apart from the old GNU tools. Now Clap only uses bold/underline, while continuing to call it "color". I tried to re-enable the legacy colors somehow, but despite searching all the release notes that only mention it in passing, and skimming through a very lengthy discussion on removing colors, I am beginning to suspect it is not (yet) possible.

To avoid breaking existing functionality, I feel v4 should have included the support for existing color styling from the beginning, even if it would require something like #[clap(legacy_color_scheme = true)].

Is this what is planned for the next release? Regardless of the minor grief above, thank you for all the hard work on Clap - it's one of the best crates we have in Rust! :)

[epage]

@nyurik

I tried to re-enable the legacy colors somehow, but despite searching all the release notes that only mention it in passing, and skimming through a very lengthy discussion on removing colors, I am beginning to suspect it is not (yet) possible.

#4132 summarizes all of the help changes and includes workarounds, where possible.

For this case, it says

Users can't rollback until theming support is in (#3234) though they can just disable the coloring with Command::disable_colored_help(true)

@nyurik

legacy_color_scheme

Such a flag is not going to be supported. Instead, our focus will be to theming

@nyurik

Is this what is planned for the next release

We do not commit to specific features for a "next release" as we we release on almost every PR made.

Addressing color support, in general, is a priority though. The main thing blocking theming support is releasing a 1.0 of https://docs.rs/anstyle/latest/anstyle/ which is blocked on getting more feedback on the API / more runtime to make sure the API is good for a 1.0 release, see https://github.com/epage/anstyle/issues/14, see also my earlier comment

As it becomes a chicken and egg problem, my plan has been to implement styling support in #3108 / #1433 as that will at least give me some experience with anstyle to decide when its ready to go 1.0 and be safe to use in other crate's APIs.

[nyurik]

Thanks @epage for such a great in-depth reply! I think we should modify the CHANGELOG file (and possibly the release v4 comment) -- to make it clearer. I searched for the word "color", and nothing came up. I found this

We've moved to a more neutral palette for highlighting elements (not highlighted above)

which is not a good explanation when a highly visible breaking change is introduced. Perhaps something like this text? I will be happy to make a pull request.

We have removed colored help in favor of bold and underlined text. There is currently no way to re-enable the old color scheme until the styling (#3108 / #1433) is implemented.

[epage]

As I'm trying to focus to get other things done so I can get back to that work, I do not have time to litigate a discussion about how to handle this (sorry, you are partly getting the short end of the stick from some other individuals taking up too much time / attention). As that is the case, we'll leave it as-is for now.

[dhruvkb]

"default" could be a good name for the default value, and "possibilities" for the possible values. That seems the most intuitive to me.

[epage]

I don't want to create a style per one of these bracketed items as that doesn't scale well for us to add more in the future.

Note: there is also one for env variables

[epage]

Besides naming the styling element for defaults, possible values, and env variables, I'm curious on how people think we should style it.

Some options I thought of:

• {spec}[default: true]{reset} (all styled the same)
• {spec}[default: {literal}true{reset}{spec}]{reset} (outer-styled, value stuled)
• [{spec}default:{reset} {literal}true{reset}] (key-styled, values-styled)

[nyurik]

I might be misunderstanding the last post - if {spec}, {literal}, and {reset} are ANSI color escape sequences, why does it say "all styled the same"?

I think the 1st variant is a subset of the 2nd (i.e. if literal style is the same as the spec) - so I would think the 2nd variant is preferred as it offers more flexibility. I also think that by default literal and spec should be the same color (thus producing the 1st variant) - as less color-disruptive (I wouldn't want my help screen to look like the early days of MS Word with word-art, with everyone using every single font available to print a flier). I am not a big fan of the 3rd.

[epage]

I might be misunderstanding the last post - if {spec}, {literal}, and {reset} are ANSI color escape sequences, why does it say "all styled the same"?

Sorry, forgot to go back and fix those

I think the 1st variant is a subset of the 2nd (i.e. if literal style is the same as the spec) - so I would think the 2nd variant is preferred as it offers more flexibility. I also think that by default literal and spec should be the same color (thus producing the 1st variant) - as less color-disruptive (I wouldn't want my help screen to look like the early days of MS Word with word-art, with everyone using every single font available to print a flier). I am not a big fan of the 3rd.

The difference between (1) and (2) is literal is an existing style, used by --flags and acts like backticks in markdown.

[nyurik]

thx, in that case yes, I think the 2nd is the best because it would allow this help screen (from above):

to be consistent for both the default and possible values:

display icons next to node names {spec}[default: true] [possible values: true, false]{reset}

[epage]

To be clear, (2) would cause true, true, and false to be teal like --icons, --align, and --multi-cols.

I hesitate about (2) because we want to draw attention to literals in the first column and in usage but it feels weird to in the help description, it might be too bus.

btw this is the current way we highlight something similar in errors

                        let _ = write!(styled, "\n{TAB}[possible values: ");
                        if let Some((last, elements)) = possible_values.split_last() {
                            for v in elements {
                                let _ = write!(
                                    styled,
                                    "{}{}{}, ",
                                    valid.render(),
                                    Escape(v),
                                    valid.render_reset()
                                );
                            }
                            let _ = write!(
                                styled,
                                "{}{}{}",
                                valid.render(),
                                Escape(last),
                                valid.render_reset()
                            );
                        }
                        styled.push_str("]");

[nyurik]

I think the most ideal for discussion is some real rendering image of all variants, perhaps in a few default variants (console vs markdown)? Kinda tricky to discuss it in a plain text format.

P.S. your code example made me realize it could use some DRY, so I made a #4876 PR - hope its ok - deletes 23 lines :)

[AndreasBackx]

I was working on some tooling that makes it easier for people to switch over from x to Rust and came across this Python Click library to add colours to --help. I noticed it allows overriding colours per command as well. I could see it being useful where you colour some subcommands red to showcase they might be destructive or might require you being an admin or something (not referring to OS level root/admin but for whatever tool is being built). https://github.com/click-contrib/click-help-colors

Food for thought, could be something that needs thinking about for this particular issue as well.

[epage]

I think that would be a useful feature and, with the plugin system I've been adding to clap, it should minimize some of the negative effects of adding it.

The question for this thread is if there is anything about that that would require breaking changes to the existing feature before we stabilize it. The rest can be deferred out into its own issue.

Unfortunately, not seeing a quick reference, so from what I gather they allow

• help_headers_color
• help_options_color
• help_options_custom_colors (maps arg or command to color)
• prog_name_color (for --version)
• version_color (for --version)
• message_color (for --version)

All of that can be set on a per-command basis

One problem I see with what we currently do is we copy out styles to subcommand but we overwrite the subcommand, rather than allowing the subcommand to have special behavior.

Our style sheet is more fine grained in areas but doesn't allow controlling prog name and version separately. Our plugin system would offer a better way for coloring most things (color set directly on arg rather than in a map) but it won't let us easily hit things like version but we allow setting the version as styled./

For if/when we support per-arg and per-command styling, we'll need to make sure StyledStr can be sorted agnostic of styling.

[epage]

A new release is out that re-exports anstyle and includes some more examples

[epage]

As for styling of defaults, https://github.com/Canop/clap-help is somewhat similar to one of the options being considered.

[gibfahn]

The default example in https://github.com/Canop/clap-help#with-clap-help seems quite hard to read to me (compared to the current output), it's hard to see which option in the left column maps to which description on the right column, and it's hard to see where one option's help ends and the next one begins in the right column.

This is even more true when you have more detailed help text with examples for the options.

[epage]

I was more wanting to highlight how it styling the text (which ties into this issue) and not the wider formatting change

[epage]

At this point, the remaining open questions are

• How should [default: value] be styled / support styling
  • I'm leaning towards a uniform style for the whole block of text which means we won't use an existing style and can add this later. I'll create an issue for tracking this
  • EDIT: Allow customizing styling of [default], [possible values], [env] in arg description #5093
• Any future extensibility for customization
  • I'm thinking we shouldn't further block on this and create a separaet issue. @AndreasBackx mind creating an issue?

So at this point, I think I'm going to move towards stabilization

[donovanglover]

It took me some time to figure this out, but here's an example of adding color to --help.

use clap::builder::styling::{AnsiColor, Effects, Styles};
use clap::Parser;

fn styles() -> Styles {
    Styles::styled()
        .header(AnsiColor::Red.on_default() | Effects::BOLD)
        .usage(AnsiColor::Red.on_default() | Effects::BOLD)
        .literal(AnsiColor::Blue.on_default() | Effects::BOLD)
        .placeholder(AnsiColor::Green.on_default())
}

#[derive(Parser)]
#[command(author, version, about, styles = styles())]
pub struct Cli {
    // ...
}

[murlakatamenka]

It took me some time to figure this out, but here's an example of adding color to --help.

use clap::builder::styling::{AnsiColor, Effects, Styles};
use clap::Parser;

fn styles() -> Styles {
    Styles::styled()
        .header(AnsiColor::Red.on_default() | Effects::BOLD)
        .usage(AnsiColor::Red.on_default() | Effects::BOLD)
        .literal(AnsiColor::Blue.on_default() | Effects::BOLD)
        .placeholder(AnsiColor::Green.on_default())
}

#[derive(Parser)]
#[command(author, version, about, styles = styles())]
pub struct Cli {
    // ...
}

Piggybacking on this, since Styles::styled is const:

use clap::{
    builder::styling::{AnsiColor as Ansi, Styles},
    Parser,
};

const MY_AWESOME_STYLE: Styles = Styles::styled()
    .header(Ansi::Red.on_default().bold())
    .usage(Ansi::Red.on_default().bold())
    .literal(Ansi::Blue.on_default().bold())
    .placeholder(Ansi::Green.on_default());

#[derive(Parser)]
#[command(styles = MY_AWESOME_STYLE)]
pub struct Cli {
    // ...
}

fn main() {
    let _cli = Cli::parse();
}

Clap v3 Style:

• https://docs.rs/clap/4.5.2/clap/builder/struct.Styles.html#example

rustic's style:

• https://github.com/rustic-rs/rustic/blob/6fffaad1cc1aeebf874063fc62125f4ce3b490b5/src/commands.rs#L143-L149

[MilesCranmer]

Here's an example of manually customizing the colors in the help template:

https://github.com/MilesCranmer/rip2/blob/29b46efbff046515360cf5a16bdbae678db90b37/src/args.rs#L8-L83

Both in the text (with anstyle render) and by letting clap do it.

On white background:

And dark:

(Same color scheme as cargo)