Termcolor
=========
.. image:: docs/_static/example.png
:alt: termcolor in action
:align: left
.. -*- inclusion-marker-for-sphinx-docs -*-
Termcolor_ is a header-only C++ library for printing colored messages to the
terminal. Written just for fun with a help of `the Force`_. Termcolor uses
`ANSI color formatting`_, so you can use it on every system that is used such
terminals (most \*nix systems, including Linux and Mac OS).
.. note::
On Windows, `Windows API`_ is used instead of escape codes but some
limitations are applied (not everything is supported). That's why it's
recommended to enter `virtual terminal processing`_ mode and set
``TERMCOLOR_USE_ANSI_ESCAPE_SEQUENCES`` macro to trick termcolor to use
ANSI color codes.
.. _virtual terminal processing: https://docs.microsoft.com/en-us/windows/console/console-virtual-terminal-sequences
It's licensed under the BSD (3-clause) License. That basically means: do
whatever you want as long as copyright sticks around.
.. _Termcolor: https://github.com/ikalnytskyi/termcolor
.. _the Force: https://starwars.wikia.com/wiki/The_Force
.. _ANSI color formatting: https://en.wikipedia.org/wiki/ANSI_escape_code#Colors
.. _Windows API: https://docs.microsoft.com/en-us/windows/console/setconsoletextattribute
Installation
------------
* Add ``termcolor.hpp`` (grab it from ``include/termcolor/termcolor.hpp``) to
the project and use stream manipulators from the ``termcolor`` namespace.
* You can also use vcpkg_ to install the library:
.. code:: sh
$ vcpkg install termcolor
.. _vcpkg: https://github.com/microsoft/vcpkg
* Or if you are on macOS, you can use Homebrew_ for that purpose:
.. code:: sh
$ brew install termcolor
.. _Homebrew: https://brew.sh/
* For up-to-date information about existing packages, refer to the the following
picture:
.. image:: https://repology.org/badge/vertical-allrepos/termcolor.svg
:target: https://repology.org/project/termcolor/versions
:alt: Packaging Status
How to use?
-----------
It's very easy to use. The idea is built upon C++ stream manipulators.
Typical «Hello World» application looks like this:
.. code:: c++
#include <iostream>
#include <termcolor/termcolor.hpp>
int main(int /*argc*/, char** /*argv*/)
{
std::cout << termcolor::red << "Hello, "; // 16 colors
std::cout << termcolor::color<100> << "Colorful "; // 256 colors
std::cout << termcolor::color<211, 54, 130> << "World!"; // true colors
std::cout << std::endl;
return 0;
}
The application above prints a string using different colors. There is one
caveat though. You must not forget to reset colors, otherwise they will be
applied to other prints as well.
.. code:: c++
std::cout << termcolor::red << "Hello, Colorful World!" << std::endl;
std::cout << "I'm RED too!" << std::endl;
Correct version of the code above should look like this:
.. code:: c++
std::cout << termcolor::red << "Hello, Colorful World!" << termcolor::reset << std::endl;
std::cout << termcolor::reset << "Here I'm!" << std::endl;
By default, Termcolor ignores any colors for non-tty streams (e.g.
``std::stringstream``), so the following snippet
.. code:: c++
std::stringstream ss;
ss << termcolor::red << "unicorn";
std::cout << ss.str();
will print «unicorn» using default color, not red. In order to change this
behaviour one can use ``termcolor::colorize`` manipulator that enforce colors
no matter what.
What manipulators are supported?
--------------------------------
The manipulators are divided into four groups:
* *foreground*, which changes text color;
* *background*, which changes text background color;
* *attributes*, which changes some text style (bold, underline, etc);
* *control*, which changes termcolor's behaviour.
Also, there are color manipulators for `16 colors`_, `256 colors`_ and
`true colors`_ palettes.
.. note::
While ``termcolor`` supports true color, it's required for the terminal
emulator you use to run your software to support true color too. So please
ensure it's supported before filing an issue.
.. _16 colors: https://en.wikipedia.org/wiki/Color_depth#4-bit_color
.. _256 colors: https://en.wikipedia.org/wiki/Color_depth#8-bit_color
.. _true colors: https://en.wikipedia.org/wiki/Color_depth#True_color_(24-bit)
Foreground manipulators
.......................
16 colors
`````````
#. ``termcolor::grey``
#. ``termcolor::red``
#. ``termcolor::green``
#. ``termcolor::yellow``
#. ``termcolor::blue``
#. ``termcolor::magenta``
#. ``termcolor::cyan``
#. ``termcolor::white``
#. ``termcolor::bright_grey``
#. ``termcolor::bright_red``
#. ``termcolor::bright_green``
#. ``termcolor::bright_yellow``
#. ``termcolor::bright_blue``
#. ``termcolor::bright_magenta``
#. ``termcolor::bright_cyan``
#. ``termcolor::bright_white``
256 colors
``````````
#. ``termcolor::color<256_COLOR_CODE>``
true colors
```````````
#. ``termcolor::color<RED, GREEN, BLUE>``
Background manipulators
.......................
16 colors
`````````
#. ``termcolor::on_grey``
#. ``termcolor::on_red``
#. ``termcolor::on_green``
#. ``termcolor::on_yellow``
#. ``termcolor::on_blue``
#. ``termcolor::on_magenta``
#. ``termcolor::on_cyan``
#. ``termcolor::on_white``
#. ``termcolor::on_bright_grey``
#. ``termcolor::on_bright_red``
#. ``termcolor::on_bright_green``
#. ``termcolor::on_bright_yellow``
#. ``termcolor::on_bright_blue``
#. ``termcolor::on_bright_magenta``
#. ``termcolor::on_bright_cyan``
#. ``termcolor::on_bright_white``
256 colors
``````````
#. ``termcolor::on_color<256_COLOR_CODE>``
true colors
```````````
#. ``termcolor::on_color<RED, GREEN, BLUE>``
Attribute manipulators
......................
(Windows API does not support these manipulators except for ``underline``)
#. ``termcolor::bold``
#. ``termcolor::dark``
#. ``termcolor::italic``
#. ``termcolor::underline``
#. ``termcolor::blink``
#. ``termcolor::reverse``
#. ``termcolor::concealed``
#. ``termcolor::crossed``
Control manipulators
....................
(Windows API does not support these manipulators)
#. ``termcolor::colorize``
#. ``termcolor::nocolorize``
Caveats
-------
#. On Windows, due to internal usage of ``<windows.h>``, global namespace could
be polluted with `min`/`max` macros. If such effect is desireable, please
consider using ``#define NOMINMAX`` before ``#include <termcolor.hpp>``.
