mint is a single C++11 header to format terminal text using a simple tag-based markup syntax.
mint.hpp offers the mint::mint() function which transforms a string
containing terminal attribute tags similar to
BBCode
into another string containing actual terminal
SGR codes.
mint::mint() automatically detects terminal support. If the standard
output (or any other file descriptor you choose, like the standard
error) isn't connected to a compatible terminal, it removes the
attribute tags instead of converting them to SGR codes. It also honors
the NO_COLOR and
FORCE_COLOR environment variables.
Important
You may copy mint.hpp as is to your project.
The only requirements are Linux and C++11.
mint tags allow you to specify text attributes like colors, bold, underline, and italic formatting.
The mint markup syntax is straightforward and composable.
An opening tag is, between [ and ], an unordered sequence of
specifiers (all optional, but at least one):
| Specifier | Description |
|---|---|
! |
Bold |
- |
Dim |
_ |
Underline |
' |
Italic |
^ |
Reverse video |
* |
Bright foreground color |
COLOR |
Foreground color |
:COLOR |
Background color |
COLOR is one of:
-
ANSI 16-color palette:
Code Color dDefault kBlack rRed gGreen yYellow bBlue mMagenta cCyan wWhite -
True color:
#followed with six hex digits (like a CSS color).Note that you can set two foreground or background colors within a single opening tag, for example:
A [r#e74c3c]wonderful [!:m:#9b59b6]day[//]!When
mint::mint()only emits ANSI 16-color palette codes (in auto mode whenmint::terminalSupport()reports only that, or when you passmint::TerminalSupport::BasicColor), it ignores the true color specifiers and only keeps the basic ones.
Spaces are allowed between specifiers within an opening tag.
A closing tag contains one or more / characters between [ and ].
Each / closes one level.
Escape [ with \[ and \ with \\. Use mint::escape() to escape
text for mint::mint(). Use mint::escapeAnsi() to return to a plain
string (no SGR codes) from the result of mint::mint().
Opening and closing tags may be nested (maximum four levels of depth) and must be balanced. Note that nesting is additive: a nested tag cannot cancel an active attribute.
Important
The SGR code of any opening and closing tag always starts with a reset.
Because you must balance opening and closing tags, mint is more suited
to {fmt} and printf() than I/O streams:
Using mint with {fmt}:
fmt::print(mint::mint("[w:r] [!]ERROR[/]: At offset [!*b]{:#x}[/]: {} [/]"),
exc.offset(), exc.what());Note
In this example, mint::mint() formats before fmt::print(),
therefore we don't need to escape exc.what() with mint::escape().
Include the mint.hpp header in your C++ code:
#include "mint.hpp"See the documentation of mint::mint(), mint::escape(),
mint::escapeAnsi(), and mint::terminalSupport() in the header file
itself.
By default, mint::mint() checks whether or not the standard output
is connected to a terminal. If you write the result somewhere else,
pass the corresponding file descriptor:
std::cerr << mint::mint("[!r]ERROR[/]: Cannot open file\n",
mint::When::Auto, STDERR_FILENO);This way, the following command doesn't write SGR codes to
errors.txt, even if the standard output is a terminal:
$ my-program 2>errors.txt
In auto mode, mint::mint() also honors the following environment
variables when they're set and not empty:
| Variable | Effect |
|---|---|
NO_COLOR |
Removes the attribute tags, even with a compatible terminal. |
FORCE_COLOR |
Converts the attribute tags, even without a terminal (for example, to keep colors in CI logs). |
NO_COLOR takes precedence over FORCE_COLOR. mint::terminalSupport()
honors them too.
You may also decide yourself by passing a mint::TerminalSupport
value instead of a mint::When value, for example according to a
command-line option. In that case, as with mint::When::Always and
mint::When::Never, mint::mint() ignores those environment variables.
To test mint:
-
Build the testers:
$ mkdir -p build && cd build && cmake .. && make -
Test with pytest, providing the build directory:
$ MINT_BUILD_DIR=$PWD pytest ../tests
To report a bug, create a GitHub issue.


