feat(AppSettings): Enable user-defined colors for help message

[codeinred]

Introduction

This pull request adds support for configuring colors and styles in Clap. It does this by adding a StyleSpec class that holds information about the termcolor::ColorSpecs associated with various styles. This is added as a component of the App class, and it allows users to set colors, styles, and other such aspects of Clap.

For example, I can now write the following:

use clap::{Color, IntoApp, Parser, Style};

fn main() {
    let app = Args::into_app()
        .bold(Style::Good, true)
        .bold(Style::Warning, true)
        .foreground(Style::Warning, Some(Color::Green));

    // ...

In this example, this will set text displayed in Style::Good and Style::Warning to bold, and also update the warning style color to Green.

Before Customization:

After Customization:

Motivation

I wanted to be able to make help flags and section headers display in bold for greater readability. Adding support for the ability to customize that involved a rework of a lot of Colorizer code, and it wasn't much additional work to enable other customizations as well.

Changes to clap's API

This section documents changes to the public API of clap

Newly exposed types:

• Expose clap::output::fmt::Style as clap::Style
• Expose termcolor::Color as clap::Color
• Expose termcolor::ColorSpec as clap::ColorSpec

Additions to App

The following functions were added to App, to enable users to customize colors and styles:

pub fn style(mut self, style: Style, spec: termcolor::ColorSpec) -> Self;
pub fn bold(mut self, style: Style, value: bool) -> Self;
pub fn italic(mut self, style: Style, value: bool) -> Self;
pub fn underline(mut self, style: Style, value: bool) -> Self;
pub fn dimmed(mut self, style: Style, value: bool) -> Self;
pub fn intense(mut self, style: Style, value: bool) -> Self;
pub fn foreground(mut self, style: Style, color: Option<Color>) -> Self;
pub fn background(mut self, style: Style, color: Option<Color>) -> Self;

A note on the Style enum

This pull request functions within the bounds of the Style enum already defined by Clap, inside src/output/fmt.rs. We may want to give the options defined in this enum more descriptive names (for example, Style::Warning would become Style::SectionHeader, which is what it's used for when printing --help). We may also want to increase the number of styles (so that there's a Warning style and a SectionHeader style)

Internal additions / changes

• Create StyleSpec, which holds a ColorSpec for each Style
• Make StyleSpec a parameter of Colorizer::new
• Update all uses of Colorizer::new to include a StyleSpec

Related issues and discussions

Issues:

• Resolves #2963: Make colored help output more compatible with an applications overall theme by enabling users to customize colors as necessary to match their application theme

Discussions:

• See also #2906 Challenges with Colored Help

[epage]

Thank you for your interest in solving this but we have previously rejected extending the API like this (#3234). I'd recommend starting new design discussions in issues rather than PRs to help catch things like this before putting in all of this effort.

Other high level thoughts just so you have an idea on how we think about these things for future contributions

• We have to worry about API stability and the current styles are not ready to be exposed. API stability isn't just about what names are but expectations for how they are used. We can make it so we can add more entries to the enum but dramatically changing how they apply will break user expectations.
• This API feels backwards. an app shouldn't be responsible for applying formatting to styles in the style sheet. Instead the user should be defining the formatting of a style and passing that in, overriding the built-in style.