From 67eb0aa55e48ead9fe2aab049f0b1aa7943ba0ea Mon Sep 17 00:00:00 2001 From: Ihor Kalnytskyi Date: Sun, 28 Feb 2021 19:19:24 +0200 Subject: [PATCH] Update README.rst --- README.rst | 128 ++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 88 insertions(+), 40 deletions(-) diff --git a/README.rst b/README.rst index d0eb88f..2c62175 100644 --- a/README.rst +++ b/README.rst @@ -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++ @@ -60,34 +74,31 @@ 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++ @@ -95,7 +106,7 @@ By default, Termcolor ignores any colors for non-tty streams 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. @@ -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`` @@ -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`` Background manipulators ....................... +16 colors +````````` + #. ``termcolor::on_grey`` #. ``termcolor::on_red`` #. ``termcolor::on_green`` @@ -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`` Attribute manipulators ...................... -(so far they aren't supported on Windows) +(Windows API does not support these manipulators except for ``underline``) #. ``termcolor::bold`` #. ``termcolor::dark`` @@ -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`` @@ -186,3 +233,4 @@ Caveats #. On Windows, due to internal usage of ````, global namespace could be polluted with `min`/`max` macros. If such effect is desireable, please consider using ``#define NOMINMAX`` before ``#include ``. +