mint

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 into another string containing actual terminal SGR codes.

mint::mint() automatically detects terminal support. If the standard output isn’t connected to a compatible terminal, it removes the attribute tags instead of converting them to SGR codes.

Important

You may copy mint.hpp as is to your project. The only requirements are Linux and C++11.

Table of Contents

• Markup syntax
• API usage
• Testing
• Contributing

Markup syntax

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 (all optional, but at least one):

!

Bold.

-

Dim.

_

Underline.

#

Italic.

*

Bright foreground color.

:COLOR (background)

COLOR (foreground)

COLOR is one of:

d	Default
k	Black
r	Red
g	Green
y	Yellow
b	Blue
m	Magenta
c	Cyan
w	White

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:

Example 1. 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().

API usage

Include the mint.hpp header in your C++ code:

#include "mint.hpp"

See the documentation of mint::mint(), mint::escape(), mint::escapeAnsi(), and mint::hasTerminalSupport() in the header file itself.

Testing

To test mint:

1. Build the testers:

   $ mkdir -p build && cd build && cmake .. && make

2. Test with pytest, providing the build directory:

   $ MINT_BUILD_DIR=$PWD pytest ../tests

Contributing

To report a bug, create a GitHub issue.