Module: Tuile::ColorDepth

Defined in:
lib/tuile/color_depth.rb,
sig/tuile.rbs

Overview

How many colors the terminal on the other end can actually show — the depth Tuile::Color#quantize degrades a color to:

ColorDepth.detect                                        # => :truecolor
ColorDepth.detect(env: { "TERM" => "xterm-256color" })   # => :palette256
ColorDepth.detect(env: {})                               # => :ansi16

Env-only: no terminal round-trip, so unlike TerminalBackground.detect there is no stdin timing to respect, and the answer cannot go stale mid-session the way a background color can.

Terminals lie in both directions — COLORTERM frequently doesn't survive ssh (it isn't in the default SendEnv set) or tmux — so OVERRIDE_ENV beats every other signal, the escape hatch for a terminal detected wrong. Misdetection otherwise lands conservatively: a truecolor tmux advertising only tmux-256color reads as :palette256, which renders coarser but never mangled.

Implementation details

Terminfo is deliberately not consulted — its RGB boolean and colors#0x1000000 would mean shelling out to tput/infocmp at every startup, and the env ladder plus the override already covers the real terminal matrix.

Constant Summary collapse

DEPTHS =

The depths, most capable first: 24-bit RGB, the 256-color palette, and the 16 named ANSI colors.

Returns:

  • (Array<Symbol>) 
%i[truecolor palette256 ansi16].freeze
OVERRIDE_ENV =

Environment variable that overrides detection outright; holds one of DEPTHS. Empty counts as unset.

Returns:

  • (String) 
"TUILE_COLOR_DEPTH"
TRUECOLOR_COLORTERM =

COLORTERM values that promise 24-bit color.

Returns:

  • (Array<String>) 
%w[truecolor 24bit].freeze

Class Method Summary collapse

Class Method Details

.detect(env: ENV) ⇒ Symbol

The terminal's color depth, from OVERRIDE_ENV, else COLORTERM, else TERM (a -direct entry means 24-bit, a 256color one the palette), else the 16-color floor.

@param env — environment to read; defaults to ENV (which duck-types the [] lookup).

@return — one of DEPTHS.

Parameters:

  • env: (::Hash[String, String]) (defaults to: ENV)

Returns:

  • (Symbol) 


55
56
57
58
59
60
61
62
63
64
65
 
# File 'lib/tuile/color_depth.rb', line 55

def detect(env: ENV)
  override = env[OVERRIDE_ENV].to_s
  return parse_override(override) unless override.empty?

  term = env["TERM"].to_s
  return :truecolor if TRUECOLOR_COLORTERM.include?(env["COLORTERM"].to_s.downcase) ||
                       term.include?("-direct")
  return :palette256 if term.include?("256color")

  :ansi16
end