Skip to content
efficiosPublic

About

Single C++11 header for markup-based colorful terminal output

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

51 Commits

Folders and files

Repository files navigation

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 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.

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 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
    d Default
    k Black
    r Red
    g Green
    y Yellow
    b Blue
    m Magenta
    c Cyan
    w White
  • 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 when mint::terminalSupport() reports only that, or when you pass mint::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().

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::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.

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.

About

Single C++11 header for markup-based colorful terminal output

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages