Skip to content

Commit

Permalink
Update README.rst
Browse files Browse the repository at this point in the history
  • Loading branch information
@ikalnytskyi
ikalnytskyi committed Feb 28, 2021
1 parent c1180d5 commit 67eb0aa
Showing 1 changed file with 88 additions and 40 deletions.
128 changes: 88 additions & 40 deletions README.rst
View file
Expand Up @@ -10,48 +10,62 @@ Termcolor
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). On Windows, WinAPI
is used instead but some limitations are applied.
terminals (most \*nix systems, including Linux and Mac OS).

It's licensed under the BSD (3-clause) License. That basically means:
do whatever you want as long as copyright sticks around.
.. note::

.. _Termcolor: https://github.com/ikalnitsky/termcolor
.. _the Force: http://starwars.wikia.com/wiki/The_Force
.. _ANSI color formatting: http://en.wikipedia.org/wiki/ANSI_escape_code#Colors
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`` to the project and use provided stream manipulators
from the ``termcolor`` namespace.
* 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
Packaging Status
................
.. _vcpkg: https://github.com/microsoft/vcpkg

.. image:: https://repology.org/badge/vertical-allrepos/termcolor.svg
:target: https://repology.org/project/termcolor/versions
:alt: Packaging Status
* Or if you are on macOS, you can use Homebrew_ for that purpose:

Vcpkg Integration
.................
.. code:: sh
Alternatively, if you are using the vcpkg_ dependency manager you can
download and install termcolor with CMake integration in a single command:
$ brew install termcolor
.. _vcpkg: https://github.com/microsoft/vcpkg
.. _Homebrew: https://brew.sh/

.. code:: sh
* For up-to-date information about existing packages, refer to the the following
picture:

vcpkg install termcolor
.. 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 based on the use of C++ stream
manipulators. The typical «Hello World» application is below:
It's very easy to use. The idea is built upon C++ stream manipulators.
Typical «Hello World» application looks like this:

.. code:: c++

Expand All @@ -60,42 +74,39 @@ manipulators. The typical «Hello World» application is below:

int main(int /*argc*/, char** /*argv*/)
{
std::cout << termcolor::red << "Hello, ";
std::cout << termcolor::color<100> << "Colorful ";
std::cout << termcolor::color<211, 54, 130> << "World!";
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 with red. It's obvious, isn't it?
There is a one problem that is not obvious for the unexperienced users.
If you write something this way:
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 << "Here I'm!" << std::endl;
std::cout << "I'm RED too!" << std::endl;

the phrase «Here I'm» will be printed with red too. Why? Because you don't
reset termcolor's setting. So if you want to print text wit default terminal
setting you have to reset termcolor's settings. It can be done by using
``termcolor::reset`` manipulator:
Correct version of the code above should look like this:

.. code:: c++

std::cout << termcolor::red << "Hello, Colorful World!" << std::endl;
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:
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();

would print «unicorn» using default color, not red. In order to change this
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.

Expand All @@ -110,10 +121,26 @@ The manipulators are divided into four groups:
* *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``
Expand All @@ -130,13 +157,24 @@ Foreground manipulators
#. ``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``
Expand All @@ -153,14 +191,23 @@ Background manipulators
#. ``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
......................

(so far they aren't supported on Windows)
(Windows API does not support these manipulators except for ``underline``)

#. ``termcolor::bold``
#. ``termcolor::dark``
Expand All @@ -174,7 +221,7 @@ Attribute manipulators
Control manipulators
....................

(so far they aren't supported on Windows)
(Windows API does not support these manipulators)

#. ``termcolor::colorize``
#. ``termcolor::nocolorize``
Expand All @@ -186,3 +233,4 @@ 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>``.

0 comments on commit 67eb0aa

Please sign in to comment.