module RatatuiRuby::Terminal::Capabilities

Queries how many colors the terminal can display.

Modern terminals vary wildly in capability. Some only support 8 ANSI colors. Others display 256. High-end terminals render 16 million truecolor shades. If your app uses rich color palettes without checking, users on basic terminals see garbled output or crashes.

This method queries crossterm (which checks COLORTERM and TERM) and returns the raw count. Use it to select color palettes or degrade gracefully.

Returns 8, 256, or 65535 (truecolor).

Example

colors = RatatuiRuby::Terminal.available_color_count
palette = colors >= 256 ? :rich : :basic

Returns the terminal’s color capability as a symbol.

Comparing integers is annoying. You want to know: can I use gradients? Do I need a fallback palette? This method translates the raw count into semantic symbols.

Returns :none when NO_COLOR is set or terminal is dumb. Returns :basic (8 colors), :ansi256 (256), or :truecolor (16M) based on capability.

Use it to switch rendering strategies or skip color entirely.

Example

case RatatuiRuby::Terminal.color_support
when :truecolor then use_gradient_theme
when :ansi256   then use_256_palette
when :basic     then use_ansi_colors
when :none      then use_monochrome
end

Checks if the terminal declared itself “dumb.”

Dumb terminals exist. Emacs shell-mode sets TERM=dumb. Serial consoles do too. These terminals cannot interpret escape sequences. If your app sends cursor movements or colors, output becomes unreadable.

This method checks for explicit TERM=dumb. Empty or unset TERM means “unknown,” not “dumb.” Use it to fall back to plain text rendering.

Example

if RatatuiRuby::Terminal.dumb?
  render_plain_table(data)
else
  render_styled_table(data)
end

Checks if color output is explicitly forced.

Some CI systems and logging pipelines detect non-TTY and strip colors. Users want colors anyway for readability. FORCE_COLOR overrides the TTY check.

This method checks for FORCE_COLOR in the environment. When set, your app should emit colors even when tty? returns false.

Example

use_color = RatatuiRuby::Terminal.tty? ||
            RatatuiRuby::Terminal.force_color?

Globally override NO_COLOR detection.

The NO_COLOR environment variable tells applications to disable color. Sometimes users want colors anyway, like in CI pipelines that log to files but display logs with color. Passing true forces color output regardless of NO_COLOR.

This method calls crossterm’s global override. The effect is immediate and affects all subsequent color detection queries. Pass false to restore normal NO_COLOR behavior.

Example

if options[:color] == :always
  RatatuiRuby::Terminal.force_color_output(true)
end

Checks if the terminal supports interactive TUI mode.

A TUI needs a real terminal. Piped output breaks cursor control. Dumb terminals corrupt escape sequences. Starting TUI mode in these environments wastes resources and confuses users.

This method combines tty? and dumb? checks. Returns true only when both conditions allow TUI operation. Use it as the gatekeeper before calling run.

Example

if RatatuiRuby::Terminal.interactive?
  RatatuiRuby.run { |tui| main_loop(tui) }
else
  abort "Interactive terminal required"
end

Checks if the user disabled color output.

Users with visual impairments or screen readers often disable colors. The NO_COLOR standard (no-color.org) provides a universal way to request this. Ignoring it frustrates accessibility-conscious users.

This method checks for NO_COLOR in the environment. The value does not matter; presence alone disables color. Respect it.

Example

style = RatatuiRuby::Terminal.no_color? ? :plain : :colored

Checks for Kitty keyboard protocol support.

Standard terminal input is ambiguous. Escape key and arrow keys share prefixes. Modifier keys get lost. Applications that need precise key handling (editors, games) struggle with the limitations.

The Kitty keyboard protocol solves this. Terminals that support it report key presses unambiguously, with full modifier information. This method queries support so you can enable enhanced input or fall back gracefully.

Returns false immediately if tty? returns false. Otherwise queries crossterm with a 0.5s timeout. Returns true only if the terminal responds affirmatively.

Example

if RatatuiRuby::Terminal.supports_keyboard_enhancement?
  enable_vim_style_keybindings
else
  use_simple_navigation
end

Checks if stdout connects to a terminal device.

Terminal apps render escape sequences. Piped output or log files cannot interpret them. If your app writes ANSI codes to a non-TTY, logs fill with garbage like [32m instead of green text.

This method checks $stdout.tty?. Use it to skip TUI mode when output is redirected. Print plain text instead.

Example

if RatatuiRuby::Terminal.tty?
  start_tui
else
  print_plain_output
end