It is possible to customize the appearance of help, usage, version, error, and warning messages using a dedicated style file, given as ARGPARSER_STYLE_FILE, with the same format as the configuration file. The usage of the legacy and less powerful environment variables, viz. ARGPARSER_HELP_STYLE, ARGPARSER_USAGE_STYLE, ARGPARSER_VERSION_STYLE, ARGPARSER_ERROR_STYLE, and ARGPARSER_WARNING_STYLE, is considered deprecated and will be disabled in v2.0.0.
The colorization and stylization of the messages works by using Select Graphic Rendition (SGR) ANSI escape sequence codes. Employing colors is especially useful to quickly see errors when logging, but requires that the terminal or text editor, with which you opened the log file, supports interpreting the escape codes. This is, e.g., supported by less --raw-control-chars <filename>. Thereby, when ARGPARSER_USE_STYLES is set to "tty" (the default), the escape sequences are only output when STDOUT/STDERR is a terminal, not a file. The value "never" deactivates the styles even for terminals—whereas "always" activates them for both, and "file" only for files, not terminals.
To adhere to the informal no-color standard, the Argparser supports the NO_COLOR environment variable. If given, and not set to the empty string, you can globally disable ANSI colorization in any software supporting the standard, including the Argparser. You can then selectively re-enable colorization for the Argparser using ARGPARSER_USE_STYLES={always,file,tty}. Thereby, if ARGPARSER_USE_STYLES or the (deprecated) ARGPARSER_USE_STYLES_IN_FILES are given in the environment, including their occurrence on the command line or in a configuration file, they unconditionally override NO_COLOR, in line with the standard. This allows instructing no software to use colors, except of the Argparser, if wanted.
The available colors and styles offer a detailled way of customizing the look of messages. Besides being possible to colorize and stylize the actual text of the messages, usage, version, error and warning messages, as well as the argument groups in help messages, can be surrounded by frames, serving as visual grouping to blocks. These frame styles use characters from the Unicode Box Drawing block. For maximum compatibility with output devices, the Argparser currently does not use the frames by default, you have to opt into them by using an ARGPARSER_STYLE_FILE.
The following colors and styles are available (with the actual appearance depending on the output device):
Tab. 2: Available colors and styles.
| Colors | Text styles | Frame styles |
|---|---|---|
normal |
angular |
|
bold |
rounded |
|
faint |
double |
|
italic |
solid |
|
underline |
double-dashed |
|
double |
triple-dashed |
|
overline |
quadruple-dashed |
|
crossed-out |
thin |
|
blink |
thick |
|
reverse |
double |
Colors overwrite each other, whereas styles may be combined, like "red,bold,reverse" as default value for error message captions, or "red,rounded" for error message frames in the template styles.cfg. Text styles may be given in any order, while frame styles are only in part compatible (e.g., there is no way to specify thick, rounded corners since Unicode lacks characters for them); for colors, the last one is effectively visible. Still, the escape codes are concatenated in their order of definition in the style setting.
You can prefix color names with bright_ to obtain the bright ANSI colors, and suffix them with _fg or _bg to use them as either a foreground or background color. Without suffix, the color is used as foreground color. Be wary, however, that not all terminals support bright or background colors and may use substitute colors or ignore the escape sequences. Thus, the Argparser does not, and will never, use these extensions by default, only the eight classic ANSI foreground colors.
For the default values currently in use, refer to the reference. You may also want to have a look at the template styles.cfg, where frames are employed.