term.h

Go to the documentation of this file.

#pragma once
 
#include <cstdlib>
#include <cstring>
 
#include <atomic>
#include <iostream>
#include <optional>
#include <ostream>
#include <string_view>
 
#ifdef _WIN32
#    ifndef WIN32_LEAN_AND_MEAN
#        define WIN32_LEAN_AND_MEAN
#    endif
#    ifndef NOMINMAX
#        define NOMINMAX
#    endif
#    include <windows.h>
#else
#    include <sys/ioctl.h>
#    include <unistd.h>
#endif
 
#include "fe/assert.h"
#include "fe/format.h"
#include "fe/restore.h"
 
/// Lightweight stream-based terminal colors for diagnostics and CLI output.
///
/// Include `fe/term.h` and stream a @ref fe::term::FG value into an `std::ostream`:
/// ```
/// std::cerr << fe::term::FG::Red << "error: " << fe::term::FG::Reset << "unexpected token\n";
/// ```
///
/// The current behavior is controlled via @ref fe::term::Mode and can be overridden with
/// @ref fe::term::set_mode. In @ref fe::term::Mode::Auto, colors are emitted only for
/// `std::cout`, `std::cerr`, `std::clog`, or streams sharing those buffers when they refer to
/// terminals. FE also respects the common environment conventions `NO_COLOR`, `CLICOLOR=0`, and
/// `CLICOLOR_FORCE` (unless it is set to `0`).
///
/// Note that a `std::formatter` never sees the destination stream - it formats into a detached buffer.
/// Hence, embedding a @ref fe::term::FG value in a `std::format`/`std::print` format string resolves
/// @ref fe::term::Mode::Auto to "no color".
/// If you emit colors this way, call @ref fe::term::resolve_mode once at startup to decide
/// @ref fe::term::Mode::Auto up front based on a representative stream.
///
/// Use @ref fe::term::use_color to branch on whether color will actually be emitted, e.g. to keep a
/// plain-text fallback in sync with the colored rendering.
namespace fe::term {
 
/// Controls whether color escape sequences are emitted.
enum class Mode {
    Auto,
    Never,
    Always,
};
 
/// Foreground colors that can be streamed into an `std::ostream`.
enum class FG {
    Black,
    Red,
    Green,
    Yellow,
    Blue,
    Magenta,
    Cyan,
    Gray,
    Grey = Gray,
    Reset,
};
 
namespace detail {
 
enum class Stream {
    Unknown,
    Stdout,
    Stderr,
};
 
inline bool env_set(const char* name) noexcept {
    auto* value = std::getenv(name);
    return value && *value != '\0';
}
 
inline bool env_is(const char* name, const char* expected) noexcept {
    auto* value = std::getenv(name);
    return value && std::strcmp(value, expected) == 0;
}
 
inline Mode default_mode() noexcept {
    if (env_set("NO_COLOR")) return Mode::Never;
    if (env_set("CLICOLOR_FORCE") && !env_is("CLICOLOR_FORCE", "0")) return Mode::Always;
    if (env_is("CLICOLOR", "0")) return Mode::Never;
    return Mode::Auto;
}
 
inline std::atomic<Mode>& current_mode() noexcept {
    static std::atomic<Mode> mode(default_mode());
    return mode;
}
 
inline std::streambuf* stdout_rdbuf() noexcept {
    static std::streambuf* buf = std::cout.rdbuf();
    return buf;
}
 
inline std::streambuf* stderr_rdbuf() noexcept {
    static std::streambuf* buf = std::cerr.rdbuf();
    return buf;
}
 
inline std::streambuf* clog_rdbuf() noexcept {
    static std::streambuf* buf = std::clog.rdbuf();
    return buf;
}
 
inline Stream stream(std::ostream& os) noexcept {
    auto* const buf = os.rdbuf();
    if (buf == stdout_rdbuf()) return Stream::Stdout;
    if (buf == stderr_rdbuf() || buf == clog_rdbuf()) return Stream::Stderr;
    return Stream::Unknown;
}
 
#ifdef _WIN32
inline bool enable_vt(HANDLE handle) noexcept {
    if (handle == INVALID_HANDLE_VALUE) return false;
 
    DWORD mode = 0;
    if (!GetConsoleMode(handle, &mode)) return false;
    if (mode & ENABLE_VIRTUAL_TERMINAL_PROCESSING) return true;
    return SetConsoleMode(handle, mode | ENABLE_VIRTUAL_TERMINAL_PROCESSING) != 0;
}
 
inline bool is_terminal(Stream s) noexcept {
    switch (s) {
        case Stream::Stdout: {
            static bool stdout_is_terminal = enable_vt(GetStdHandle(STD_OUTPUT_HANDLE));
            return stdout_is_terminal;
        }
        case Stream::Stderr: {
            static bool stderr_is_terminal = enable_vt(GetStdHandle(STD_ERROR_HANDLE));
            return stderr_is_terminal;
        }
        default: return false;
    }
}
#else
inline bool is_terminal(Stream s) noexcept {
    switch (s) {
        case Stream::Stdout: {
            static bool stdout_is_terminal = ::isatty(STDOUT_FILENO) != 0;
            return stdout_is_terminal;
        }
        case Stream::Stderr: {
            static bool stderr_is_terminal = ::isatty(STDERR_FILENO) != 0;
            return stderr_is_terminal;
        }
        default: return false;
    }
}
#endif
 
constexpr std::string_view sgr(FG color) noexcept {
    // clang-format off
    switch (color) {
        case FG::Black:   return "\033[30m";
        case FG::Red:     return "\033[31m";
        case FG::Green:   return "\033[32m";
        case FG::Yellow:  return "\033[33m";
        case FG::Blue:    return "\033[34m";
        case FG::Magenta: return "\033[35m";
        case FG::Cyan:    return "\033[36m";
        case FG::Gray:    return "\033[90m";
        case FG::Reset:   return "\033[39m";
        default: fe::unreachable();
    }
    // clang-format on
}
 
} // namespace detail
 
/// Returns the current terminal color mode.
inline Mode mode() noexcept { return detail::current_mode().load(std::memory_order_relaxed); }
 
/// Whether color escape sequences are emitted for @p os right now.
/// In Mode::Auto this is decided by whether @p os refers to a terminal, so a detached buffer
/// (anything a `std::formatter` writes into) yields `false`; see @ref resolve_mode.
/// Use this to keep a plain-text fallback in sync with what @ref operator<<(std::ostream&, FG) will emit,
/// e.g. to spell out a marker only when it cannot be conveyed by color.
inline bool use_color(std::ostream& os) noexcept {
    // clang-format off
    switch (mode()) {
        case Mode::Always: return true;
        case Mode::Never:  return false;
        case Mode::Auto:   return detail::is_terminal(detail::stream(os));
        default: fe::unreachable();
    }
    // clang-format on
}
 
/// Number of columns of the terminal @p os refers to.
/// Unlike @ref use_color, this ignores @ref Mode and always asks the actual stream.
/// @returns `std::nullopt` if @p os is not a terminal or its size cannot be determined.
inline std::optional<size_t> width(std::ostream& os) noexcept {
    auto s = detail::stream(os);
    if (!detail::is_terminal(s)) return {};
 
#ifdef _WIN32
    auto handle = GetStdHandle(s == detail::Stream::Stdout ? STD_OUTPUT_HANDLE : STD_ERROR_HANDLE);
    if (CONSOLE_SCREEN_BUFFER_INFO info; GetConsoleScreenBufferInfo(handle, &info)) {
        if (auto cols = info.srWindow.Right - info.srWindow.Left + 1; cols > 0) return size_t(cols);
    }
#else
    auto fd = s == detail::Stream::Stdout ? STDOUT_FILENO : STDERR_FILENO;
    if (winsize ws; ::ioctl(fd, TIOCGWINSZ, &ws) == 0 && ws.ws_col > 0) return size_t(ws.ws_col);
#endif
    return {};
}
 
/// Overrides the current terminal color mode.
inline void set_mode(Mode m) noexcept { detail::current_mode().store(m, std::memory_order_relaxed); }
 
/// Overrides the color mode for the duration of the scope.
/// @warning The mode is global, so this affects every stream - and every thread - while it is alive.
using ScopedMode = Restore<Mode, &mode, &set_mode>;
 
/// Resolves Mode::Auto to Mode::Always or Mode::Never, depending on whether @p os refers to a terminal.
/// A `std::formatter` cannot see its destination stream, so FG values embedded in a
/// `std::format`/`std::print` format string never detect a terminal in Mode::Auto.
/// Call this once at startup to make formatted output colored as well; explicit modes are left untouched:
/// ```
/// fe::term::resolve_mode(); // decide based on stderr
/// std::print(std::cerr, "{}error:{} ...", fe::term::FG::Red, fe::term::FG::Reset);
/// ```
inline void resolve_mode(std::ostream& os = std::cerr) noexcept {
    if (mode() == Mode::Auto) set_mode(detail::is_terminal(detail::stream(os)) ? Mode::Always : Mode::Never);
}
 
/// Streams the ANSI escape sequence for @p color when colors are enabled for @p os.
inline std::ostream& operator<<(std::ostream& os, FG color) {
    if (use_color(os)) {
        auto esc = detail::sgr(color);
        os.write(esc.data(), esc.size());
    }
    return os;
}
 
} // namespace fe::term
 
#ifndef DOXYGEN
template<>
struct std::formatter<fe::term::FG> : fe::ostream_formatter {};
#endif