Skip to content

Latest commit

 

History

History
187 lines (146 loc) · 7.81 KB

README.md

File metadata and controls

187 lines (146 loc) · 7.81 KB

AEC++ License: MIT

Yet another small C++11 library for colors and effects in terminal ouput by means of ansi escape codes

Quick example

#include <iostream>
#include "aecpp.h"

int main() {
	std::cout << "Normal text\n"
	          << aec::red << "Red text!\n" << aec::reset
	          << aec::bold + aec::blue << "Bold blue text!!\n" << aec::reset;

	auto style = aec::green + aec::italic;

	std::cout << style << "Green italic text!!!\n" << aec::reset;

	return 0;
}

Installation

AEC++ is a single-file header-only library, consisting only of the file aecpp.h in the include directory. As long as you adhere to the license, this file is all you need. Simply copy it to a place where your compiler can find it, or use a compiler flag to add the include directory to your compiler's include directory list.

How to use

Basic usage

AEC++ has a simple interface, based on C++ stream objects such as cout. To enable a color or an effect, output the appropriate value (e.g. aec::red) to the stream, as shown in the example above. To turn it off again, output aec::reset. The values can be divided into four categories: text colors, background colors, text effects and resetting values. The complete list of outputtable values is shown below:

Text colors

Value Effect
aec::black Black text
aec::red Red text
aec::green Green text
aec::yellow Yellow text
aec::blue Blue text
aec::magenta Magenta text
aec::cyan Cyan text
aec::gray Gray text
aec::brightblack Bright black text
aec::brightred Bright red text
aec::brightgreen Bright green text
aec::brightyellow Bright yellow text
aec::brightblue Bright blue text
aec::brightmagenta Bright magenta text
aec::brightcyan Bright cyan text
aec::brightgray Bright gray text

Background colors

Value Effect
aec::bgblack Black background
aec::bgred Red background
aec::bggreen Green background
aec::bgyellow Yellow background
aec::bgblue Blue background
aec::bgmagenta Magenta background
aec::bgcyan Cyan background
aec::bggray Gray background
aec::bgbrightblack Bright black background
aec::bgbrightred Bright red background
aec::bgbrightgreen Bright green background
aec::bgbrightyellow Bright yellow background
aec::bgbrightblue Bright blue background
aec::bgbrightmagenta Bright magenta background
aec::bgbrightcyan Bright cyan background
aec::bgbrightgray Bright gray background

Text effects

Value Effect
aec::bold Bold text
aec::dim Dim text
aec::italic Italic text
aec::underline Underlined text
aec::blink Blinking text
aec::rapidblink Rapidly blinking text
aec::reversevideo Inverted colors
aec::conceal Invisible text
aec::crossout Strikethrough text

Resetting values

Value Effect
aec::creset Reset text color
aec::bgcreset Reset background color
aec::reset Reset all styling

Note that text effects cannot be reset separately.

Under the hood, outputting these values to a stream object causes special ansi escape codes to be printed. If these codes are printed to a terminal that supports them (i.e. any modern terminal), then they are invisible and trigger the described effects. However, if the codes are printed to a file or a terminal that doesn't support them, the raw codes will be visible. To address this problem, AEC++ by default only actually outputs the codes if the output stream is connected to a terminal that supports them. This means that you don't need to worry about the environment in which your program is used or whether users will redirect your program's output to a file.

Note:
When using background colors, it is important to use aec::reset before writing a newline. Otherwise, the next line may be affected.

Style objects

In addition to the ansi escape code values, AEC++ provides the aec::Style class. This class represents a combination of escape code values that together form a style. Using Style objects, such styles can be stored and changed via variables. Styles can be constructed by adding code values with the +-operator (as is done in the quick example at the top). They can also be constructed explicitly. This is shown in the additional examples. Style objects can also be modified using its public methods setColor, unsetColor, setBGColor, unsetBGColor, setEffect, unsetEffect and setReset.

A minor technical detail: when outputting styles, its three types of escape codes (text color, background color and text effects) are combined into a single code. This saves a few characters.

Output modes

As stated, the escape codes are by default only actually printed if the output stream is connected to a terminal that supports them. You may however not always want this behavior. AEC++ provides four different output modes. The active output mode can be changed at runtime using aec::setMode. This function takes an aec::Mode enum value. The available modes are:

  • aec::Mode::Always
    Always print escape codes.

  • aec::Mode::Auto (default)
    Print escape codes if and only if the output stream is connected to a terminal that supports them.

  • aec::Mode::Semi
    Print escape codes if and only if the program is running in an environment that supports them, but do not check if the output stream is connected to a terminal. This may be useful if an AEC++ program is used in a pipeline.

  • aec::Mode::Never
    Never print escape codes.

Terminal support of ansi escape codes is currently determined solely based on the environment variable $TERM. View aecpp.h for the values of $TERM that AEC++ considers ansi-escape-code-supporting.

To improve performance, AEC++ does not check whether the output stream is connected to a terminal for every printed escape code. Instead, it checks this only once, at the start of the program. This is not a problem in the vast majority of use cases. However, if you do somehow change the targets of the standard output streams at runtime, you can call aec::checkIfOutputStreamsAreTerminals to make AEC++ re-check them. The length of that function name should serve as an indication of how unlikely it is that you need it :).

Additional examples

Additional example code can be found in examples/examples.cpp. These examples can also be compiled and executed by using make run in the examples directory.

Attributions

AEC++ was inspired by rang: https://github.com/agauniyal/rang