Module: RatatuiRuby::Debug

Defined in:
lib/ratatui_ruby/debug.rb

Overview

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

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

# Programmatic activation
RatatuiRuby::Debug.enable!

# Or use the convenience alias
RatatuiRuby.debug_mode!

– SPDX-SnippetEnd ++

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.enable!(source: :programmatic) ⇒ Object

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,

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

<tt>:test</tt> from TestHelper (skips remote debugging),
<tt>:programmatic</tt> otherwise.

– SPDX-SnippetEnd ++



80
81
82
83
84
85
86
87
88
89
90
91
 
# 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

.enable_rust_backtrace! ⇒ Object

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.



54
55
56
57
58
59
 
# 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

Instance Method Details

#enabled? ⇒ Boolean

Returns whether full debug mode is enabled.

Returns:

  • (Boolean) 


128
129
130
 
# File 'lib/ratatui_ruby/debug.rb', line 128

public def enabled?
  @debug_mode_enabled
end

#remote_debugging_mode ⇒ Object

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.



151
152
153
 
# File 'lib/ratatui_ruby/debug.rb', line 151

public def remote_debugging_mode
  @remote_debugging_mode
end

#rust_backtrace_enabled? ⇒ Boolean

Returns whether Rust backtraces are enabled.

Returns:

  • (Boolean) 


134
135
136
 
# File 'lib/ratatui_ruby/debug.rb', line 134

public def rust_backtrace_enabled?
  @rust_backtrace_enabled
end

#suppress_debug_mode ⇒ Object

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

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

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

– SPDX-SnippetEnd ++



202
203
204
205
206
207
208
 
# File 'lib/ratatui_ruby/debug.rb', line 202

public def suppress_debug_mode
  old_value = @debug_mode_enabled
  @debug_mode_enabled = false
  yield
ensure
  @debug_mode_enabled = old_value
end

#test_panic! ⇒ Object

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

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

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

– SPDX-SnippetEnd ++



178
179
180
 
# File 'lib/ratatui_ruby/debug.rb', line 178

public def test_panic!
  RatatuiRuby.__send__(:_test_panic)
end