module RatatuiRuby::Debug

Debug mode control for RatatuiRuby.

TUI applications are hard to debug. Rust panics show cryptic stack traces. Ruby exceptions lack Rust context.

This module controls debug visibility. Enable Rust backtraces only, or enable full debug mode for both Rust and Ruby-side features.

Activation Methods

Three ways to enable debug features:

RUST_BACKTRACE=1: Rust backtraces only (no Ruby-side debug).
RR_DEBUG=1: Full debug mode (backtraces + Ruby features).
include RatatuiRuby::TestHelper: Auto-enables debug mode.

Example

# Programmatic activation
RatatuiRuby::Debug.enable!

# Or use the convenience alias
RatatuiRuby.debug_mode!

Public Class Methods

enable! (source: :programmatic)

Source

# File lib/ratatui_ruby/debug.rb, line 80
def enable!(source: :programmatic)
  return @socket_path if @debug_mode_enabled

  @debug_mode_enabled = true
  enable_rust_backtrace!

  # Tests don't need remote debugging — it would cause hangs
  return if source == :test

  @remote_debugging_mode = (source == :env) ? :open : :open_nonstop
  @socket_path = enable_remote_debugging!
end

Enables full debug mode.

Activates Rust backtraces plus any Ruby-side debug features. Optionally enables remote debugging via the debug gem.

Safe to call multiple times; subsequent calls are no-ops.

source: :env if called from RR_DEBUG env var, :test from TestHelper (skips remote debugging), :programmatic otherwise.

enable_rust_backtrace! ()

Source

# File lib/ratatui_ruby/debug.rb, line 54
def enable_rust_backtrace!
  return if @rust_backtrace_enabled

  @rust_backtrace_enabled = true
  RatatuiRuby.__send__(:_enable_rust_backtrace)
end

Enables Rust backtraces only.

Call this to get meaningful stack traces when Rust panics. Does not enable Ruby-side debug features.

Safe to call multiple times; subsequent calls are no-ops.

enabled? ()

Source

# File lib/ratatui_ruby/debug.rb, line 128
       def enabled?
  @debug_mode_enabled
end

Returns whether full debug mode is enabled.

remote_debugging_mode ()

Source

# File lib/ratatui_ruby/debug.rb, line 151
       def remote_debugging_mode
  @remote_debugging_mode
end

Returns the remote debugging mode for debug gem integration.

TUI apps run in raw terminal mode, making interactive debugging impossible. The debug gem’s remote debugging feature lets you attach from another terminal via UNIX socket.

Returns one of: :open Stop at program start, wait for debugger attach.

Activated when <tt>RR_DEBUG=1</tt> is set at startup.

:open_nonstop Continue running, attach whenever ready.

Activated when <tt>enable!</tt> is called programmatically.

nil No remote debugging configured.

rust_backtrace_enabled? ()

Source

# File lib/ratatui_ruby/debug.rb, line 134
       def rust_backtrace_enabled?
  @rust_backtrace_enabled
end

Returns whether Rust backtraces are enabled.

suppress_debug_mode () { || ... }

Source

# File lib/ratatui_ruby/debug.rb, line 202
       def suppress_debug_mode
  old_value = @debug_mode_enabled
  @debug_mode_enabled = false
  yield
ensure
  @debug_mode_enabled = old_value
end

Temporarily suppresses Ruby-side debug mode checks.

Rust backtraces remain enabled if previously activated; only Ruby-side features (like unknown-key errors) are suppressed within the block.

Example

RatatuiRuby::Debug.suppress_debug_mode do
  tui.table({ unknown_key: 1 }) # Does not raise
end

test_panic! ()

Source

# File lib/ratatui_ruby/debug.rb, line 178
       def test_panic!
  RatatuiRuby.__send__(:_test_panic)
end

Triggers a Rust panic for backtrace verification.

Debugging TUI apps is hard. Rust errors lack context. You want to confirm RUST_BACKTRACE=1 actually shows stack traces before hitting a real bug.

This method deliberately panics. The panic hook catches it and prints the Rust backtrace to stderr. If you see stack frames, your setup works.

WARNING: Crashes your process. Use only for debugging.

Example

RUST_BACKTRACE=1 ruby -e 'require "ratatui_ruby"; RatatuiRuby::Debug.test_panic!'