Files
carbon-lang/common/terminal/capabilities.h
T
Chandler Carruth 40aa4419c0 Update the terminal library for rendering diagnostics (#7659)
Everything drawn into a buffer was checked against `columns()`. That is
right for wrapping and for line drawing, both of which have somewhere
else to put what doesn't fit, but wrong for `DrawText`, which exists for
text that must not be broken and sometimes has to run past the width
with no other answer available. It and `DrawCodePoint` now check only
that the column is non-negative and the row is one a grid can index, and
widen the buffer as far as the text needs; `DrawWrappedText`,
`DrawHorizontalLine`, `DrawVerticalLine`, and `DrawBox` are unchanged.
That also settles what a caller does after a drawing overhangs, since
`DrawEnd` exists so that a run can continue where the last one ended,
and that continuation was itself a checked error whenever the previous
run overhung. A column computed to be negative, such as a gutter
narrower than the line number it holds, still fails.

A color picked to read against black is hard to read against white, and
nothing in `Capabilities` said which a stream was going into.
`ChooseBackground` reads `COLORFGBG`, which `rxvt` and its derivatives
set to the foreground and background palette indices, and takes anything
it doesn't answer to be dark: guessing dark costs contrast, while
guessing light puts pale text on a pale background. Asking the terminal
itself with an `OSC 11` query is the accurate answer, and needs raw
mode, a timeout, and somewhere to put the reply, so there is a TODO for
it rather than an implementation.

Every corner, tee, and crossing came out of `Charset::Ascii` as `+`,
which left six of the shapes a diagnostic draws indistinguishable: the
rule closing a frame read as the one separating two snippets, and the
anchor opening a diagnostic as the one carrying it on. Each stand-in now
keeps the axis its line runs through, which leaves `+` meaning a
crossing and nothing else. A tee keeps its through-stroke and leaves the
branch to what is drawn beside it, and a corner is `.` where its line
leaves downward and `'` where it arrives from above, which is where
those characters sit in their cells. A box is a box again:

```
    +--+        .--.
    |  |   ->   |  |
    +--+        '--'
```

Assisted-by: Claude Code
2026-08-21 22:19:12 +00:00

254 lines
11 KiB
C++

// Part of the Carbon Language project, under the Apache License v2.0 with LLVM
// Exceptions. See /LICENSE for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
#ifndef CARBON_COMMON_TERMINAL_CAPABILITIES_H_
#define CARBON_COMMON_TERMINAL_CAPABILITIES_H_
#include <cstdint>
#include <optional>
#include "common/filesystem.h"
#include "common/terminal/color.h"
#include "llvm/ADT/StringRef.h"
namespace Carbon::Terminal {
// The encoding the terminal decodes output with.
//
// This decides far more than which characters can be drawn: rendering has to
// count the columns a run of bytes will occupy, and that count only follows
// from the code points those bytes encode if the terminal agrees about the
// encoding. Disagreeing misaligns the entire line rather than drawing a single
// character wrong.
//
// No other encoding is modeled. A terminal decoding something else, an ISO 8859
// part for example, is treated as `Ascii`. That is correct output for any of
// them, as they all encode printable ASCII as itself, and rendering in one
// natively would mean carrying its conversion and column-width tables to gain
// nothing but nicer line drawing, which `Ascii` already has a fallback for. So
// `Utf8` is used only where the environment says outright that the terminal
// decodes UTF-8, and `Ascii` does no UTF-8 processing at all.
enum class Charset : int8_t {
// Every byte is one column, and lines are drawn from `-`, `|`, and `+`.
//
// Bytes outside printable ASCII are replaced rather than passed through,
// because a terminal decoding some single-byte encoding will render them as
// something, and there is no way to know what.
Ascii,
// Bytes are decoded as UTF-8, giving double-width characters two columns and
// combining marks none, and lines are drawn with box-drawing characters.
Utf8,
};
// Whether to use one of the terminal features detection decides about, where
// an explicit request overrides what detection would conclude.
//
// This is the tri-state that a `--color=never` style flag parses into. It says
// nothing about which feature is being requested; `Preferences` holds one of
// these per feature.
enum class Preference : int8_t {
// Decide from the environment and the stream.
Auto,
// Never use the feature, whatever the environment says.
Never,
// Use the feature even when the stream isn't a terminal. This is what a
// caller wants when piping into a pager, capturing output for later replay,
// or writing a test.
Always,
};
// What the terminal draws its text on.
//
// Nothing about the rendering depends on the exact color, only on which side of
// the middle it sits: a color chosen to read on one is hard to read on the
// other.
enum class Background : int8_t {
Dark,
Light,
};
// An explicit statement of what the terminal draws its text on, where `Auto`
// leaves it to detection.
//
// This is a tri-state like `Preference`, but its two settings name the answer
// rather than turning a feature on and off, so it is an enum of its own.
enum class BackgroundPreference : int8_t {
Auto,
Dark,
Light,
};
// An explicit preference for each feature detection decides about, normally
// parsed from command line flags.
struct Preferences {
Preference color = Preference::Auto;
Preference utf8 = Preference::Auto;
BackgroundPreference background = BackgroundPreference::Auto;
};
// The environment variables that control whether and how color is used.
//
// An unset variable and one set to the empty string mean the same thing
// throughout: no opinion. Values point into the process environment and are
// invalidated by anything that modifies it.
struct ColorEnvironment {
// Reads the variables from the process environment.
static auto FromProcess() -> ColorEnvironment;
llvm::StringRef no_color;
llvm::StringRef clicolor_force;
llvm::StringRef force_color;
llvm::StringRef clicolor;
llvm::StringRef colorterm;
llvm::StringRef term_program;
llvm::StringRef term;
};
// Returns the color mode to render with.
//
// Whether to use color at all is decided first, from highest priority to
// lowest:
//
// - An explicit `Never` or `Always` preference.
// - `NO_COLOR` set to any non-empty value disables color: see
// https://no-color.org.
// - `FORCE_COLOR=0` disables color, following the Node convention.
// - Any other non-empty `FORCE_COLOR`, or a non-empty `CLICOLOR_FORCE` other
// than `0`, enables color even when the stream isn't a terminal.
// - `CLICOLOR=0` disables color.
// - `TERM=dumb` disables color, being an explicit statement that escape
// sequences won't render.
// - Otherwise color is used only when the stream is a terminal and something
// identifies that terminal: `TERM` set to anything else, or `COLORTERM` or
// `TERM_PROGRAM` set at all. The latter two stand on their own rather than
// refining `TERM`, because the emulator sets them itself and they are
// specifically about color, while `TERM` is left unset by anything not
// launched from a shell.
//
// How much color to use is then guessed from `FORCE_COLOR`'s level,
// `COLORTERM`, `TERM_PROGRAM`, and `TERM`, falling back to `Ansi16` when color
// is called for but nothing says how much of it works. Apart from
// `FORCE_COLOR`, which is a request rather than a description, none of these
// enable color on their own, so a rich `COLORTERM` inherited by a redirected
// stream can't put escape sequences into it.
//
// Depth comes from enumerating known terminals rather than from terminfo,
// which trades a list to maintain here for not depending on databases that are
// routinely absent from the containers and CI images this runs in. An
// unrecognized terminal gets the conservative answer.
//
// This is separated from `Capabilities::Detect` so that the policy can be
// tested without touching the process environment.
auto ChooseColorMode(Preference preference, const ColorEnvironment& env,
bool is_terminal) -> ColorMode;
// Returns the encoding to render with, where `locale` is the value of the
// first set variable among `LC_ALL`, `LC_CTYPE`, and `LANG`.
//
// Only a locale that names UTF-8 gets `Utf8`. Guessing wrong in that direction
// costs alignment on every line that isn't pure ASCII, while guessing wrong
// the other way only makes output plainer.
auto ChooseCharset(Preference preference, llvm::StringRef locale) -> Charset;
// Returns what the terminal draws its text on, where `colorfgbg` is the value
// of `COLORFGBG`.
//
// That variable is the only thing a process can read without talking to the
// terminal. `rxvt` and its derivatives set it, as do a few others, to the
// foreground and background palette indices separated by `;` -- sometimes with
// a third field between them -- so the background is the last of them. An index
// of 0 through 6 or 8 is a dark one, 7 and 9 through 15 a light one, and
// anything outside that range says nothing.
//
// It is missing far more often than it is present, and stale when the user
// changes their theme without restarting, so anything it doesn't answer is
// treated as dark. Guessing wrong that way costs contrast; guessing wrong the
// other way puts light text on a light background.
auto ChooseBackground(BackgroundPreference preference,
llvm::StringRef colorfgbg) -> Background;
// The width to lay out for when nothing says how wide the output is.
//
// Layout always has a width to fit, because the alternative is output laid out
// as if nothing bounded it, which a terminal then wraps at column zero --
// breaking every indent and gutter it was given, and in the middle of whatever
// word it lands on. The cost of guessing is asymmetric: a viewer wider than
// this sees slack on the right, while one narrower sees the wrapping done
// twice, ours and then its own.
//
// Eighty is the traditional terminal width, and narrower ones are rare enough
// that fitting them would cost more in wasted width everywhere else.
inline constexpr int DefaultColumns = 80;
// The columns between tab stops, absent anything saying otherwise.
//
// Eight is the interval terminfo records as `it#8` for all but a handful of
// legacy entries. Nothing measures a terminal's stops, so unlike its width this
// stands in for no measurement: `Capabilities` carries it as a plain value
// rather than as one a caller can tell apart from an absence.
inline constexpr int DefaultTabWidth = 8;
// What the terminal behind a stream can render, and how wide it is.
//
// Detect this once per stream at startup and pass it down; the fields come from
// environment queries and system calls that shouldn't be repeated per
// diagnostic.
struct Capabilities {
// Detects the capabilities of the terminal behind `file`, honoring
// `preferences`.
//
// Detection reads the descriptor directly, because `isatty` and `TIOCGWINSZ`
// are what answer the question and no stream abstraction exposes them.
// LLVM's `raw_ostream::has_colors()` is not a substitute for the enablement
// rule above, which recognizes terminals its `TERM` list doesn't.
//
// An `OSC 11` query would ask the terminal what it draws on, which is the
// only accurate answer and what `vim`, `delta`, and `bat` do. It isn't one a
// non-interactive tool can use: the reply has to be waited for, and drawing
// with it only when it arrives in time would leave the colors depending on
// that. Reading it also consumes whatever was typed ahead for the next shell
// command, along with the input a compile may be taking from stdin.
// `COLORFGBG` is the passive stand-in that costs none of this.
static auto Detect(Filesystem::WriteFileRef file,
Preferences preferences = {}) -> Capabilities;
// The richest color escapes the terminal is believed to understand.
ColorMode color_mode = ColorMode::NoColor;
// The encoding the terminal decodes output with.
Charset charset = Charset::Ascii;
// What the terminal draws its text on.
Background background = Background::Dark;
// Whether the stream is attached to a terminal at all. Note that color can
// still be in use when this is false, if the environment forces it.
bool is_terminal = false;
// The terminal's width, or none when nothing says how wide the output is.
// Positive whenever it is set, so layout can divide by it freely.
//
// This says what was measured, and nothing is invented to fill it in: an
// absence is a real answer about a pipe nobody described. Laying out still
// needs a width, and `DefaultColumns` is what a layout falls back to, so
// whether this is set decides whether output is fitted to the terminal in
// front of it or to a width chosen to be safe wherever it ends up.
std::optional<int> columns;
// The columns between the terminal's tab stops, which is what a tab in text
// advances to the next of.
//
// TODO: Nothing sets this away from `DefaultTabWidth`. A terminal's stops are
// mutable at runtime -- `hts` sets one and `tbc` clears them -- so the only
// report of the live ones is `DECRQPSR`, which few emulators outside `xterm`
// answer, or a `DSR-CPR` round trip after writing a tab, which nearly all do.
// Either means putting the descriptor in raw mode and reading a reply with a
// timeout. Add it when a terminal that disagrees with eight is worth that.
int tab_width = DefaultTabWidth;
};
} // namespace Carbon::Terminal
#endif // CARBON_COMMON_TERMINAL_CAPABILITIES_H_