module RatatuiRuby

Main entry point for the library.

Terminal UIs require low-level control using C/Rust and high-level abstraction in Ruby.

This module bridges the gap. It provides the native methods to initialize the terminal, handle raw mode, and render the widget tree.

Use ‘RatatuiRuby.run` to start your application.

SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com> SPDX-License-Identifier: AGPL-3.0-or-later

Constants

VERSION: The version of the ratatui_ruby gem. See semver.org/spec/v2.0.0.html

Attributes

experimental_warnings [RW]

:attr_accessor: experimental_warnings Whether to show warnings when using experimental features (default: true).

Public Class Methods

get_cell_at(x, y) → Cell

Source

# File lib/ratatui_ruby.rb, line 213
def self.get_cell_at(x, y)
  raw = _get_cell_at(x, y)
  Cell.new(
    char: raw["char"],
    fg: raw["fg"],
    bg: raw["bg"],
    modifiers: raw["modifiers"] || []
  )
end

:method: get_cell_at

Inspects the terminal buffer at specific coordinates.

When writing tests, you need to verify that your widget drew the correct characters and styles. This method provides deep inspection of the cell’s state (symbol, colors, modifiers).

Returns a {Cell} object.

Values depend on what the backend has rendered. If nothing has been rendered to a cell, it may contain defaults (empty symbol, nil colors).

Example

cell = RatatuiRuby.get_cell_at(10, 5)
expect(cell.symbol).to eq("X")
expect(cell.fg).to eq(:red)
expect(cell).to be_bold

init_terminal (focus_events: true, bracketed_paste: true)

Source

# File lib/ratatui_ruby.rb, line 62
def self.init_terminal(focus_events: true, bracketed_paste: true)
  _init_terminal(focus_events, bracketed_paste)
end

Initializes the terminal for TUI mode. Enters alternate screen and enables raw mode.

focus_events: whether to enable focus gain/loss events (default: true).
bracketed_paste: whether to enable bracketed paste mode (default: true).

poll_event() → Event, nil

Source

# File lib/ratatui_ruby.rb, line 125
def self.poll_event
  raw = _poll_event
  return nil if raw.nil?

  case raw[:type]
  when :key
    Event::Key.new(code: raw[:code], modifiers: raw[:modifiers] || [])
  when :mouse
    Event::Mouse.new(
      kind: raw[:kind].to_s,
      x: raw[:x],
      y: raw[:y],
      button: raw[:button].to_s,
      modifiers: raw[:modifiers] || []
    )
  when :resize
    Event::Resize.new(width: raw[:width], height: raw[:height])
  when :paste
    Event::Paste.new(content: raw[:content])
  when :focus_gained
    Event::FocusGained.new
  when :focus_lost
    Event::FocusLost.new
  else
    # Fallback for unknown events, though ideally we cover them all
    nil
  end
end

:method: poll_event

Checks for user input.

Returns a discrete event (Key, Mouse, Resize) if one is available in the queue. Returns nil immediately if the queue is empty (non-blocking).

Example

event = RatatuiRuby.poll_event
puts "Key pressed" if event.is_a?(RatatuiRuby::Event::Key)

run { |session| ... } → Object

Source

# File lib/ratatui_ruby.rb, line 185
def self.run(focus_events: true, bracketed_paste: true)
  require_relative "ratatui_ruby/session"
  init_terminal(focus_events: focus_events, bracketed_paste: bracketed_paste)
  yield Session.new
ensure
  restore_terminal
end

:method: run

Starts the TUI application lifecycle.

Managing generic setup/teardown (raw mode, alternate screen) manualy is error-prone. If your app crashes, the terminal might be left in a broken state.

This method handles the safety net. It initializes the terminal, yields a {Session}, and ensures the terminal state is restored even if exceptions occur.

Example

RatatuiRuby.run(focus_events: false) do |tui|
  tui.draw(tui.paragraph(text: "Hi"))
  sleep 1
end

warn_experimental_feature (feature_name)

Source

# File lib/ratatui_ruby.rb, line 80
def self.warn_experimental_feature(feature_name)
  return unless experimental_warnings

  @warned_features ||= {}
  return if @warned_features[feature_name]

  warn "WARNING: #{feature_name} is an experimental feature and may change in future versions. Disable this warning with RatatuiRuby.experimental_warnings = false."
  @warned_features[feature_name] = true
end