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

[milesj]

Please complete the following tasks

• [X] I have searched the discussions
• [X] 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 https://github.com/clap-rs/clap/issues/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 https://github.com/clap-rs/clap/issues/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 (https://github.com/clap-rs/clap/issues/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.

[casey]

Is this the issue to follow for color support? I'd like to upgrade to clap v4, but the lack of colored help is a blocker. I found this issue, but the title is a little ambiguous.

[epage]

Yes, this is the issue in that it will let you color the help as you wish

[dream-dasher]

Same as @casey. A sea of almost identical white text adds a lot of parse work to the user. And drains a lot of joy. A hard no for any app with an ounce of kindness, imo.

I'm glad to see that v3 documentation still exists though!

Is the plan to make color default again with specification possible or only allow color via manual specification? (If the later then that's a level of friction not consistent with my use case [I'm just looking to for very basic, readable user interfaces] and would just like to have a sense of trajectory before I invest in this system. [new to rust and trying to find cli app frameworks that let me focus on non-interface elements -- thanks in advance for any answer] )

[epage]

The plan is to add customization of whats already there. If someone wants to come up with a counter proposal for colors that meets the stated goals, we'll evaluate adopting it. So far, no one has taken up that offer. Once we allow customization, we're hoping people will do that implicitly and we'll watch to see what develops in the community.

As for other Rust CLI parsers, I believe they all have less text styling than clap.

[dream-dasher]

Thanks for the response @epage. I'm not at a place in my journey where I can fruitfully offer help on that issue. (maybe eventually!) I'll look into front-ending my rust code with another language and use one of their frameworks. (which seems funny for a cli, but different eco-systems are in different places)

Thanks for all the work you are doing! I can only imagine being the de facto face of argument parsing for the language is a lot of responsibility and makes decisions that leave any given set-up less supported feel very weighty.

[dream-dasher]

I've noticed that piping the output of clap into bat 🦈 🦇 gives excellent default highlighting. (i.e. easy to scan and parse)

Having only just begun looking at these crates (clap & bat's library) it's not immediately clear how to run the clap output through bat library and gain syntax advantages. (much less apply syntax processing during compilation vs runtime)

But a crate extension that enabled coloring that works on _many/most terminals, but, being an extension, needn't support the same breadth as clap seems to me to be a possible workaround.

Having an extension that deals with colorschemes and plugs into output syntax also seems like it might be a nice decoupling for the project.

Not sure how many suggestions you want from the peanut gallery. 🥜 🎪 But as far as the core code existing (though possibly not cleanly interfaceable ways 🤷) -- this does look like a promising approach from the outside.

Any thoughts? Has this been considered and reject previously? (e.g. due to code being so runtime focused that it couldn't easily get worked into a compile time extension)

---

Below, an example of runtime syntax parsing and highlighting of clap output, using the QuickStart Derive example from current docs (v4.1)

[epage]

Not sure how many suggestions you want from the peanut gallery. 🥜 🎪 But as far as the core code existing (though possibly not cleanly interfaceable ways 🤷) -- this does look like a promising approach from the outside.

Any thoughts? Has this been considered and reject previously? (e.g. due to code being so runtime focused that it couldn't easily get worked into a compile time extension)

This is a fairly complex solution with a large binary size and build-time impact. The proposed solution in this PR is relatively simple and mall; I just need to wrap up another project first.

[epage]

Support for this is now available as Command::styles with v4.2.3 when the unstable-styles feature is enabled.

Note: we are not guaranteeing semver compatibility on this feature until the feature flag is removed.

[dhruvkb]

Thank you @epage! Are there any examples/docs we can refer to? The docs for Command::styles seem to be incorrectly copied from Command::color.

[epage]

clap-rs/clap#4845 is correcting it

[epage]

I guess one question is whether we should re-export anstyle (and how) or require people to depend on it directly.

Re-exports are more convenient (no need for extra dep) and keep things in sync (though anstyle will hopefully never go 2.0 or if it does, we;'ll have a long time inbetween).

My guess is we could expose it as clap::builder::style.

Thoughts?

[dhruvkb]

I like the idea of re-exporting as it prevents the developer from needing to worry about compatibility 👍.

On a side note, I use the, derive notation but have to import Styles from clap::builder.

#[command(styles=clap::builder::Styles::plain())]
pub struct Arguments {
}

[DianaNites]

As a user, I always prefer when a libraries public dependencies are re-exported, the way I see it, its not my dependency, its the libraries, and I don't want to have to manage it in my Cargo.toml

As for how, I think re-exporting from the crate root is the best when its an entire dependency rather than just a type or few.

[epage]

On a side note, I use the, derive notation but have to import Styles from clap::builder.

That is true of a lot of functionality. We onlyh re-export the core types in the root.

[epage]

As for how, I think re-exporting from the crate root is the best when its an entire dependency rather than just a type or few.

(Emphasis mine)

If anstyle wasn't an independent crate, I'd most likely expose it in clap::builder or clap::builder::style.

I feel like a similar approach should be taken with re-exports. I feel like dumping it in the root without taking into account any other considerations can lead to a bloated root, making it harder to find things, and a less cohesive experience.

But getting opinions out like this is why I didn't immediately re-export but brought it up here so I can see what different people's thoughts were.

[bryantbiggs]

any pointers on how to enabled styled output - I've followed @dhruvkb snippet above but the output looks the same as before (and I enabled the colors and unstable-styles features as well)

[epage]

@bryantbiggs can you provide a minimal, complete reproduction case for whats not working for you, with a description of what you'd expect?

[dhruvkb]

I was able to color the section headers and argument names using this snippet (building on the styled_str.rs source file.

pub fn get_styles() -> clap::builder::Styles {
	clap::builder::Styles::styled()
		.header(
			anstyle::Style::new()
				.bold()
				.underline()
				.fg_color(Some(anstyle::Color::Ansi(anstyle::AnsiColor::Blue))),
		)
		.literal(
			anstyle::Style::new()
				.bold()
				.fg_color(Some(anstyle::Color::Ansi(anstyle::AnsiColor::Cyan))),
		)
}

#[command(styles=get_styles())]
pub struct Arguments {
	// ...
}

[eatradish]

Doesn't seem to be available in the builder api? (clap 4.2.4 with "cargo", "wrap_help", "unstable-styles", "color" features, rustc 1.68.2)

error[E0603]: struct `Styles` is private
  --> src/args.rs:1:37
   |
1  | use clap::{builder::{PossibleValue, Styles}, command, Arg, ArgAction, Command};
   |                                     ^^^^^^ private struct
   |
note: the struct `Styles` is defined here
  --> /home/saki/.cargo/registry/src/github.com-1ecc6299db9ec823/clap_builder-4.2.4/src/builder/mod.rs:66:16
   |
66 | pub(crate) use styled_str::Styles;
   |                ^^^^^^^^^^^^^^^^^^

error[E0599]: no method named `styles` found for struct `Command` in the current scope
  --> src/args.rs:49:10
   |
49 |         .styles(Styles::styled().usage(Default::default()))
   |          ^^^^^^ help: there is a method with a similar name: `get_styles`

Some errors have detailed explanations: E0599, E0603.
For more information about an error, try `rustc --explain E0599`.

[epage]

@eatradish did you run cargo add clap -F unstable-styles?

I wish rustc would partially parse disabled cfgs so it could tell suggest the feature to you

[eatradish]

@eatradish did you run cargo add clap -F unstable-styles?

I wish rustc would partially parse disabled cfgs so it could tell suggest the feature to you

My fault, I have set this version in Cargo.toml:

clap = { version = "4.2", features = ["cargo", "wrap_help", "color", "unstable-styles"] }

But the right thing to do is:

clap = { version = "4.2.4", features = ["cargo", "wrap_help", "color", "unstable-styles"] }