ratatui_ruby 0.3.1 → 0.5.0

data/ext/ratatui_ruby/src/frame.rs

@@ -0,0 +1,115 @@
+// SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+//! Frame wrapper for exposing Ratatui's Frame to Ruby.
+//!
+//! This module provides `RubyFrame`, a struct that wraps `ratatui::Frame` and exposes
+//! it to Ruby via Magnus. It enables explicit widget placement through `render_widget`,
+//! aligning `RatatuiRuby` with native Rust Ratatui patterns.
+//!
+//! # Safety
+//!
+//! `RubyFrame` uses raw pointer casting to store a `Frame` reference with an erased
+//! lifetime. This is safe because:
+//! 1. `RubyFrame` is only created within `Terminal::draw()` callbacks
+//! 2. `RubyFrame` is never returned from or stored beyond the callback scope
+//! 3. The Ruby block receiving `RubyFrame` completes before the callback returns
+//!
+//! The `'static` lifetime is a lie, but a safe one within these constraints.
+
+use crate::rendering;
+use magnus::{prelude::*, Error, Value};
+use ratatui::layout::Rect;
+use ratatui::Frame;
+use std::cell::UnsafeCell;
+use std::ptr::NonNull;
+
+/// A wrapper around Ratatui's `Frame` that can be exposed to Ruby.
+///
+/// This struct uses raw pointers to hold a mutable reference to the frame,
+/// which is valid only for the duration of the draw callback.
+///
+/// # Safety
+///
+/// We implement `Send` manually because:
+/// 1. `RubyFrame` is only created and used within a single `Terminal::draw()` callback
+/// 2. The Ruby VM is single-threaded (GVL), so the frame pointer is never accessed
+///    from multiple threads simultaneously
+/// 3. `RubyFrame` never escapes the draw callback scope
+#[magnus::wrap(class = "RatatuiRuby::Frame")]
+pub struct RubyFrame {
+    /// Pointer to the underlying frame. Valid only during the draw callback.
+    inner: UnsafeCell<NonNull<Frame<'static>>>,
+}
+
+// SAFETY: RubyFrame is only used within Terminal::draw() callbacks, which are
+// single-threaded. The Ruby VM's GVL ensures no concurrent access.
+unsafe impl Send for RubyFrame {}
+
+impl RubyFrame {
+    /// Creates a new `RubyFrame` wrapping the given frame reference.
+    ///
+    /// # Safety
+    ///
+    /// The caller must ensure that:
+    /// 1. The `RubyFrame` does not outlive the frame reference
+    /// 2. No other mutable references to the frame exist while `RubyFrame` is in use
+    pub fn new(frame: &mut Frame<'_>) -> Self {
+        // SAFETY: We cast the frame pointer to 'static lifetime. This is safe because:
+        // - RubyFrame is only used within Terminal::draw() callbacks
+        // - The Ruby block completes before the callback returns
+        // - No reference to RubyFrame escapes the callback scope
+        let ptr = NonNull::from(frame);
+        let static_ptr: NonNull<Frame<'static>> =
+            // SAFETY: Lifetime erasure is safe within the draw callback scope.
+            // The frame pointer remains valid for the entire callback duration.
+            unsafe { std::mem::transmute(ptr) };
+
+        Self {
+            inner: UnsafeCell::new(static_ptr),
+        }
+    }
+
+    /// Returns the terminal area as a Ruby `RatatuiRuby::Rect`.
+    ///
+    /// This mirrors `frame.area()` in Rust Ratatui.
+    pub fn area(&self) -> Result<Value, Error> {
+        let ruby = magnus::Ruby::get().unwrap();
+
+        // SAFETY: The frame pointer is valid for the duration of the draw callback.
+        // We only read from the frame, which is safe with an immutable reference.
+        let area = unsafe { (*self.inner.get()).as_ref().area() };
+
+        // Create a Ruby Rect object
+        let module = ruby.define_module("RatatuiRuby")?;
+        let class = module.const_get::<_, magnus::RClass>("Rect")?;
+        class.funcall("new", (area.x, area.y, area.width, area.height))
+    }
+
+    /// Renders a widget at the specified area.
+    ///
+    /// This mirrors `frame.render_widget(widget, area)` in Rust Ratatui.
+    ///
+    /// # Arguments
+    ///
+    /// * `widget` - A Ruby widget object (e.g., `RatatuiRuby::Paragraph`)
+    /// * `area` - A Ruby `Rect` or hash-like object with `x`, `y`, `width`, `height`
+    pub fn render_widget(&self, widget: Value, area: Value) -> Result<(), Error> {
+        // Parse the Ruby area into a Rust Rect
+        let x: u16 = area.funcall("x", ())?;
+        let y: u16 = area.funcall("y", ())?;
+        let width: u16 = area.funcall("width", ())?;
+        let height: u16 = area.funcall("height", ())?;
+        let rect = Rect::new(x, y, width, height);
+
+        // SAFETY: The frame pointer is valid for the duration of the draw callback.
+        // We take a mutable reference which is safe because:
+        // 1. RubyFrame is only used within Terminal::draw() callbacks
+        // 2. Ruby's GVL ensures single-threaded access
+        // 3. No other code holds a reference to the frame during this call
+        let frame = unsafe { (*self.inner.get()).as_mut() };
+
+        // Delegate to the existing render_node function
+        rendering::render_node(frame, rect, widget)
+    }
+}

data/ext/ratatui_ruby/src/lib.rs

@@ -1,41 +1,103 @@
 // SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
-mod buffer;
+// Require SAFETY comments on all unsafe blocks
+#![warn(clippy::undocumented_unsafe_blocks)]
+// Enable pedantic lints for stricter code quality
+#![warn(clippy::pedantic)]
+// Allow certain pedantic lints that are too noisy for FFI code
+#![allow(clippy::missing_errors_doc)]
+#![allow(clippy::missing_panics_doc)]
+#![allow(clippy::module_name_repetitions)]
+
 mod events;
+mod frame;
 mod rendering;
 mod style;
 mod terminal;
+mod text;
 mod widgets;
 
-use magnus::{function, Class, Error, Module, Value};
+use frame::RubyFrame;
+use magnus::{function, method, Error, Module, Object, Ruby, Value};
 use terminal::{init_terminal, restore_terminal, TERMINAL};
 
-fn draw(tree: Value) -> Result<(), Error> {
-    let ruby = magnus::Ruby::get().unwrap();
+/// Draw to the terminal.
+///
+/// Supports two calling conventions:
+/// - Legacy: `RatatuiRuby.draw(tree)` - Renders a widget tree to the full terminal area
+/// - New: `RatatuiRuby.draw { |frame| ... }` - Yields a Frame for explicit widget placement
+fn draw(args: &[Value]) -> Result<(), Error> {
+    let ruby = Ruby::get().unwrap();
+
+    // Parse arguments: check for optional tree argument
+    let tree: Option<Value> = if args.is_empty() {
+        None
+    } else if args.len() == 1 {
+        Some(args[0])
+    } else {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            format!(
+                "wrong number of arguments (given {}, expected 0..1)",
+                args.len()
+            ),
+        ));
+    };
+    let block_given = ruby.block_given();
+
+    // Validate: must have either tree or block, but not both
+    if tree.is_some() && block_given {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "Cannot provide both a tree and a block to draw",
+        ));
+    }
+    if tree.is_none() && !block_given {
+        return Err(Error::new(
+            ruby.exception_arg_error(),
+            "Must provide either a tree or a block to draw",
+        ));
+    }
+
     let mut term_lock = TERMINAL.lock().unwrap();
+    let mut render_error: Option<Error> = None;
+
+    // Helper closure to execute the draw callback logic for either terminal type
+    let mut draw_callback = |f: &mut ratatui::Frame<'_>| {
+        if block_given {
+            // New API: yield RubyFrame to block
+            let ruby_frame = RubyFrame::new(f);
+            if let Err(e) = ruby.yield_value::<_, Value>(ruby_frame) {
+                render_error = Some(e);
+            }
+        } else if let Some(tree_value) = tree {
+            // Legacy API: render tree to full area
+            if let Err(e) = rendering::render_node(f, f.area(), tree_value) {
+                render_error = Some(e);
+            }
+        }
+    };
+
     if let Some(wrapper) = term_lock.as_mut() {
         match wrapper {
             terminal::TerminalWrapper::Crossterm(term) => {
-                term.draw(|f| {
-                    if let Err(e) = rendering::render_node(f, f.area(), tree) {
-                        eprintln!("Render error: {:?}", e);
-                    }
-                })
-                .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
+                term.draw(&mut draw_callback)
+                    .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
             }
             terminal::TerminalWrapper::Test(term) => {
-                term.draw(|f| {
-                    if let Err(e) = rendering::render_node(f, f.area(), tree) {
-                        eprintln!("Render error: {:?}", e);
-                    }
-                })
-                .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
+                term.draw(&mut draw_callback)
+                    .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
             }
         }
     } else {
         eprintln!("Terminal is None!");
     }
+
+    if let Some(e) = render_error {
+        return Err(e);
+    }
+
     Ok(())
 }
 
@@ -44,16 +106,17 @@ fn init() -> Result<(), Error> {
     let ruby = magnus::Ruby::get().unwrap();
     let m = ruby.define_module("RatatuiRuby")?;
 
-    let buffer_class = m.define_class("Buffer", ruby.class_object())?;
-    buffer_class.undef_default_alloc_func();
-    buffer_class.define_method("set_string", magnus::method!(buffer::BufferWrapper::set_string, 4))?;
-    buffer_class.define_method("area", magnus::method!(buffer::BufferWrapper::area, 0))?;
-
-    m.define_module_function("init_terminal", function!(init_terminal, 0))?;
+    m.define_module_function("_init_terminal", function!(init_terminal, 2))?;
     m.define_module_function("restore_terminal", function!(restore_terminal, 0))?;
-    m.define_module_function("draw", function!(draw, 1))?;
-    m.define_module_function("poll_event", function!(events::poll_event, 0))?;
+    m.define_module_function("_draw", function!(draw, -1))?;
+
+    // Register Frame class
+    let frame_class = m.define_class("Frame", ruby.class_object())?;
+    frame_class.define_method("area", method!(RubyFrame::area, 0))?;
+    frame_class.define_method("render_widget", method!(RubyFrame::render_widget, 2))?;
+    m.define_module_function("_poll_event", function!(events::poll_event, 0))?;
     m.define_module_function("inject_test_event", function!(events::inject_test_event, 2))?;
+    m.define_module_function("clear_events", function!(events::clear_events, 0))?;
 
     // Test backend helpers
     m.define_module_function(
@@ -68,8 +131,26 @@ fn init() -> Result<(), Error> {
         "get_cursor_position",
         function!(terminal::get_cursor_position, 0),
     )?;
+    m.define_module_function("_get_cell_at", function!(terminal::get_cell_at, 2))?;
     m.define_module_function("resize_terminal", function!(terminal::resize_terminal, 2))?;
 
+    // Register Layout.split on the Layout class
+    let layout_class = m.const_get::<_, magnus::RClass>("Layout")?;
+    layout_class.define_singleton_method("_split", function!(widgets::layout::split_layout, 4))?;
+
+    // Paragraph metrics
+    m.define_module_function(
+        "_paragraph_line_count",
+        function!(widgets::paragraph::line_count, 2),
+    )?;
+    m.define_module_function(
+        "_paragraph_line_width",
+        function!(widgets::paragraph::line_width, 1),
+    )?;
+
+    // Tabs metrics
+    m.define_module_function("_tabs_width", function!(widgets::tabs::width, 1))?;
+
     Ok(())
 }
 

data/ext/ratatui_ruby/src/rendering.rs

@@ -1,29 +1,40 @@
 // SPDX-FileCopyrightText: 2025 Kerrick Long <me@kerricklong.com>
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
-use crate::buffer::BufferWrapper;
+use crate::style::{parse_color_value, parse_modifier_str, parse_style};
 use crate::widgets;
-use magnus::{prelude::*, Error, Value};
-use ratatui::{layout::Rect, Frame};
+use magnus::{prelude::*, Error, RArray, Value};
+use ratatui::{buffer::Buffer, layout::Rect, style::Style, Frame};
 
 pub fn render_node(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Error> {
     if node.respond_to("render", true)? {
-        let wrapper = BufferWrapper::new(frame.buffer_mut());
         let ruby = magnus::Ruby::get().unwrap();
         let ruby_area = {
             let module = ruby.define_module("RatatuiRuby")?;
             let class = module.const_get::<_, magnus::RClass>("Rect")?;
             class.funcall::<_, _, Value>("new", (area.x, area.y, area.width, area.height))?
         };
-        let wrapper_obj = ruby.obj_wrap(wrapper);
-        node.funcall::<_, _, Value>("render", (ruby_area, wrapper_obj))?;
+
+        // Call render with just the area (no buffer!)
+        let commands: Value = node.funcall("render", (ruby_area,))?;
+
+        // Process returned draw commands
+        if let Some(arr) = RArray::from_value(commands) {
+            for i in 0..arr.len() {
+                let ruby = magnus::Ruby::get().unwrap();
+                let index = isize::try_from(i)
+                    .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+                let cmd: Value = arr.entry(index)?;
+                process_draw_command(frame.buffer_mut(), cmd)?;
+            }
+        }
         return Ok(());
     }
 
-    let class = node.class();
-    let class_name = unsafe { class.name() };
+    // SAFETY: Immediate conversion to owned string avoids GC-unsafe borrowed reference.
+    let class_name = unsafe { node.class().name() }.into_owned();
 
-    match class_name.as_ref() {
+    match class_name.as_str() {
         "RatatuiRuby::Paragraph" => widgets::paragraph::render(frame, area, node)?,
         "RatatuiRuby::Clear" => widgets::clear::render(frame, area, node)?,
         "RatatuiRuby::Cursor" => widgets::cursor::render(frame, area, node)?,
@@ -32,6 +43,7 @@ pub fn render_node(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Err
         "RatatuiRuby::Layout" => widgets::layout::render(frame, area, node)?,
         "RatatuiRuby::List" => widgets::list::render(frame, area, node)?,
         "RatatuiRuby::Gauge" => widgets::gauge::render(frame, area, node)?,
+        "RatatuiRuby::LineGauge" => widgets::line_gauge::render(frame, area, node)?,
         "RatatuiRuby::Table" => widgets::table::render(frame, area, node)?,
         "RatatuiRuby::Block" => widgets::block::render(frame, area, node)?,
         "RatatuiRuby::Tabs" => widgets::tabs::render(frame, area, node)?,
@@ -41,9 +53,81 @@ pub fn render_node(frame: &mut Frame, area: Rect, node: Value) -> Result<(), Err
         "RatatuiRuby::Calendar" => widgets::calendar::render(frame, area, node)?,
         "RatatuiRuby::Sparkline" => widgets::sparkline::render(frame, area, node)?,
         "RatatuiRuby::Chart" | "RatatuiRuby::LineChart" => {
-            widgets::chart::render(frame, area, node)?
+            widgets::chart::render(frame, area, node)?;
+        }
+        "RatatuiRuby::RatatuiLogo" => widgets::ratatui_logo::render(frame, area, node),
+        "RatatuiRuby::RatatuiMascot" => {
+            widgets::ratatui_mascot::render_ratatui_mascot(frame, area, node)?;
         }
         _ => {}
     }
     Ok(())
 }
+
+fn process_draw_command(buffer: &mut Buffer, cmd: Value) -> Result<(), Error> {
+    let ruby = magnus::Ruby::get().unwrap();
+    // SAFETY: Immediate conversion to owned string avoids GC-unsafe borrowed reference.
+    let class_name = unsafe { cmd.class().name() }.into_owned();
+
+    match class_name.as_str() {
+        "RatatuiRuby::Draw::StringCmd" => {
+            let x: u16 = cmd.funcall("x", ())?;
+            let y: u16 = cmd.funcall("y", ())?;
+            let string: String = cmd.funcall("string", ())?;
+            let style_val: Value = cmd.funcall("style", ())?;
+            let style = parse_style(style_val)?;
+            buffer.set_string(x, y, string, style);
+        }
+        "RatatuiRuby::Draw::CellCmd" => {
+            let x: u16 = cmd.funcall("x", ())?;
+            let y: u16 = cmd.funcall("y", ())?;
+            let cell_val: Value = cmd.funcall("cell", ())?;
+
+            let area = buffer.area;
+            if x >= area.x + area.width || y >= area.y + area.height {
+                return Ok(());
+            }
+
+            let symbol: String = cell_val.funcall("char", ())?;
+            let fg_val: Value = cell_val.funcall("fg", ())?;
+            let bg_val: Value = cell_val.funcall("bg", ())?;
+            let modifiers_val: Value = cell_val.funcall("modifiers", ())?;
+
+            let mut style = Style::default();
+
+            if !fg_val.is_nil() {
+                if let Some(color) = parse_color_value(fg_val)? {
+                    style = style.fg(color);
+                }
+            }
+            if !bg_val.is_nil() {
+                if let Some(color) = parse_color_value(bg_val)? {
+                    style = style.bg(color);
+                }
+            }
+
+            if let Some(mods_array) = RArray::from_value(modifiers_val) {
+                for i in 0..mods_array.len() {
+                    let index = isize::try_from(i)
+                        .map_err(|e| Error::new(ruby.exception_range_error(), e.to_string()))?;
+                    let mod_str: String = mods_array.entry::<String>(index)?;
+                    if let Some(modifier) = parse_modifier_str(&mod_str) {
+                        style = style.add_modifier(modifier);
+                    }
+                }
+            }
+
+            if let Some(cell) = buffer.cell_mut((x, y)) {
+                cell.set_symbol(&symbol).set_style(style);
+            }
+        }
+        _ => {
+            return Err(Error::new(
+                ruby.exception_type_error(),
+                format!("Unknown draw command: {class_name}"),
+            ));
+        }
+    }
+
+    Ok(())
+}