ratatui_ruby 1.2.2 → 1.3.0

data/ext/ratatui_ruby/Cargo.toml

@@ -3,7 +3,7 @@
 
 [package]
 name = "ratatui_ruby"
-version = "1.2.2"
+version = "1.3.0"
 edition = "2021"
 
 [lib]
@@ -11,7 +11,6 @@ crate-type = ["cdylib", "staticlib"]
 
 [dependencies]
 magnus = "0.8.2"
-rb-sys = "*"
 ratatui = { version = "0.30", features = ["widget-calendar", "layout-cache", "unstable-rendered-line-info", "palette"] }
 unicode-width = "0.1"
 

data/ext/ratatui_ruby/src/events.rs

@@ -2,9 +2,7 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 use magnus::{Error, IntoValue, TryConvert, Value};
-use rb_sys::rb_thread_call_without_gvl;
 use std::cell::RefCell;
-use std::os::raw::c_void;
 
 /// Wrapper enum for test events - includes crossterm events and our Sync event.
 #[derive(Debug, Clone)]
@@ -316,92 +314,6 @@ pub fn clear_events() {
     EVENT_QUEUE.with(|q| q.borrow_mut().clear());
 }
 
-/// Result of polling crossterm from outside the GVL.
-///
-/// The blocking I/O (poll + read) happens without the Ruby GVL held,
-/// so other Ruby threads can run concurrently. This enum carries the
-/// result back across the GVL boundary for Ruby object construction.
-#[derive(Debug)]
-enum PollResult {
-    /// A crossterm event was read successfully.
-    Event(ratatui::crossterm::event::Event),
-    /// The timeout expired with no event available.
-    NoEvent,
-    /// An I/O error occurred during poll or read.
-    Error(String),
-}
-
-/// Data passed to the GVL-free polling callback.
-///
-/// The `timeout` field controls the poll behavior:
-/// - `Some(duration)`: poll with a timeout, return `NoEvent` if it expires.
-/// - `None`: block indefinitely until an event arrives.
-struct PollData {
-    timeout: Option<std::time::Duration>,
-    result: PollResult,
-}
-
-/// Polls crossterm for events without the Ruby GVL held.
-///
-/// This is the work function passed to `rb_thread_call_without_gvl`.
-/// It performs blocking I/O that would otherwise starve Ruby threads.
-extern "C" fn poll_without_gvl(data: *mut c_void) -> *mut c_void {
-    // SAFETY: `data` is a valid pointer to `PollData`, passed by
-    // `poll_crossterm_without_gvl` via `rb_thread_call_without_gvl`. The
-    // pointer remains valid for the duration of this callback because the
-    // caller owns the `PollData` on the stack and waits for us to return.
-    let data = unsafe { &mut *data.cast::<PollData>() };
-
-    data.result = match data.timeout {
-        Some(duration) => match ratatui::crossterm::event::poll(duration) {
-            Ok(true) => match ratatui::crossterm::event::read() {
-                Ok(event) => PollResult::Event(event),
-                Err(e) => PollResult::Error(e.to_string()),
-            },
-            Ok(false) => PollResult::NoEvent,
-            Err(e) => PollResult::Error(e.to_string()),
-        },
-        None => match ratatui::crossterm::event::read() {
-            Ok(event) => PollResult::Event(event),
-            Err(e) => PollResult::Error(e.to_string()),
-        },
-    };
-
-    std::ptr::null_mut()
-}
-
-/// Polls crossterm with the GVL released, then converts the result
-/// to a Ruby value after reacquiring the GVL.
-fn poll_crossterm_without_gvl(
-    ruby: &magnus::Ruby,
-    timeout: Option<std::time::Duration>,
-) -> Result<Value, Error> {
-    let mut data = PollData {
-        timeout,
-        result: PollResult::NoEvent,
-    };
-
-    // SAFETY: `data` is a valid stack-local `PollData` whose lifetime
-    // spans this entire call. `poll_without_gvl` only reads/writes
-    // through the pointer while `rb_thread_call_without_gvl` blocks,
-    // and we don't access `data` again until that function returns.
-    unsafe {
-        rb_thread_call_without_gvl(
-            Some(poll_without_gvl),
-            (&raw mut data).cast::<c_void>(),
-            None,
-            std::ptr::null_mut(),
-        );
-    }
-
-    // GVL is now re-held — safe to create Ruby objects.
-    match data.result {
-        PollResult::Event(event) => handle_crossterm_event(event),
-        PollResult::NoEvent => Ok(ruby.qnil().into_value_with(ruby)),
-        PollResult::Error(msg) => Err(Error::new(ruby.exception_runtime_error(), msg)),
-    }
-}
-
 pub fn poll_event(ruby: &magnus::Ruby, timeout_val: Option<f64>) -> Result<Value, Error> {
     let event = EVENT_QUEUE.with(|q| {
         let mut queue = q.borrow_mut();
@@ -422,8 +334,24 @@ pub fn poll_event(ruby: &magnus::Ruby, timeout_val: Option<f64>) -> Result<Value
         return Ok(ruby.qnil().into_value_with(ruby));
     }
 
-    let timeout = timeout_val.map(std::time::Duration::from_secs_f64);
-    poll_crossterm_without_gvl(ruby, timeout)
+    if let Some(secs) = timeout_val {
+        // Timed poll: wait up to the specified duration
+        let duration = std::time::Duration::from_secs_f64(secs);
+        if ratatui::crossterm::event::poll(duration)
+            .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?
+        {
+            let event = ratatui::crossterm::event::read()
+                .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
+            handle_crossterm_event(event)
+        } else {
+            Ok(ruby.qnil().into_value_with(ruby))
+        }
+    } else {
+        // Blocking: wait indefinitely for an event
+        let event = ratatui::crossterm::event::read()
+            .map_err(|e| Error::new(ruby.exception_runtime_error(), e.to_string()))?;
+        handle_crossterm_event(event)
+    }
 }
 
 fn handle_test_event(event: TestEvent) -> Result<Value, Error> {
@@ -631,70 +559,3 @@ fn handle_focus_event(event_type: &str) -> Result<Value, Error> {
     hash.aset(ruby.to_symbol("type"), ruby.to_symbol(event_type))?;
     Ok(hash.into_value_with(&ruby))
 }
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-
-    #[test]
-    fn poll_data_defaults_to_no_event() {
-        let data = PollData {
-            timeout: Some(std::time::Duration::from_millis(0)),
-            result: PollResult::NoEvent,
-        };
-        assert!(matches!(data.result, PollResult::NoEvent));
-    }
-
-    #[test]
-    fn poll_data_accepts_none_timeout_for_indefinite_blocking() {
-        let data = PollData {
-            timeout: None,
-            result: PollResult::NoEvent,
-        };
-        assert!(data.timeout.is_none());
-    }
-
-    #[test]
-    fn poll_result_error_preserves_message() {
-        let result = PollResult::Error("connection reset".to_string());
-        match result {
-            PollResult::Error(msg) => assert_eq!(msg, "connection reset"),
-            _ => panic!("Expected PollResult::Error"),
-        }
-    }
-
-    #[test]
-    fn poll_result_event_wraps_crossterm_event() {
-        let key_event =
-            ratatui::crossterm::event::Event::Key(ratatui::crossterm::event::KeyEvent::new(
-                ratatui::crossterm::event::KeyCode::Char('q'),
-                ratatui::crossterm::event::KeyModifiers::empty(),
-            ));
-        let result = PollResult::Event(key_event.clone());
-        match result {
-            PollResult::Event(e) => assert_eq!(format!("{e:?}"), format!("{key_event:?}")),
-            _ => panic!("Expected PollResult::Event"),
-        }
-    }
-
-    #[test]
-    fn poll_without_gvl_returns_no_event_on_zero_timeout() {
-        // With a zero-duration timeout, poll returns immediately with no event.
-        // In headless environments (CI), crossterm may return an Error because
-        // there is no terminal to read from — that's also a valid outcome.
-        let mut data = PollData {
-            timeout: Some(std::time::Duration::from_millis(0)),
-            result: PollResult::Error("sentinel — should be overwritten".to_string()),
-        };
-
-        poll_without_gvl(&mut data as *mut PollData as *mut c_void);
-
-        // The callback must have overwritten the sentinel value.
-        match &data.result {
-            PollResult::Error(msg) if msg == "sentinel — should be overwritten" => {
-                panic!("poll_without_gvl did not write to data.result")
-            }
-            _ => {} // NoEvent, Event, or a *different* Error are all fine.
-        }
-    }
-}

data/lib/ratatui_ruby/event/focus_gained.rb

@@ -70,6 +70,56 @@ module RatatuiRuby
       def ==(other)
         other.is_a?(FocusGained)
       end
+
+      # =========================================================================
+      # DWIM Predicates
+      # =========================================================================
+
+      # Returns true. The terminal window is now in focus.
+      #
+      #   event.focus? # => true
+      def focus?
+        true
+      end
+      alias focused? focus?
+
+      # Returns true. The application gained focus.
+      #
+      #   event.gained? # => true
+      def gained?
+        true
+      end
+
+      # Returns false. This is not a focus lost event.
+      #
+      #   event.lost? # => false
+      def lost?
+        false
+      end
+
+      # Returns false. Blur is the opposite of focus gained.
+      #
+      #   event.blur? # => false
+      def blur?
+        false
+      end
+      alias blurred? blur?
+
+      # Returns true. The application is active.
+      #
+      #   event.active? # => true
+      def active?
+        true
+      end
+      alias foreground? active?
+
+      # Returns false. The application is not inactive.
+      #
+      #   event.inactive? # => false
+      def inactive?
+        false
+      end
+      alias background? inactive?
     end
   end
 end

data/lib/ratatui_ruby/event/focus_lost.rb

@@ -71,6 +71,57 @@ module RatatuiRuby
       def ==(other)
         other.is_a?(FocusLost)
       end
+
+      # =========================================================================
+      # DWIM Predicates
+      # =========================================================================
+
+      # Returns true. The terminal has lost focus (blur).
+      #
+      #   event.blur? # => true
+      def blur?
+        true
+      end
+      alias blurred? blur?
+
+      # Returns true. The application lost focus.
+      #
+      #   event.lost? # => true
+      def lost?
+        true
+      end
+      alias unfocused? lost?
+
+      # Returns false. This is not a focus gained event.
+      #
+      #   event.focus? # => false
+      def focus?
+        false
+      end
+      alias focused? focus?
+
+      # Returns false. This is not a gained event.
+      #
+      #   event.gained? # => false
+      def gained?
+        false
+      end
+
+      # Returns true. The application is inactive.
+      #
+      #   event.inactive? # => true
+      def inactive?
+        true
+      end
+      alias background? inactive?
+
+      # Returns false. The application is not active.
+      #
+      #   event.active? # => false
+      def active?
+        false
+      end
+      alias foreground? active?
     end
   end
 end

data/lib/ratatui_ruby/event/key/dwim.rb

@@ -0,0 +1,301 @@
+# frozen_string_literal: true
+
+#--
+# SPDX-FileCopyrightText: 2026 Kerrick Long <me@kerricklong.com>
+# SPDX-License-Identifier: LGPL-3.0-or-later
+#++
+
+module RatatuiRuby
+  class Event
+    class Key < Event
+      # DWIM predicates for common key patterns.
+      #
+      # These predicates anticipate what developers intuitively try. Space bars,
+      # character categories, Unix signals, and Vim-style navigation.
+      module Dwim
+        # Returns true if the key is a space character.
+        #
+        #   event.space? # => true for " "
+        def space?
+          @code == " " && @modifiers.empty?
+        end
+
+        alias spacebar? space?
+
+        # Returns true if the key is Enter. Alias for carriage return.
+        #
+        #   event.cr? # => true for enter
+        def cr?
+          @code == "enter" && @modifiers.empty?
+        end
+
+        alias carriagereturn? cr?
+        alias linefeed? cr?
+        alias newline? cr?
+        alias lf? cr?
+
+        # Returns true if the key is a single letter (a-z, A-Z).
+        #
+        #   Event::Key.new(code: "a").letter? # => true
+        def letter?
+          @code.length == 1 && @code.match?(/\A[A-Za-z]\z/)
+        end
+
+        # Returns true if the key is a digit (0-9).
+        #
+        #   Event::Key.new(code: "5").digit? # => true
+        def digit?
+          @code.length == 1 && @code.match?(/\A[0-9]\z/)
+        end
+
+        # Returns true if the key is alphanumeric.
+        #
+        #   Event::Key.new(code: "a").alphanumeric? # => true
+        def alphanumeric?
+          letter? || digit?
+        end
+
+        # Returns true if the key is punctuation.
+        #
+        #   Event::Key.new(code: "@", modifiers: ["shift"]).punctuation? # => true
+        def punctuation?
+          return false unless @code.length == 1
+          !letter? && !digit? && !whitespace?
+        end
+
+        # Returns true if the key is whitespace (space, enter, tab).
+        #
+        #   Event::Key.new(code: " ").whitespace? # => true
+        def whitespace?
+          @code == " " || @code == "enter" || @code == "tab"
+        end
+
+        # Returns true for interrupt (Ctrl+C).
+        #
+        #   event.interrupt? # => true for Ctrl+C
+        def interrupt?
+          @code == "c" && @modifiers == ["ctrl"]
+        end
+
+        # Returns true for end-of-file (Ctrl+D).
+        #
+        #   event.eof? # => true for Ctrl+D
+        def eof?
+          @code == "d" && @modifiers == ["ctrl"]
+        end
+
+        # Returns true for cancel (Esc or Ctrl+C).
+        #
+        #   event.cancel? # => true for Esc or Ctrl+C
+        def cancel?
+          (@code == "esc" && @modifiers.empty?) || interrupt?
+        end
+
+        # Returns true for SIGINT (Ctrl+C).
+        #
+        #   event.sigint? # => true for Ctrl+C
+        def sigint?
+          interrupt?
+        end
+
+        alias int? sigint?
+
+        # Returns true for SIGTSTP (Ctrl+Z) - suspend/stop.
+        #
+        #   event.suspend? # => true for Ctrl+Z
+        def suspend?
+          @code == "z" && @modifiers == ["ctrl"]
+        end
+
+        alias sigtstp? suspend?
+        alias tstp? suspend?
+
+        # Returns true for SIGQUIT (Ctrl+\).
+        #
+        #   event.quit? # => true for Ctrl+\
+        def quit?
+          @code == "\\" && @modifiers == ["ctrl"]
+        end
+
+        alias sigquit? quit?
+
+        NAVIGATION_KEYS = %w[up down left right home end page_up page_down].freeze # :nodoc:
+
+        # Returns true if key is a navigation key.
+        #
+        #   Event::Key.new(code: "up").navigation? # => true
+        def navigation?
+          NAVIGATION_KEYS.include?(@code) && @modifiers.empty?
+        end
+
+        ARROW_KEYS = %w[up down left right].freeze # :nodoc:
+
+        # Returns true if key is an arrow key.
+        #
+        #   Event::Key.new(code: "up").arrow? # => true
+        def arrow?
+          ARROW_KEYS.include?(@code) && @modifiers.empty?
+        end
+
+        VIM_MOVEMENT_KEYS = %w[h j k l w b g G].freeze # :nodoc:
+
+        # Returns true if key is a Vim movement key.
+        #
+        #   Event::Key.new(code: "j").vim? # => true
+        def vim?
+          return true if VIM_MOVEMENT_KEYS.include?(@code) && @modifiers.empty?
+          @code == "G" && @modifiers == ["shift"]
+        end
+
+        # Returns true for Vim left (h).
+        def vim_left?
+          @code == "h" && @modifiers.empty?
+        end
+
+        # Returns true for Vim down (j).
+        def vim_down?
+          @code == "j" && @modifiers.empty?
+        end
+
+        # Returns true for Vim up (k).
+        def vim_up?
+          @code == "k" && @modifiers.empty?
+        end
+
+        # Returns true for Vim right (l).
+        def vim_right?
+          @code == "l" && @modifiers.empty?
+        end
+
+        # Returns true for Vim word forward (w).
+        def vim_word_forward?
+          @code == "w" && @modifiers.empty?
+        end
+
+        # Returns true for Vim word backward (b).
+        def vim_word_backward?
+          @code == "b" && @modifiers.empty?
+        end
+
+        # Returns true for Vim go to top (gg pattern, here just g).
+        def vim_top?
+          @code == "g" && @modifiers.empty?
+        end
+
+        # Returns true for Vim go to bottom (G).
+        def vim_bottom?
+          @code == "G" && @modifiers == ["shift"]
+        end
+
+        # Punctuation name predicates - generated at load time for performance.
+        # Maps intuitive names to their symbol characters.
+        # :nodoc:
+        PUNCTUATION_NAMES = {
+          # Navigation shortcuts (the original use case!)
+          tilde: "~",
+          slash: "/",
+          forwardslash: "/",
+          backslash: "\\",
+
+          # Common punctuation
+          comma: ",",
+          period: ".",
+          dot: ".",
+          colon: ":",
+          semicolon: ";",
+
+          # Question and exclamation
+          question: "?",
+          questionmark: "?",
+          exclamation: "!",
+          exclamationmark: "!",
+          exclamationpoint: "!",
+          bang: "!",
+
+          # Programming symbols
+          at: "@",
+          atsign: "@",
+          hash: "#",
+          pound: "#",
+          numbersign: "#",
+          dollar: "$",
+          dollarsign: "$",
+          percent: "%",
+          caret: "^",
+          circumflex: "^",
+          ampersand: "&",
+          asterisk: "*",
+          star: "*",
+
+          # Arithmetic and comparison
+          underscore: "_",
+          hyphen: "-",
+          dash: "-",
+          minus: "-",
+          plus: "+",
+          equals: "=",
+          equalsign: "=",
+          pipe: "|",
+          bar: "|",
+          lessthan: "<",
+          lt: "<",
+          greaterthan: ">",
+          gt: ">",
+
+          # Brackets and parens
+          lparen: "(",
+          leftparen: "(",
+          openparen: "(",
+          leftparenthesis: "(",
+          openparenthesis: "(",
+          rparen: ")",
+          rightparen: ")",
+          closeparen: ")",
+          rightparenthesis: ")",
+          closeparenthesis: ")",
+          lbracket: "[",
+          leftbracket: "[",
+          openbracket: "[",
+          leftsquarebracket: "[",
+          opensquarebracket: "[",
+          rbracket: "]",
+          rightbracket: "]",
+          closebracket: "]",
+          rightsquarebracket: "]",
+          closesquarebracket: "]",
+          lbrace: "{",
+          leftbrace: "{",
+          openbrace: "{",
+          leftcurlybrace: "{",
+          opencurlybrace: "{",
+          rbrace: "}",
+          rightbrace: "}",
+          closebrace: "}",
+          rightcurlybrace: "}",
+          closecurlybrace: "}",
+
+          # Quotes
+          backtick: "`",
+          grave: "`",
+          singlequote: "'",
+          apostrophe: "'",
+          doublequote: "\"",
+        }.freeze
+
+        # Generate predicate methods at load time (faster than method_missing)
+        PUNCTUATION_NAMES.each do |name, char|
+          class_eval <<~RUBY, __FILE__, __LINE__ + 1
+            def #{name}?
+              @code == #{char.inspect}
+            end
+          RUBY
+        end
+
+        # quote? matches both single and double quotes
+        def quote?
+          @code == "'" || @code == "\""
+        end
+      end
+    end
+  end
+end

data/lib/ratatui_ruby/event/key/modifier.rb

@@ -40,6 +40,8 @@ module RatatuiRuby
         # Alias for {#super?}.
         alias win? super?
         # Alias for {#super?}.
+        alias windows? super?
+        # Alias for {#super?}.
         alias command? super?
         # Alias for {#super?}.
         alias cmd? super?

data/lib/ratatui_ruby/event/key.rb

@@ -6,6 +6,7 @@
 #++
 
 require_relative "key/character"
+require_relative "key/dwim"
 require_relative "key/media"
 require_relative "key/modifier"
 require_relative "key/navigation"
@@ -88,6 +89,7 @@ module RatatuiRuby
     # These keys will not work in Terminal.app, iTerm2, or GNOME Terminal.
     class Key < Event
       include Character
+      include Dwim
       include Media
       include Modifier
       include Navigation
@@ -435,6 +437,13 @@ module RatatuiRuby
           normalized_code = @code.delete("_")
           return true if normalized_predicate == normalized_code && @modifiers.empty?
 
+          # DWIM: Underscore variants delegate to existing methods
+          # space_bar? → spacebar? → space?, sig_int? → sigint?
+          normalized_method = :"#{normalized_predicate}?"
+          if normalized_method != name && respond_to?(normalized_method)
+            return public_send(normalized_method)
+          end
+
           false
         else
           super