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

!!! DO NOT EDIT THIS FILE BY HAND !!! This file is automatically generated by ‘rake autodoc:rdoc:session`. Any changes will be overwritten.

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

draw (tree = nil, &block)

Source

# File lib/ratatui_ruby.rb, line 137
def self.draw(tree = nil, &block)
  if tree && block
    raise ArgumentError, "Cannot provide both a tree and a block to draw"
  end
  unless tree || block
    raise ArgumentError, "Must provide either a tree or a block to draw"
  end

  if tree
    _draw(tree)
  else
    _draw(&block)
  end
end

Draws the given UI node tree to the terminal.

TUI applications need to render widgets to the screen. Rendering could happen all at once with a pre-built tree, or incrementally with direct frame access.

This method handles both. Pass a tree for declarative rendering, or pass a block to manipulate the frame directly. The block receives a {Frame} object for imperative drawing.

tree: A widget tree (Paragraph, Layout, etc.) to render. Optional if a block is given.

Examples

Legacy declarative style (tree-based):

RatatuiRuby.draw(Paragraph.new(text: "Hello"))

New imperative style (block-based):

RatatuiRuby.draw do |frame|
  frame.render_widget(Paragraph.new(text: "Hello"), frame.area)
end

get_cell_at (x, y)

Source

# File lib/ratatui_ruby.rb, line 240
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

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 63
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).

inject_test_event ()

Source

# File lib/ratatui_ruby.rb, line 83

Injects a mock event into the event queue for testing purposes.

event_type: “key” or “mouse”
data: a Hash containing event data

inject_test_event("key", { code: "a" })

(Native method implemented in Rust)

poll_event ()

Source

# File lib/ratatui_ruby.rb, line 170
def self.poll_event
  raw = _poll_event
  return Event::None.new 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

Checks for user input.

Returns a discrete event (Key, Mouse, Resize) if one is available in the queue. Returns RatatuiRuby::Event::None if the queue is empty (non-blocking).

Example

event = RatatuiRuby.poll_event
if event.none?
  puts "No input available"
elsif event.key?
  puts "Key pressed"
end

restore_terminal ()

Source

# File lib/ratatui_ruby.rb, line 76

Restores the terminal to its original state. Leaves alternate screen and disables raw mode.

(Native method implemented in Rust)

run (focus_events: true, bracketed_paste: true) { |session| ... }

Source

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

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 98
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

Warns about usage of an experimental feature unless warnings are suppressed.

feature_name: String name of the feature (e.g., “Paragraph#line_count”)

This warns only once per feature name per session.