tuile 0.4.0 → 0.5.0

data/lib/tuile/event_queue.rb

@@ -47,17 +47,56 @@ module Tuile
       latch.wait
     end
 
+    # Schedules `block` to fire on the event-loop thread roughly `fps` times
+    # per second, passing a 0-based monotonically increasing tick counter. Use
+    # it for animations (e.g. a `/-\|` spinner in a {Component::Label}) or
+    # periodic UI refresh from a background task.
+    #
+    # The returned {Ticker} controls the schedule — call {Ticker#cancel} to
+    # stop it.
+    #
+    # **Errors:** if `block` raises, the {Ticker} cancels itself and the
+    # exception flows through the normal event-loop error path — i.e.
+    # {Screen#on_error} for the default Tuile setup. Auto-cancel prevents a
+    # broken block from spamming `on_error` at the tick rate.
+    #
+    # Tickers reuse `concurrent-ruby`'s shared timer thread
+    # ({Concurrent}.global_timer_set) — adding more tickers does not add more
+    # threads, just more work on the shared scheduler.
+    #
+    # @param fps [Numeric] firings per second, must be positive. Fractional
+    #   values are fine (`fps: 0.5` ⇒ one tick every two seconds).
+    # @yield [tick] called on the event-loop thread each firing.
+    # @yieldparam tick [Integer] 0-based monotonically increasing counter.
+    # @yieldreturn [void]
+    # @return [Ticker]
+    def tick(fps, &block)
+      raise ArgumentError, "block required" unless block
+      unless fps.is_a?(Numeric) && fps.positive?
+        raise ArgumentError, "fps must be a positive Numeric, got #{fps.inspect}"
+      end
+
+      Ticker.new(self, fps, block)
+    end
+
     # Runs the event loop and blocks. Must be run from at most one thread at the
     # same time. Blocks until some thread calls {#stop}. Calls block for all
-    # events submitted via {#post}; the block is always called from the thread
-    # running this function.
+    # events; the block is always called from the thread running this function.
     #
-    # Any exception raised by block is re-thrown, causing this function to
-    # terminate.
-    # @yield [event] called for each non-internal event.
+    # Any exception raised by the block is re-thrown, causing this function to
+    # terminate. Wrap the block body in `rescue` if you want to handle errors
+    # without tearing down the loop — see {Screen#event_loop} for an example.
+    #
+    # **Procs are yielded too.** A {#submit}ed block arrives as a `Proc` event;
+    # the consumer is responsible for invoking it (typically `event.call`).
+    # Yielding rather than dispatching inline means a raise inside the
+    # submitted block flows through the consumer's `rescue` like any other
+    # event-handler error, instead of bypassing it.
+    # @yield [event] called for each posted event.
     # @yieldparam event [Object] a posted event — typically a {KeyEvent},
-    #   {MouseEvent}, {TTYSizeEvent}, {EmptyQueueEvent}, or any object pushed
-    #   via {#post}.
+    #   {MouseEvent}, {TTYSizeEvent}, {EmptyQueueEvent}, a `Proc` from {#submit},
+    #   or any object pushed via {#post}. {ErrorEvent}s are not yielded — they
+    #   terminate the loop directly.
     # @yieldreturn [void]
     # @return [void]
     def run_loop(&)
@@ -152,6 +191,64 @@ module Tuile
       include Singleton
     end
 
+    # Handle returned by {EventQueue#tick}. Cancel a running ticker via
+    # {#cancel}.
+    #
+    # Internally wraps a `Concurrent::TimerTask` whose firing posts a single
+    # submit-block to the owning {EventQueue}; the user's block therefore
+    # always runs on the event-loop thread and may freely mutate UI. If the
+    # user block raises, the Ticker auto-cancels and the exception is
+    # re-raised so it flows through the loop's normal error handling
+    # ({Screen#on_error} for the default Tuile setup).
+    class Ticker
+      # @param event_queue [EventQueue] queue to dispatch tick calls onto.
+      # @param fps [Numeric] firings per second (positive).
+      # @param block [Proc] called as `block.call(tick_count)` on each fire.
+      def initialize(event_queue, fps, block)
+        @event_queue = event_queue
+        @block = block
+        @tick = 0
+        # AtomicBoolean rather than a plain ivar: cancel may run on any
+        # thread (caller code, the event-loop thread from inside the block,
+        # or the IO executor on an error path), and we want both a CAS-style
+        # one-shot guard against double-shutdown and well-defined visibility
+        # on non-MRI Rubies.
+        @cancelled = Concurrent::AtomicBoolean.new(false)
+        @timer = Concurrent::TimerTask.new(execution_interval: 1.0 / fps) do
+          @event_queue.submit { fire }
+        end
+        @timer.execute
+      end
+
+      # @return [Boolean] true once {#cancel} has been called.
+      def cancelled? = @cancelled.true?
+
+      # Stops the ticker. Idempotent and safe to call from any thread,
+      # including from inside the tick block. Any tick already queued on the
+      # event loop at the moment of cancellation is dropped before the user
+      # block runs.
+      # @return [void]
+      def cancel
+        return unless @cancelled.make_true # CAS: only the winner shuts down
+
+        @timer.shutdown
+      end
+
+      private
+
+      # Runs on the event-loop thread.
+      # @return [void]
+      def fire
+        return if @cancelled.true?
+
+        @block.call(@tick)
+        @tick += 1
+      rescue StandardError
+        cancel
+        raise
+      end
+    end
+
     private
 
     # @return [void]
@@ -169,8 +266,6 @@ module Tuile
             # while the loop's own backtrace shows up in the wrapper.
             raise Tuile::Error, "background event raised: #{event.error.class}: #{event.error.message}"
           end
-        elsif event.is_a? Proc
-          event.call
         else
           yield event
         end

data/lib/tuile/fake_event_queue.rb

@@ -4,6 +4,10 @@ module Tuile
   # A "synchronous" event queue – no loop is run, submitted blocks are run right
   # away and submitted events are thrown away. Intended for testing only.
   class FakeEventQueue
+    def initialize
+      @tickers = []
+    end
+
     # @return [Boolean]
     def locked? = true
     # @return [void]
@@ -27,5 +31,70 @@ module Tuile
     # @param event [Object]
     # @return [void]
     def post(event); end
+
+    # Mirrors {EventQueue#tick} but timeless: returns a {FakeTicker} that
+    # only fires when a test calls {#tick_once}. The `fps` argument is
+    # validated the same way the real queue validates it, then discarded —
+    # the fake has no clock, so frame cadence is up to the test.
+    #
+    # @param fps [Numeric] firings per second, must be positive. Validated
+    #   for parity with {EventQueue#tick}; otherwise unused.
+    # @yield [tick] called on each {#tick_once}.
+    # @yieldparam tick [Integer] 0-based monotonically increasing counter.
+    # @yieldreturn [void]
+    # @return [FakeTicker]
+    def tick(fps, &block)
+      raise ArgumentError, "block required" unless block
+      unless fps.is_a?(Numeric) && fps.positive?
+        raise ArgumentError, "fps must be a positive Numeric, got #{fps.inspect}"
+      end
+
+      FakeTicker.new(block).tap { |t| @tickers << t }
+    end
+
+    # Test helper: fires every live ticker's user block once and prunes
+    # cancelled tickers. No-op when no tickers are registered. Pumps once
+    # per call regardless of any ticker's fps — the fake has no clock, so
+    # tests pump N frames by calling this N times.
+    # @return [void]
+    def tick_once
+      @tickers.reject!(&:cancelled?)
+      @tickers.each(&:fire)
+    end
+
+    # Handle returned by {FakeEventQueue#tick}. Mirrors the public surface of
+    # {EventQueue::Ticker} (`cancel`, `cancelled?`) but does not auto-fire —
+    # the host {FakeEventQueue} drives firing via {FakeEventQueue#tick_once}.
+    class FakeTicker
+      # @param block [Proc] called as `block.call(tick_count)` on each {#fire}.
+      def initialize(block)
+        @block = block
+        @tick = 0
+        @cancelled = false
+      end
+
+      # @return [Boolean] true once {#cancel} has been called.
+      def cancelled? = @cancelled
+
+      # Marks the ticker cancelled. Idempotent. Subsequent {#fire} calls are
+      # no-ops; {FakeEventQueue#tick_once} also prunes the ticker on its next
+      # pass.
+      # @return [void]
+      def cancel
+        @cancelled = true
+      end
+
+      # Invokes the user block with the current tick counter, then advances.
+      # No-op when {#cancelled?}. Typically driven by
+      # {FakeEventQueue#tick_once}; safe to call directly from a test that
+      # wants to drive a single ticker.
+      # @return [void]
+      def fire
+        return if @cancelled
+
+        @block.call(@tick)
+        @tick += 1
+      end
+    end
   end
 end

data/lib/tuile/screen.rb

@@ -598,6 +598,8 @@ module Tuile
           layout
         when EventQueue::EmptyQueueEvent
           repaint
+        when Proc
+          event.call
         end
       rescue StandardError => e
         @on_error.call(e)

data/lib/tuile/styled_string.rb

@@ -53,18 +53,16 @@ module Tuile
     # Raised by {.parse} on malformed or unsupported escape sequences.
     class ParseError < Error; end
 
-    # A frozen value type describing the visual style of a {Span}.
-    #
-    # `fg` and `bg` accept:
-    # - `nil` — the terminal default (SGR 39 / 49)
-    # - a symbol from {COLOR_SYMBOLS} — 8 standard + 8 bright ANSI colors
-    # - an Integer 0..255 — 256-color palette index (SGR 38;5;N / 48;5;N)
-    # - an `[r, g, b]` Array of three 0..255 Integers — 24-bit RGB
+    # A frozen value type describing the visual style of a {Span}. Colors are
+    # stored as {Color} instances (or `nil` for the terminal default); inputs
+    # to {.new} and {#merge} are coerced via {Color.coerce}, so the four
+    # accepted color forms — `nil`, Symbol, Integer 0..255, RGB Array — work
+    # transparently.
     #
     # @!attribute [r] fg
-    #   @return [Symbol, Integer, Array<Integer>, nil]
+    #   @return [Color, nil]
     # @!attribute [r] bg
-    #   @return [Symbol, Integer, Array<Integer>, nil]
+    #   @return [Color, nil]
     # @!attribute [r] bold
     #   @return [Boolean]
     # @!attribute [r] italic
@@ -72,42 +70,16 @@ module Tuile
     # @!attribute [r] underline
     #   @return [Boolean]
     class Style < Data.define(:fg, :bg, :bold, :italic, :underline)
-      # Symbolic color names recognized by {#fg} and {#bg}. Order is
-      # significant: indices 0..7 map to standard ANSI colors (SGR 30..37 fg
-      # / 40..47 bg); indices 8..15 map to bright variants (SGR 90..97 /
-      # 100..107).
-      # @return [Array<Symbol>]
-      COLOR_SYMBOLS = %i[
-        black red green yellow blue magenta cyan white
-        bright_black bright_red bright_green bright_yellow
-        bright_blue bright_magenta bright_cyan bright_white
-      ].freeze
-
-      # @param fg [Symbol, Integer, Array<Integer>, nil]
-      # @param bg [Symbol, Integer, Array<Integer>, nil]
+      # @param fg [Color, Symbol, Integer, Array<Integer>, nil] coerced via {Color.coerce}.
+      # @param bg [Color, Symbol, Integer, Array<Integer>, nil] coerced via {Color.coerce}.
       # @param bold [Boolean]
       # @param italic [Boolean]
       # @param underline [Boolean]
       # @return [Style]
       # @raise [ArgumentError] when a color is not one of the accepted forms.
       def self.new(fg: nil, bg: nil, bold: false, italic: false, underline: false)
-        validate_color!(fg, :fg)
-        validate_color!(bg, :bg)
-        super(fg:, bg:, bold:, italic:, underline:)
-      end
-
-      # @param color [Object]
-      # @param which [Symbol]
-      # @return [void]
-      def self.validate_color!(color, which)
-        return if color.nil? || COLOR_SYMBOLS.include?(color)
-        return if color.is_a?(Integer) && color.between?(0, 255)
-        return if color.is_a?(Array) && color.length == 3 &&
-                  color.all? { |v| v.is_a?(Integer) && v.between?(0, 255) }
-
-        raise ArgumentError, "invalid #{which} color: #{color.inspect}"
+        super(fg: Color.coerce(fg), bg: Color.coerce(bg), bold:, italic:, underline:)
       end
-      private_class_method :validate_color!
 
       # The style with no color and no attributes — what the terminal shows
       # without any SGR applied.
@@ -149,11 +121,11 @@ module Tuile
     # supported SGR alphabet raises {ParseError}.
     class Parser
       # @return [Array<Symbol>]
-      STANDARD_COLORS = Style::COLOR_SYMBOLS[0, 8].freeze
+      STANDARD_COLORS = Color::COLOR_SYMBOLS[0, 8].freeze
       private_constant :STANDARD_COLORS
 
       # @return [Array<Symbol>]
-      BRIGHT_COLORS = Style::COLOR_SYMBOLS[8, 8].freeze
+      BRIGHT_COLORS = Color::COLOR_SYMBOLS[8, 8].freeze
       private_constant :BRIGHT_COLORS
 
       # @param input [String]
@@ -487,9 +459,9 @@ module Tuile
     # `underline`). Useful for row-level highlights — the new bg overlays
     # without dropping foreground colors the original styling carried.
     #
-    # @param bg [Symbol, Integer, Array<Integer>, nil] background color, in
-    #   any of the forms accepted by {Style.new}. `nil` clears bg back to
-    #   the terminal default.
+    # @param bg [Color, Symbol, Integer, Array<Integer>, nil] background
+    #   color, coerced via {Color.coerce}. `nil` clears bg back to the
+    #   terminal default.
     # @return [StyledString]
     def with_bg(bg)
       self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(bg: bg)) })
@@ -500,9 +472,9 @@ module Tuile
     # `underline`). The new fg overlays without dropping background colors or
     # text attributes the original styling carried.
     #
-    # @param fg [Symbol, Integer, Array<Integer>, nil] foreground color, in
-    #   any of the forms accepted by {Style.new}. `nil` clears fg back to
-    #   the terminal default.
+    # @param fg [Color, Symbol, Integer, Array<Integer>, nil] foreground
+    #   color, coerced via {Color.coerce}. `nil` clears fg back to the
+    #   terminal default.
     # @return [StyledString]
     def with_fg(fg)
       self.class.new(@spans.map { |span| Span.new(text: span.text, style: span.style.merge(fg: fg)) })
@@ -556,26 +528,21 @@ module Tuile
       codes << (to.bold ? 1 : 22) if from.bold != to.bold
       codes << (to.italic ? 3 : 23) if from.italic != to.italic
       codes << (to.underline ? 4 : 24) if from.underline != to.underline
-      codes.concat(color_codes(to.fg, base: 30, ext: 38)) if from.fg != to.fg
-      codes.concat(color_codes(to.bg, base: 40, ext: 48)) if from.bg != to.bg
+      codes.concat(color_codes(to.fg, target: :fg)) if from.fg != to.fg
+      codes.concat(color_codes(to.bg, target: :bg)) if from.bg != to.bg
       return "" if codes.empty?
 
       "\e[#{codes.join(";")}m"
     end
 
-    # @param color [Symbol, Integer, Array<Integer>, nil]
-    # @param base [Integer] base SGR code — 30 for fg, 40 for bg.
-    # @param ext [Integer] extended-color SGR code — 38 for fg, 48 for bg.
-    # @return [Array<Integer>]
-    def color_codes(color, base:, ext:)
-      case color
-      when nil then [base + 9]
-      when Symbol
-        idx = Style::COLOR_SYMBOLS.index(color)
-        idx < 8 ? [base + idx] : [base + 60 + (idx - 8)]
-      when Integer then [ext, 5, color]
-      when Array then [ext, 2, *color]
-      end
+    # @param color [Color, nil]
+    # @param target [Symbol] `:fg` or `:bg`.
+    # @return [Array<Integer>] SGR codes; `[39]` / `[49]` for the "default" reset
+    #   when `color` is `nil`, otherwise delegated to {Color#sgr_codes}.
+    def color_codes(color, target:)
+      return [target == :fg ? 39 : 49] if color.nil?
+
+      color.sgr_codes(target)
     end
 
     # @param start_or_range [Integer, Range]

data/lib/tuile/version.rb

@@ -2,5 +2,5 @@
 
 module Tuile
   # @return [String]
-  VERSION = "0.4.0"
+  VERSION = "0.5.0"
 end