Crate terminal_colorsaurus
source ·Expand description
Determines the background and foreground color of the terminal
using the OSC 10
and OSC 11
terminal sequence.
On Windows, the colors are queried using the Win32 Console API.
This crate helps answer the question “Is this terminal dark or light?”.
§Features
- Background and foreground color detection.
- Uses a timeout (for situations with high latency such as an SSH connection).
- Correct perceived lightness calculation.
- Works even if all of stderr, stdout and stdin are redirected.
- Safely restores the terminal from raw mode even if the library errors or panicks.
- Does not send any escape sequences if
TERM=dumb
.
§Example 1: Test If the Terminal Uses a Dark Background
use terminal_colorsaurus::{color_scheme, QueryOptions};
let colors = color_scheme(QueryOptions::default()).unwrap();
dbg!(colors.is_dark_on_light());
§Example 2: Query for the Terminal’s Foreground Color
use terminal_colorsaurus::{foreground_color, QueryOptions};
let fg = foreground_color(QueryOptions::default()).unwrap();
println!("rgb({}, {}, {})", fg.r, fg.g, fg.b);
§Terminals
The following terminals have known support or non-support for querying for the background/foreground colors.
Note that terminals that support the relevant terminal sequences automatically work with this library even if they are not explicitly listed below.
Supported
- macOS Terminal
- iTerm2
- Alacritty
- VSCode (xterm.js)
- IntelliJ IDEA
- Contour
- GNOME Terminal, (GNOME) Console, MATE Terminal, XFCE Terminal, (elementary) Terminal, LXTerminal
- Console
- foot
- xterm
- tmux (next-3.4)
- Windows Console (conhost)
Unsupported
- linux
- Jetbrains Fleet
- Windows Terminal
§Optional Dependencies
rgb
— Enable this feature to convert betweenColor
andrgb::RGB16
.
§Comparison with Other Crates
§termbg
- Is hardcoded to use stdin/stderr for communicating with the terminal.
This means that it does not work if some or all of these streams are redirected. - Pulls in an async runtime for the timeout.
- Does not calculate the perceived lightness, but another metric.
§terminal-light
- Is hardcoded to use stdin/stdout for communicating with the terminal.
- Does not report the colors, only the color’s luma.
- Does not calculate the perceived lightness, but another metric.
Modules§
- terminal_survey
docs
A list of terminals that were tested for support of DA1 (CSI c
) andOSC 10
/OSC 11
.
Structs§
- An RGB color with 16 bits per channel.
- The color scheme i.e. foreground and background colors of the terminal. Retrieved by calling
color_scheme
. - Preconditions that have to be met before querying.
- Options to be used with
foreground_color
andbackground_color
.
Enums§
- An error returned by this library.
Functions§
- Queries the terminal for it’s background color.
If you also need the foreground color it is more efficient to usecolor_scheme
instead. - Queries the terminal for it’s color scheme (foreground and background color).
- Queries the terminal for it’s foreground color.
If you also need the foreground color it is more efficient to usecolor_scheme
instead.
Type Aliases§
- Result used by this library.