Module: RatatuiRuby::Terminal::Capabilities

Included in:
RatatuiRuby::Terminal
Defined in:
lib/ratatui_ruby/terminal/capabilities.rb

Overview

Environment-based terminal capability detection.

TUI applications need to know what the terminal supports. Color depth varies. Some terminals lack escape sequence support entirely. Users set environment variables like NO_COLOR to express preferences.

This module detects terminal capabilities from environment variables. It checks TERM, COLORTERM, NO_COLOR, and FORCE_COLOR to determine what the terminal supports.

Use these methods before initializing a Terminal instance to decide whether TUI mode is appropriate for the current environment.

Example

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

if RatatuiRuby::Terminal.interactive?
  RatatuiRuby.run { |tui| ... }
else
  puts "TUI mode not available"
end

– SPDX-SnippetEnd ++

Instance Method Summary collapse

Instance Method Details

#available_color_count ⇒ Object

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++



204
205
206
 
# File 'lib/ratatui_ruby/terminal/capabilities.rb', line 204

def available_color_count
  _available_color_count
end

#color_support ⇒ Object

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++



236
237
238
239
240
241
242
243
244
245
 
# File 'lib/ratatui_ruby/terminal/capabilities.rb', line 236

def color_support
  return :none if no_color?
  return :none if dumb?

  count = available_color_count
  return :truecolor if count >= 65_535
  return :ansi256 if count >= 256

  :basic
end

#dumb? ⇒ Boolean

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++

Returns:

  • (Boolean) 


95
96
97
 
# File 'lib/ratatui_ruby/terminal/capabilities.rb', line 95

def dumb?
  ENV["TERM"] == "dumb"
end

#force_color? ⇒ Boolean

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++

Returns:

  • (Boolean) 


146
147
148
 
# File 'lib/ratatui_ruby/terminal/capabilities.rb', line 146

def force_color?
  ENV.key?("FORCE_COLOR")
end

#force_color_output(enable) ⇒ Object

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++



309
310
311
 
# File 'lib/ratatui_ruby/terminal/capabilities.rb', line 309

def force_color_output(enable)
  _force_color_output(enable)
end

#interactive? ⇒ Boolean

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++

Returns:

  • (Boolean) 


175
176
177
 
# File 'lib/ratatui_ruby/terminal/capabilities.rb', line 175

def interactive?
  tty? && !dumb?
end

#no_color? ⇒ Boolean

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++

Returns:

  • (Boolean) 


120
121
122
 
# File 'lib/ratatui_ruby/terminal/capabilities.rb', line 120

def no_color?
  ENV.key?("NO_COLOR")
end

#supports_keyboard_enhancement? ⇒ Boolean

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++

Returns:

  • (Boolean) 


277
278
279
280
281
282
283
 
# File 'lib/ratatui_ruby/terminal/capabilities.rb', line 277

def supports_keyboard_enhancement?
  return false unless tty?

  Timeout.timeout(0.5) { _supports_keyboard_enhancement }
rescue
  false
end

#tty? ⇒ Boolean

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

– SPDX-SnippetBegin SPDX-FileCopyrightText: 2026 Kerrick Long SPDX-License-Identifier: MIT-0 ++

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

– SPDX-SnippetEnd ++

Returns:

  • (Boolean) 


65
66
67
 
# File 'lib/ratatui_ruby/terminal/capabilities.rb', line 65

def tty?
  $stdout.tty?
end