Skip to content

About

A lightweight, header-only C++17 console coloring and formatting library.

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

ColormaCpp

A lightweight, header-only C++17 library for colorful and well-formatted console output.

ColormaCpp brings ANSI colors, text styles, and convenient {}-based formatting together in one small library. It has no third-party dependencies and works with standard output streams such as std::cout, std::cerr, and std::ostringstream.

Color your console. Keep your C++ simple.

Features

  • 16 foreground colors and 16 background colors, including bright variants.
  • Bold, italic, underline, reverse, and reset styles.
  • Inline color/style changes inside format strings.
  • {} replacement fields with numeric and string formatting options.
  • Stream-based and std::cout convenience overloads.
  • Automatic, forced, and disabled color modes.
  • Automatic terminal detection, NO_COLOR, and TERM=dumb handling.
  • Windows virtual-terminal processing when writing to a supported console.
  • Header-only, C++17, dependency-free.
  • CMake target with install/export support.

Preview

#include <colorma/colorma.hpp>

#include <iostream>

int main() {
    using colorma::Color;
    using colorma::Style;

    colorma::println(
        std::cout,
        "{}Hello {}World{}!",
        Color::green,
        Style::bold + Color::bright_red,
        Style::reset);

    colorma::println(
        std::cout,
        "{}PI = {:.15f}{}",
        Color::bright_cyan,
        3.141592653589793,
        Style::reset);
}

The first line prints Hello in green, World in bold bright red, and ! in the terminal's default style. The second prints PI to 15 digits after the decimal point.

Requirements

  • C++17-compatible compiler.
  • CMake 3.16 or newer (only needed for the CMake workflow).
  • No external libraries.

Tested in this project with GCC 14, Clang 17, and CMake on Linux. CI is configured for GCC, Clang, AppleClang, and MSVC. Windows behavior should be validated in your target terminal/console environment.

Get started

Option 1: Copy the header

Copy the include/ directory into your project and include:

#include <colorma/colorma.hpp>

A compatibility header is also provided:

#include <Colorma.hpp>

Option 2: Build with CMake

# From the root of the downloaded or cloned repository:
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
ctest --test-dir build --output-on-failure

Run one of the example programs, for example:

./build/examples/colorma_example_02_inline_formatting

On Windows, the executable is typically under build\examples\Release\ when using a multi-configuration generator.

CMake integration

After installation, another CMake project can use the exported target:

find_package(ColormaCpp CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE ColormaCpp::ColormaCpp)

Install the library from a build directory with:

cmake --install build --prefix /your/install/prefix

API at a glance

Simple colored output

using colorma::Color;
using colorma::Style;

colorma::print(std::cout, "Working... ", Color::yellow);
colorma::println(std::cout, "done", Color::bright_green, std::nullopt, {Style::bold});

// std::cout convenience overloads:
colorma::println("Success", Color::green);
colorma::print("Still on this line... ", Color::cyan);
colorma::println("next line", Color::white);

The original colorize, stream-based print/println, and their original parameter order are retained.

Inline styles and colors

Each format field consumes exactly one argument. A Color, Style, TextStyle, or BackgroundColor argument changes the style state rather than inserting visible text.

colorma::println(
    std::cout,
    "{}SUCCESS:{} The operation completed in {} ms.",
    Color::bright_green,
    Style::reset,
    125);

colorma::println(
    std::cout,
    "{}Warning{}: disk space is low.",
    Style::bold + Color::black + colorma::on(Color::bright_yellow),
    Style::reset);

Styling is reset at segment boundaries, so ANSI formatting does not accidentally leak into later console output.

Backgrounds and style combinations

colorma::println(
    std::cout,
    "{} BUILD OK {}",
    Color::black + colorma::on(Color::bright_green) + Style::bold,
    Style::reset);

Use colorma::on(Color::blue) to create a background-color token.

Color modes

colorma::println(std::cout, colorma::ColorMode::automatic,
                 "{}Auto{}", Color::green, Style::reset);
colorma::println(std::cout, colorma::ColorMode::always,
                 "{}Forced ANSI{}", Color::yellow, Style::reset);
colorma::println(std::cout, colorma::ColorMode::never,
                 "Plain output");
  • automatic emits ANSI only when the destination is recognized as an interactive terminal and color is not disabled by the environment.
  • always forces ANSI sequences. Use this when you explicitly want ANSI output, including when writing to a file or captured stream.
  • never emits plain text.

NO_COLOR (when set to a non-empty value) and TERM=dumb disable automatic color output. These environment checks do not override explicit always mode.

Format string reference

ColormaCpp supports automatic sequential fields ({}), escaped braces ({{ and }}), and a deliberately small formatting grammar. Positional fields and named fields are not supported.

Format Meaning
{} Default formatting
{:d} Decimal integer
{:x} / {:X} Lowercase / uppercase hexadecimal
{:o} Octal integer
{:c} Integer code converted to a single-byte character
{:.3f} Fixed-point with 3 digits after the decimal point
{:e} / {:E} Scientific notation
{:g} / {:G} General floating-point notation
{:a} / {:A} Hexadecimal floating-point notation
{:05d} Integer width 5, zero-filled
{:+d} Show a plus sign for non-negative numbers
{:#x} Alternate hexadecimal form (0x prefix)
{:>10} Right-aligned, width 10
{:<10} Left-aligned, width 10
{:^10} Center-aligned, width 10
{:*>10} Right-aligned, * fill character
{:.5s} String precision: keep at most 5 bytes
{{text}} Literal {text}

Format flags are type-checked. Unsupported specifications, unmatched braces, missing arguments, and unused arguments throw colorma::format_error before the formatted result is written to the destination stream.

See docs/FORMAT_SPECIFIERS.md for details and examples/ for complete programs.

Examples

Example Demonstrates
01_quick_start.cpp Basic foreground colors and convenience overloads
02_inline_formatting.cpp Inline tokens, styles, and numeric formatting
03_status_dashboard.cpp Colored status output
04_colors_and_styles.cpp The 16-color palette, text styles, and backgrounds
05_pi_and_numbers.cpp PI, precision, and ordinary iostream formatting
06_color_modes.cpp Automatic, forced, and disabled color modes

Project layout

ColormaCpp/
├── .github/                 # CI, issue templates, pull request template
├── cmake/                   # CMake package configuration
├── docs/                    # API and format reference
├── examples/                # Standalone example programs
├── include/
│   ├── colorma/colorma.hpp  # Main public header
│   └── Colorma.hpp          # Backward-compatible include
├── tests/                   # Automated tests
├── CMakeLists.txt
├── LICENSE
├── CHANGELOG.md
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── SECURITY.md
└── README.md

Contributing

Bug reports, focused improvements, and documentation updates are welcome. Please read CONTRIBUTING.md before opening a pull request.

License

ColormaCpp is licensed under the MIT License. See LICENSE.

About

A lightweight, header-only C++17 console coloring and formatting library.

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages