Crate terminal_colorsaurus

Determines the background and foreground color of the terminal using the OSC 10 and OSC 11 terminal sequence.

This crate helps answer the question “Is this terminal dark or light?”.

Windows is not supported.

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, ColorScheme};

let color_scheme = color_scheme(QueryOptions::default()).unwrap();
dbg!(color_scheme == ColorScheme::Dark);

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

• Alacritty
• Contour
• foot
• GNOME Terminal, (GNOME) Console, MATE Terminal, XFCE Terminal, (elementary) Terminal, LXTerminal
• Hyper
• The builtin terminal of JetBrains IDEs (i.e. IntelliJ IDEA, …)
• iTerm2
• kitty
• Konsole
• macOS Terminal
• Rio
• st
• Terminology
• Termux
• tmux (next-3.4)
• urxvt (rxvt-unicode)
• VSCode (xterm.js)
• WezTerm
• xterm

Unsupported

• linux
• Jetbrains Fleet
• iSH

Optional Dependencies

• rgb — Enable this feature to convert between Color and rgb::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

• feature_detectiondocs
  How does colorsaurus detect if a terminal supports querying its colors?
• latencydocs
  What kind of latency do I have to expect?
• terminal_surveydocs
  A list of terminals that were tested for support of OSC 10 / OSC 11 and DA1 (= CSI c).
• windows_unsupporteddocs
  Why is Windows not supported?

Structs

• Color
  An RGB color with 16 bits per channel. You can use Color::scale_to_8bit to convert to an 8bit RGB color.
• ColorPalette
  The color palette i.e. foreground and background colors of the terminal. Retrieved by calling color_palette.
• QueryOptions
  Options to be used with foreground_color and background_color.

Enums

• ColorScheme
  The color scheme of the terminal.
• Error
  An error returned by this library.

Functions

• background_color
  Queries the terminal for it’s background color.
  If you also need the foreground color it is more efficient to use color_palette instead.
• color_palette
  Queries the terminal for it’s color scheme (foreground and background color).
• color_scheme
  Detects if the terminal is dark or light.
• foreground_color
  Queries the terminal for it’s foreground color.
  If you also need the foreground color it is more efficient to use color_palette instead.

Type Aliases

• Result
  Result used by this library.