ANSI coloring and styling

Using colors in the command line tool’s output does not just look good: contrasting important elements like argument names from the rest of the text reduces the cognitive load on the user. argparse uses ANSI escape sequences to add coloring and styling to the error messages and help text. In addition, argparse offers public API to apply colors and styles to any text printed to the console (see below).

Styles and colors

The following styles and colors are available in argparse.ansi submodule:

Font styles:

bold
italic
underline

Colors:

Foreground	Background
`black`	`onBlack`
`red`	`onRed`
`green`	`onGreen`
`yellow`	`onYellow`
`blue`	`onBlue`
`magenta`	`onMagenta`
`cyan`	`onCyan`
`lightGray`	`onLightGray`
`darkGray`	`onDarkGray`
`lightRed`	`onLightRed`
`lightGreen`	`onLightGreen`
`lightYellow`	`onLightYellow`
`lightBlue`	`onLightBlue`
`lightMagenta`	`onLightMagenta`
`lightCyan`	`onLightCyan`
`white`	`onWhite`

There is also a “virtual” style noStyle that means no styling is applied. It’s useful in ternary operations as a fallback for the case when styling is disabled. See below example for details.

All styles above can be combined using . and even be used in regular output:

import argparse.ansi;

void printText(bool enableStyle)
{
    // style is enabled at runtime when `enableStyle` is true
    auto myStyle = enableStyle ? bold.italic.cyan.onRed : noStyle;

    // "Hello" is always printed in green;
    // "world!" is printed in bold, italic, cyan and on red when `enableStyle` is true, or "as is" otherwise
    writeln(green("Hello "), myStyle("world!"));
}

printText(true);
printText(false);

The following example shows how styling can be used in custom help text (Usage, Description, ShortDescription, Epilog API):

import argparse;
import argparse.ansi;

struct T
{
    @(NamedArgument("red").Description(bold.underline("Colorize the output:")~" make everything "~red("red")))
    bool red_;
}

T t;
CLI!T.parseArgs(t, ["-h"]);

Here is how help screen will look like:

Enable/disable the styling

By default argparse will try to detect whether ANSI styling is supported, and if so, it will apply styling to the help text.

There is Config.stylingMode parameter that can be used to override default behavior:

If it’s set to Config.StylingMode.on, then styling is always enabled.
If it’s set to Config.StylingMode.off, then styling is always disabled.
If it’s set to Config.StylingMode.autodetect, then heuristics are used to determine whether styling will be applied.

In some cases styling control should be exposed to a user as a command line argument (similar to --color argument in ls or grep command). argparse supports this use case – just add an argument to a command (it can be customized with @NamedArgument UDA):

import argparse;

struct T
{
    static auto color = ansiStylingArgument;
}

T t;
CLI!T.parseArgs(t, ["-h"]);

// This is a way to detect whether `--color` argument was specified in the command line
// Note that 'autodetect' is converted to either 'on' or 'off'
assert(CLI!T.parseArgs(t, ["--color"]));
assert(t.color);

assert(CLI!T.parseArgs(t, ["--color=always"]));
assert(t.color);

assert(CLI!T.parseArgs(t, ["--color=never"]));
assert(!t.color);

This will add the following argument:

Heuristics for enabling styling

Below is the exact sequence of steps argparse uses to determine whether or not to emit ANSI escape codes (see detectSupport() function here for details):

If environment variable NO_COLOR != "", then styling is disabled. See here for details.
If environment variable CLICOLOR_FORCE != "0", then styling is enabled. See here for details.
If environment variable CLICOLOR == "0", then styling is disabled. See here for details.
If environment variable ConEmuANSI == "OFF", then styling is disabled. See here for details.
If environment variable ConEmuANSI == "ON", then styling is enabled. See here for details.
If environment variable ANSICON is defined (regardless of its value), then styling is enabled. See here for details.
Windows only (version(Windows)):
1. If environment variable TERM contains "cygwin" or starts with "xterm", then styling is enabled.
2. If GetConsoleMode call for STD_OUTPUT_HANDLE returns a mode that has ENABLE_VIRTUAL_TERMINAL_PROCESSING set, then styling is enabled.
3. If SetConsoleMode call for STD_OUTPUT_HANDLE with ENABLE_VIRTUAL_TERMINAL_PROCESSING mode was successful, then styling is enabled.
Posix only (version(Posix)):
1. If STDOUT is not redirected, then styling is enabled.
If none of the above applies, then styling is disabled.

Last modified: 09 November 2024