Class: Canon::ColorDetector

Inherits:
Object
  • Object
show all
Defined in:
lib/canon/color_detector.rb

Overview

Detects whether the current terminal supports color output.

This class provides cross-platform detection of terminal color capabilities by checking environment variables and, on Unix-like systems, optionally querying the terminfo database.

Detection Logic

The detection follows this priority order:

  1. NO_COLOR: If set (regardless of value), colors are disabled (per no-color.org/)

  2. **Explicit user choice**: If explicitly set, honor that choice

  3. **Terminal capability detection**:

    • COLORTERM=24bit or truecolor → True color support

    • TERM ending with 256 or 256color → 256-color support

    • TERM=dumb, TERM containing “emacs” → No color support

    • CI environment → Check specific CI variables

    • TTY detection → Only enable colors if output is to a TTY

Usage

# Auto-detect
ColorDetector.supports_color?  # => true or false

# Explicit choice (bypass detection)
ColorDetector.supports_color?(explicit: true)   # => true
ColorDetector.supports_color?(explicit: false)  # => false

# With output stream check
ColorDetector.supports_color?(output: $stdout)

Constant Summary collapse

COLOR_TERM_VALUES =

Environment variables that indicate color support

%w[24bit truecolor true].freeze
COLOR_TERM_SUFFIXES = 
%w[256 256color direct].freeze
NO_COLOR_TERMS = 
%w[dumb emacs].freeze
CI_ENV_VARS = 
%w[CI GITHUB_ACTIONS TRAVIS GITLAB_CI JENKINS_HOME].freeze

Class Method Summary collapse

Class Method Details

.supports_color?(explicit: nil, output: $stdout) ⇒ Boolean

Detect whether the current environment supports color output.

Parameters:

  • explicit (Boolean, nil) (defaults to: nil) —

    Explicit user choice to bypass detection

  • output (IO, nil) (defaults to: $stdout) —

    Output stream to check (default: $stdout)

Returns:

  • (Boolean) —

    true if colors are supported, false otherwise



49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/canon/color_detector.rb', line 49

def supports_color?(explicit: nil, output: $stdout)
  # 1. NO_COLOR always wins (per https://no-color.org/)
  return false if ENV.key?("NO_COLOR")

  # 2. Explicit user choice bypasses detection
  return explicit unless explicit.nil?

  # 3. Check if output is a TTY (don't use colors for piped/file output)
  return false unless tty?(output)

  # 4. Check terminal capability indicators
  detect_from_env
end