Crate should_color

Determine whether output should use colors or not.

The resulting color choice is determined by taking into account, in order of priority from higher to lower, the following settings:

• CLICOLOR_FORCE environment variable (requires the clicolor_force feature),
• explicit user preference (for instance command line arguments),
• CLICOLOR environment variable (requires the clicolor feature),
• NO_COLOR environment variable (requires the no_color feature),
• application default choice.

If the final choice is ColorChoice::Auto and the feature stream is enabled, the choice can be refined using ColorChoice::for_stream which takes into account the output stream.

The specification of CLICOLOR, CLICOLOR_FORCE, and NO_COLOR is inspired by:

• https://bixense.com/clicolors/,
• https://no-color.org,

with the exception that variables which are set to the empty string "" are treated as if they were unset. The reason is that it is common to override environment variables by executing programs as VAR= cmd args... and expect that VAR is unset.

CLICOLOR_FORCE

Requires the clicolor_force feature.

The meaning of the environment variable is the following:

• if not set or CLICOLOR_FORCE == "" or CLICOLOR_FORCE == "0": ignore;
• if set and CLICOLOR_FORCE != "" and CLICOLOR_FORCE != "0": ColorChoice::Always.

CLICOLOR

Requires the clicolor feature.

The meaning of the environment variable is the following:

• if not set or CLICOLOR == "": ignore;
• if set and CLICOLOR == "0": ColorChoice::Never;
• if set and CLICOLOR != "" and CLICOLOR != "0": ColorChoice::Auto.

NO_COLOR

Requires the no_color feature.

The meaning of the environment variable is the following:

• if not set or NO_COLOR == "": ignore;
• if set and NO_COLOR != "": ColorChoice::Never.

Compatibility

The goal of this crate is to merge and specify the standards proposed in https://no-color.org and https://bixense.com/clicolors/.

Please note that the proposals in the latter are slightly ambiguous and undesirable (see this issue), hence they are merely taken as an inspiration and not followed too strictly.

Relevant quote from https://no-color.org:

Command-line software which adds ANSI color to its output by default should check for a NO_COLOR environment variable that, when present and not an empty string (regardless of its value), prevents the addition of ANSI color.

Relevant quote from https://bixense.com/clicolors/:

The idea is to have the environment variables CLICOLOR and CLICOLOR_FORCE (which are currently already used for this exact reason on some UNIX systems). When set, the following rules should apply:

• CLICOLOR != 0: ANSI colors are supported and should be used when the program isn’t piped,
• CLICOLOR == 0: don’t output ANSI color escape codes,
• CLICOLOR_FORCE != 0: ANSI colors should be enabled no matter what.

Crate features

• clicolor (enabled by default) — Enables the detection of CLICOLOR via clicolor.
• clicolor_force (enabled by default) — Enables the detection of CLICOLOR_FORCE via clicolor_force.
• no_color (enabled by default) — Enables the detection of NO_COLOR via no_color.
• stream (enabled by default) — Adds ColorChoice::for_stream.
• clap — Adds clap_color and conversion of ColorChoice to and from clap::ColorChoice.

Enums

ColorChoice

Possible color choices for the output.

Constants

CLICOLORclicolor

Name of the CLICOLOR environment variable.

CLICOLOR_FORCEclicolor_force

Name of the CLICOLOR_FORCE environment variable.

NO_COLORno_color

Name of the NO_COLOR environment variable.

Functions

clap_colorclap

Compute a clap::ColorChoice suitable for the clap::App::color setting.

clicolorclicolor

Get the setting of the CLICOLOR environment variable.

clicolor_forceclicolor_force

Get the setting of the CLICOLOR_FORCE environment variable.

no_colorno_color

Get the setting of the NO_COLOR environment variable.

resolve

Resolve the output color choice from the environment variables and an explicit CLI preference.