Search tool for EPUB e-books
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
tastytea e154b62201
Add “Similar projects” to readme.
3 weeks ago
..
cmake Merge commit '6c33fb4dcebd5464d89ca3fb98bdf23847d81fbf' as 'dist/termcolor' 2 months ago
docs Merge commit '6c33fb4dcebd5464d89ca3fb98bdf23847d81fbf' as 'dist/termcolor' 2 months ago
examples Merge commit '6c33fb4dcebd5464d89ca3fb98bdf23847d81fbf' as 'dist/termcolor' 2 months ago
include/termcolor Merge commit '6c33fb4dcebd5464d89ca3fb98bdf23847d81fbf' as 'dist/termcolor' 2 months ago
test Merge commit '6c33fb4dcebd5464d89ca3fb98bdf23847d81fbf' as 'dist/termcolor' 2 months ago
.gitignore Merge commit '6c33fb4dcebd5464d89ca3fb98bdf23847d81fbf' as 'dist/termcolor' 2 months ago
.mailmap Merge commit '6c33fb4dcebd5464d89ca3fb98bdf23847d81fbf' as 'dist/termcolor' 2 months ago
.travis.yml Merge commit '6c33fb4dcebd5464d89ca3fb98bdf23847d81fbf' as 'dist/termcolor' 2 months ago
CMakeLists.txt Merge commit '6c33fb4dcebd5464d89ca3fb98bdf23847d81fbf' as 'dist/termcolor' 2 months ago
LICENSE Merge commit '6c33fb4dcebd5464d89ca3fb98bdf23847d81fbf' as 'dist/termcolor' 2 months ago
README.rst Merge commit '6c33fb4dcebd5464d89ca3fb98bdf23847d81fbf' as 'dist/termcolor' 2 months ago

README.rst

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