tuile 0.13.0 → 0.15.0

data/lib/tuile/event_queue.rb

@@ -247,6 +247,25 @@ module Tuile
       end
     end
 
+    # The terminal reported its background color — an OSC 11 reply, read
+    # back as a whole "key" by {Keys.getkey}.
+    #
+    # Only ever an answer to a {TerminalBackground::QUERY} someone wrote,
+    # and only the color: a {ColorSchemeEvent} is what prompts the re-probe
+    # and what carries the light/dark half. See {Screen#background_color}.
+    #
+    # @!attribute [r] color
+    #   @return [Color] the reported background, 24-bit RGB.
+    class BackgroundColorEvent < Data.define(:color)
+      # @param key [String] key read via {Keys.getkey}.
+      # @return [BackgroundColorEvent, nil] nil when `key` is not an OSC 11
+      #   background reply.
+      def self.parse(key)
+        result = TerminalBackground.parse(key)
+        result&.color && new(result.color)
+      end
+    end
+
     # Emitted once when the queue is cleared, all messages are processed and the
     # event loop will block waiting for more messages. Perfect time for
     # repainting windows.
@@ -344,7 +363,8 @@ module Tuile
           event = if key == Keys::PASTE_START
                     PasteEvent.new(Keys.read_paste)
                   else
-                    MouseEvent.parse(key) || ColorSchemeEvent.parse(key) || KeyEvent.new(key)
+                    MouseEvent.parse(key) || ColorSchemeEvent.parse(key) ||
+                      BackgroundColorEvent.parse(key) || KeyEvent.new(key)
                   end
           post event
         end

data/lib/tuile/fake_screen.rb

@@ -27,7 +27,9 @@ module Tuile
       super
       @event_queue = FakeEventQueue.new
       @size = Size.new(160, 50)
-      @buffer.resize(@size) # super sized it to the test runner's TTY
+      # super sized both to the test runner's TTY.
+      @buffer.resize(@size)
+      @pane.rect = Rect.new(0, 0, @size.width, @size.height)
       @prints = []
     end
 
@@ -81,12 +83,44 @@ module Tuile
       @invalidated.clear
     end
 
+    # Plays the terminal answering the OSC 11 re-probe, so a spec can
+    # exercise app code that derives colors from {#background_color}:
+    #
+    #   Screen.instance.background_color = Color.rgb(30, 30, 46)
+    #
+    # Takes the same path a real reply does — a changed color fires
+    # {Component#on_theme_changed} across the tree and invalidates it.
+    # There is no such writer on {Screen}: the value is a report from the
+    # terminal, not a setting.
+    # @param color [Color]
+    # @return [void]
+    def background_color=(color)
+      on_background_color(color)
+    end
+
     private
 
     # No terminal probing in tests: skip {TerminalBackground.detect}
     # (which would write an OSC 11 query to the test runner's TTY and
-    # steal its input) and pin the deterministic default.
+    # steal its input) and pin the deterministic default. The color is nil
+    # — the case every app must handle anyway — until a spec assigns one
+    # through {#background_color=}.
+    # @return [TerminalBackground::Result]
+    def detect_background = TerminalBackground::Result.new(scheme: :dark, color: nil)
+
+    # Pins the depth rather than reading the test runner's environment, so a
+    # spec asserting flushed bytes gets the same answer on a truecolor
+    # terminal, under `TERM=dumb` in CI, and inside tmux. A spec exercising
+    # degradation builds its own {Buffer} with the depth it wants.
     # @return [Symbol]
-    def detect_scheme = :dark
+    def detect_color_depth = :truecolor
+
+    # Pins the conventions instead of probing, so a spec asserting a painted
+    # date gets the same answer under `LC_TIME=en_DK` as under `LANG=C` — and
+    # so no example pays for a `locale(1)` subprocess. A spec exercising
+    # detection assigns {Screen#locale=} or calls {Locale.from_keywords} with
+    # canned answers.
+    # @return [Locale]
+    def detect_locale = Locale::ISO
   end
 end

data/lib/tuile/final.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Tuile
+  # Ruby's missing `final` keyword. A class `extend`s this, marks the methods a
+  # subclass may not redefine, and calls {#verify_final!} from its own
+  # `initialize`:
+  #
+  #   class Component
+  #     extend Final
+  #
+  #     final :children, :parent, :add_child
+  #
+  #     def initialize = Component.verify_final!(self.class)
+  #   end
+  #
+  #   Class.new(Component) { def children = [] }.new   # => Tuile::Error
+  #
+  # Marking a method says only *that* it is final. **Why** — the invariant an
+  # override would break, and the seam to use instead — belongs in that
+  # method's own rdoc, which is where the raise sends the reader.
+  #
+  # == Implementation details
+  #
+  # The check resolves each final method's `owner` instead of hooking
+  # `method_added`, which fires earlier but sees only `def` and
+  # `define_method` — an override arriving through an `include` or a `prepend`
+  # slips past it. Nothing fires late enough to place the check automatically,
+  # which is why the extending class owes the explicit {#verify_final!} call.
+  module Final
+    # Marks each of `names` non-overridable by subclasses. Declare them in one
+    # call near the top of the class; the names may be forward references,
+    # since nothing is resolved until {#verify_final!} runs.
+    #
+    #   final :parent, :children, :add_child
+    #
+    # It *reads* better as a keyword on the definition (`final def foo`, which
+    # parses — `def` hands back its name), but don't: YARD has no handler for
+    # the macro, so a decorated `def` loses its parameter list and sord then
+    # generates `def foo: () -> void` into `sig/`, silently.
+    #
+    # @param names [Array<Symbol, Array<Symbol>>] method names.
+    # @return [Symbol, Array<Symbol>] the names — a bare Symbol when exactly
+    #   one was given.
+    def final(*names)
+      names = names.flatten
+      (@final_methods ||= []).concat(names)
+      names.one? ? names.first : names
+    end
+
+    # @return [Array<Symbol>] the methods marked {#final} on this class.
+    def final_methods = @final_methods || []
+
+    # Raises unless `klass` inherits every {#final_methods} entry from this
+    # class. Memoized per class, so a construction-time call costs one hash
+    # lookup after the first instance.
+    #
+    # @param klass [Class] the class being instantiated.
+    # @raise [Error] if `klass` redefines a final method, by any route.
+    # @return [void]
+    def verify_final!(klass)
+      @final_verified ||= {}
+      return if @final_verified.key?(klass)
+
+      overridden = final_methods.reject { klass.instance_method(_1).owner == self }
+      unless overridden.empty?
+        raise Error, "#{klass} overrides #{overridden.join(", ")}, which #{overridden.one? ? "is" : "are"} final " \
+                     "on #{self} and may not be redefined. See the rdoc of " \
+                     "#{overridden.map { "#{self}##{_1}" }.join(", ")} for the invariant at stake and the seam " \
+                     "to use instead."
+      end
+
+      @final_verified[klass] = true
+    end
+  end
+end

data/lib/tuile/keys.rb

@@ -184,6 +184,13 @@ module Tuile
       # sequences never start with `\e[?`, so this can't eat a regular key.
       char += $stdin.read(1) while char.start_with?("\e[?") && !char.match?(/[\x40-\x7e]\z/)
 
+      # OSC replies (the ~22-byte background report, {TerminalBackground})
+      # outgrow the gulp too, and end in BEL or ST rather than at a fixed
+      # length. Byte-at-a-time is required, not merely tidy: ST *is* `\e\\`,
+      # so a gulping read would swallow it plus the keys typed behind it.
+      # Keyboard sequences never start with `\e]`, so this eats no real key.
+      char += $stdin.read(1) while char.start_with?("\e]") && !char.end_with?("\a", "\e\\")
+
       char
     end