rubytui 1.2.3 → 1.2.5

data/lib/rubytui/gif.rb

@@ -0,0 +1,290 @@
+# frozen_string_literal: true
+
+module RubyTUI
+  # Pure-Ruby GIF decoder (GIF87a / GIF89a).
+  #
+  # Decodes every frame and composites it onto the logical screen, following
+  # each frame's disposal method, so every returned frame is a complete image.
+  # The canvas starts fully transparent (the logical-screen background colour
+  # is ignored), "restore to background" clears to transparent, and "restore to
+  # previous" restores the canvas as it was before the frame was drawn.
+  # Used by {Widgets::Image} to display GIFs through the Kitty graphics
+  # protocol, which only accepts RGB, RGBA or PNG data.
+  #
+  # @example
+  #   anim = RubyTUI::GIF.decode(File.binread("spinner.gif"))
+  #   anim.width        # => 32
+  #   anim.frames.size  # => 12
+  #   anim.delays       # => [100, 100, ...]  (milliseconds)
+  #   anim.loops        # => 0  (loop forever)
+  module GIF
+    # Decoded GIF.
+    #
+    # @!attribute [r] width
+    #   @return [Integer] logical screen width in pixels
+    # @!attribute [r] height
+    #   @return [Integer] logical screen height in pixels
+    # @!attribute [r] frames
+    #   @return [Array<String>] one RGBA string (4 bytes per pixel) per frame
+    # @!attribute [r] delays
+    #   @return [Array<Integer>] display time of each frame in milliseconds
+    # @!attribute [r] loops
+    #   @return [Integer, nil] NETSCAPE2.0 loop count: +0+ loops forever, +n+
+    #     repeats the animation +n+ more times, +nil+ (no loop extension) plays once
+    Animation = Struct.new(:width, :height, :frames, :delays, :loops)
+
+    # Largest accepted logical screen width or height, in pixels.
+    MAX_DIMENSION = 4096
+
+    # Largest accepted total decoded size (all frames, RGBA), in bytes.
+    MAX_DECODED_BYTES = 256 * 1024 * 1024
+
+    # Delay used for frames that declare less than 20 ms (the common browser convention).
+    MIN_DELAY_FALLBACK_MS = 100
+
+    # Rows of an interlaced image, in the order they are stored: every 8th row
+    # from 0, every 8th from 4, every 4th from 2, every 2nd from 1.
+    INTERLACE_PASSES = [[0, 8], [4, 8], [2, 4], [1, 2]].freeze
+    private_constant :INTERLACE_PASSES
+
+    # Fully transparent RGBA pixel.
+    TRANSPARENT = "\x00\x00\x00\x00".b.freeze
+    private_constant :TRANSPARENT
+
+    class << self
+      # Decode GIF data.
+      #
+      # @param data [String] raw GIF bytes
+      # @return [Animation]
+      # @raise [ArgumentError] if the data is not a GIF, is truncated or corrupt,
+      #   or exceeds {MAX_DIMENSION} / {MAX_DECODED_BYTES}
+      def decode(data)
+        Decoder.new(data.b).decode
+      end
+    end
+
+    # Stateful single-use decoder behind {GIF.decode}.
+    # @api private
+    class Decoder
+      # @param data [String] raw GIF bytes (binary)
+      def initialize(data)
+        @data = data
+        @pos = 0
+      end
+
+      # @return [Animation]
+      # @raise [ArgumentError] on invalid or oversized data
+      def decode
+        signature = read(6)
+        raise ArgumentError, "Invalid GIF data: bad signature" unless %w[GIF87a GIF89a].include?(signature)
+
+        @width, @height, packed, _bg, _aspect = read(7).unpack("vvCCC")
+        if @width.zero? || @height.zero? || @width > MAX_DIMENSION || @height > MAX_DIMENSION
+          raise ArgumentError, "Invalid GIF data: unsupported size #{@width}x#{@height} " \
+                               "(1..#{MAX_DIMENSION} pixels per side)"
+        end
+        @global_palette = packed & 0x80 != 0 ? read_palette(packed & 0x07) : nil
+
+        @canvas = TRANSPARENT * (@width * @height)
+        @frames = []
+        @delays = []
+        @loops = nil
+        @gce = nil
+
+        loop do
+          case read_byte
+          when 0x21 then read_extension
+          when 0x2C then read_image
+          when 0x3B then break
+          else raise ArgumentError, "Invalid GIF data: unexpected block at byte #{@pos - 1}"
+          end
+        end
+
+        raise ArgumentError, "Invalid GIF data: no image frames" if @frames.empty?
+
+        Animation.new(@width, @height, @frames, @delays, @loops)
+      end
+
+      private
+
+      def read(n)
+        bytes = @data.byteslice(@pos, n)
+        raise ArgumentError, "Invalid GIF data: truncated" if bytes.nil? || bytes.bytesize < n
+
+        @pos += n
+        bytes
+      end
+
+      def read_byte
+        read(1).getbyte(0)
+      end
+
+      # Concatenated data sub-blocks up to the block terminator.
+      def read_sub_blocks
+        out = String.new(encoding: Encoding::BINARY)
+        while (size = read_byte) != 0
+          out << read(size)
+        end
+        out
+      end
+
+      # Palette of 2**(bits + 1) entries, each a 4-byte opaque RGBA string.
+      def read_palette(bits)
+        read(3 * (2 << bits)).unpack("C*").each_slice(3).map { |r, g, b| [r, g, b, 255].pack("C4") }
+      end
+
+      def read_extension
+        label = read_byte
+        body = read_sub_blocks
+        case label
+        when 0xF9 # Graphic Control Extension
+          packed, delay, transparent = body.unpack("CvC")
+          @gce = {
+            disposal: (packed >> 2) & 0x07,
+            delay: delay,
+            transparent: packed & 0x01 != 0 ? transparent : nil
+          }
+        when 0xFF # Application Extension: NETSCAPE2.0 loop count
+          if body.start_with?("NETSCAPE2.0", "ANIMEXTS1.0") && body.getbyte(11) == 1
+            @loops = body.byteslice(12, 2).unpack1("v")
+          end
+        end
+      end
+
+      def read_image
+        left, top, w, h, packed = read(9).unpack("vvvvC")
+        palette = packed & 0x80 != 0 ? read_palette(packed & 0x07) : @global_palette
+        raise ArgumentError, "Invalid GIF data: frame has no colour table" unless palette
+
+        interlaced = packed & 0x40 != 0
+        min_code_size = read_byte
+        raise ArgumentError, "Invalid GIF data: bad LZW code size #{min_code_size}" unless (1..8).cover?(min_code_size)
+
+        indices = lzw_decode(read_sub_blocks, min_code_size, w * h)
+        indices = deinterlace(indices, w, h) if interlaced
+
+        if (@frames.size + 1) * @canvas.bytesize > MAX_DECODED_BYTES
+          raise ArgumentError, "GIF too large: decoded frames exceed #{MAX_DECODED_BYTES / (1024 * 1024)} MB"
+        end
+
+        gce = @gce || {}
+        @gce = nil
+        disposal = gce[:disposal] || 0
+        saved = @canvas.dup if disposal == 3
+
+        draw(indices, palette, gce[:transparent], left, top, w, h)
+        @frames << @canvas.dup
+        delay_ms = (gce[:delay] || 0) * 10
+        @delays << (delay_ms < 20 ? MIN_DELAY_FALLBACK_MS : delay_ms)
+
+        case disposal
+        when 2 then clear_rect(left, top, w, h)
+        when 3 then @canvas = saved
+        end
+      end
+
+      # LZW decompression (variable code size, max 12 bits) into palette indices.
+      def lzw_decode(data, min_code_size, pixel_count)
+        clear = 1 << min_code_size
+        eoi = clear + 1
+        base = Array.new(clear) { |i| i.chr(Encoding::BINARY) } + [nil, nil]
+        dict = base.dup
+        code_size = min_code_size + 1
+        out = String.new(capacity: pixel_count, encoding: Encoding::BINARY)
+        prev = nil
+        bits = 0
+        nbits = 0
+
+        data.each_byte do |byte|
+          bits |= byte << nbits
+          nbits += 8
+          while nbits >= code_size
+            code = bits & ((1 << code_size) - 1)
+            bits >>= code_size
+            nbits -= code_size
+
+            if code == clear
+              dict = base.dup
+              code_size = min_code_size + 1
+              prev = nil
+              next
+            end
+            return out if code == eoi
+
+            if prev.nil?
+              entry = dict[code]
+              raise ArgumentError, "Invalid GIF data: bad LZW code" unless entry
+            elsif code < dict.size
+              entry = dict[code]
+              dict << prev + entry[0] if dict.size < 4096
+            elsif code == dict.size
+              entry = prev + prev[0]
+              dict << entry if dict.size < 4096
+            else
+              raise ArgumentError, "Invalid GIF data: bad LZW code"
+            end
+
+            out << entry
+            return out if out.bytesize >= pixel_count
+
+            prev = entry
+            code_size += 1 if dict.size == (1 << code_size) && code_size < 12
+          end
+        end
+        out
+      end
+
+      # Reorder interlaced rows into top-to-bottom order.
+      def deinterlace(indices, w, h)
+        rows = Array.new(h)
+        n = 0
+        INTERLACE_PASSES.each do |start, step|
+          start.step(h - 1, step) do |y|
+            rows[y] = indices.byteslice(n * w, w)
+            n += 1
+          end
+        end
+        rows.join
+      end
+
+      # Composite one frame's pixels onto the canvas, clipped to the screen.
+      def draw(indices, palette, transparent, left, top, w, h)
+        x_end = [left + w, @width].min
+        return if left >= x_end
+
+        visible = x_end - left
+        h.times do |row|
+          y = top + row
+          break if y >= @height
+
+          src = indices.byteslice(row * w, visible) || ""
+          offset = (y * @width + left) * 4
+          if transparent.nil? || !src.include?(transparent.chr(Encoding::BINARY))
+            pixels = src.unpack("C*").map! { |i| palette[i] || TRANSPARENT }.join
+            @canvas[offset, pixels.bytesize] = pixels
+          else
+            src.each_byte.with_index do |i, x|
+              next if i == transparent
+
+              @canvas[offset + x * 4, 4] = palette[i] || TRANSPARENT
+            end
+          end
+        end
+      end
+
+      # Disposal method 2: restore the frame's area to transparent.
+      def clear_rect(left, top, w, h)
+        x_end = [left + w, @width].min
+        return if left >= x_end
+
+        blank = TRANSPARENT * (x_end - left)
+        h.times do |row|
+          y = top + row
+          break if y >= @height
+
+          @canvas[(y * @width + left) * 4, blank.bytesize] = blank
+        end
+      end
+    end
+  end
+end

data/lib/rubytui/input/parser.rb

@@ -5,36 +5,224 @@ module RubyTUI
     # Decodes raw terminal input into {KeyEvent} and {MouseEvent} objects.
     #
     # Recognised input: printable ASCII, Enter, Tab, Backspace, Ctrl+letter,
-    # multi-byte UTF-8 characters given as raw bytes (as read by {Reader}), ESC,
-    # Alt+character (ESC followed by one character),
+    # single UTF-8 characters (as raw bytes, as read by {Reader}, or as a UTF-8
+    # String), ESC, Alt+character (ESC followed by one character),
     # CSI and SS3 key sequences (arrows, Home/End, Insert/Delete, Page Up/Down,
     # Back-tab, F1-F12, xterm modified arrows such as <tt>ESC [ 1 ; 5 A</tt>),
+    # the same key sequences preceded by ESC (Alt+key as sent by rxvt-style
+    # terminals, e.g. <tt>ESC ESC [ A</tt> is Alt+Up),
     # and SGR and legacy mouse reports.
     #
+    # String sequences that terminals send as replies are recognised and
+    # produce no event: APC (<tt>ESC _</tt>, e.g. Kitty graphics responses),
+    # OSC (<tt>ESC ]</tt>), DCS (<tt>ESC P</tt>), SOS (<tt>ESC X</tt>) and PM
+    # (<tt>ESC ^</tt>), each ended by ST (ESC and a backslash) or BEL. Because these
+    # introducers start a string, Alt+P, Alt+X, Alt+], Alt+^ and Alt+_ are
+    # reported only when the input ends with the string they start still
+    # unfinished (see {#parse_prefix}).
+    #
+    # The +char+ of every {KeyEvent} it returns is a UTF-8 String.
+    #
     # @example
     #   Input::Parser.new.parse("\e[A")  # => KeyEvent(up)
     class Parser
+      # Longest CSI sequence, in bytes from ESC to the final byte. Recognised
+      # keys and SGR mouse reports are far shorter; the limit only bounds the
+      # bytes scanned for a final byte.
+      MAX_CSI_BYTES = 256
+      private_constant :MAX_CSI_BYTES
+
+      # Second byte of ESC P (DCS), ESC X (SOS), ESC ] (OSC), ESC ^ (PM) and
+      # ESC _ (APC), which start string sequences
+      STRING_INTRODUCERS = [0x50, 0x58, 0x5D, 0x5E, 0x5F].freeze
+      private_constant :STRING_INTRODUCERS
+
       # Parse raw bytes into an Event.
       #
+      # Input in any encoding is decoded byte-wise; a character is returned as
+      # UTF-8. Bytes that are not valid UTF-8 yield nil instead of raising.
+      #
       # @param bytes [String, nil] raw bytes of one key press or mouse report
       # @return [KeyEvent, MouseEvent, nil] the decoded event, or nil if +bytes+
-      #   is nil, empty or not a recognised sequence
+      #   is nil, empty, invalid UTF-8 or not a recognised sequence
+      # @see #parse_prefix
       def parse(bytes)
         return nil if bytes.nil? || bytes.empty?
 
+        bytes = bytes.b
         # ESC sequence
         if bytes.start_with?("\e")
           parse_escape(bytes)
-        elsif bytes.length == 1
+        elsif bytes.bytesize == 1
           parse_single(bytes)
         else
           # Multi-byte UTF-8 character
-          KeyEvent.new(code: Key::CHAR, char: bytes)
+          char = utf8_char(bytes)
+          char && KeyEvent.new(code: Key::CHAR, char: char)
         end
       end
 
+      # Parse the first event at the front of a buffer that may hold several.
+      #
+      # Finds where the first key press, escape sequence or mouse report in
+      # +bytes+ ends and decodes it with {#parse}. Unrecognised sequences are
+      # still measured, so the caller can drop them and carry on.
+      #
+      # A CSI sequence (<tt>ESC [</tt>) is at most 256 bytes long. If no
+      # final byte comes within its first 256 bytes, only <tt>ESC [</tt> is
+      # taken, as Alt+[, and the bytes after it are left to be decoded as
+      # input of their own; this does not depend on +partial+.
+      #
+      # A terminal string sequence (APC, OSC, DCS, SOS, PM) runs up to and
+      # including its ST or BEL terminator and gives no event. An ESC inside
+      # it that does not start ST ends it just before that ESC, also with no
+      # event. There is no length limit ({Reader} applies one).
+      #
+      # @param bytes [String] buffered raw input
+      # @param partial [Boolean] true if more input may follow +bytes+: an
+      #   incomplete sequence at the front (such as a lone ESC, an unfinished
+      #   string sequence, or ESC ESC that may start Alt+key) is then left
+      #   unconsumed. When false, it is decoded as it stands: ESC ESC is a
+      #   plain ESC key; an unfinished string sequence (no terminator, and no
+      #   ESC followed by another byte) is taken to be typed, so only its
+      #   introducer is taken, as Alt+character (2 bytes, e.g. <tt>ESC P</tt>
+      #   is Alt+P), and the bytes after it are left to be decoded as input
+      #   of their own; any other unfinished sequence is taken whole (a lone
+      #   ESC is the ESC key, <tt>ESC [</tt> and <tt>ESC O</tt> are Alt+[ and
+      #   Alt+O, and a cut-off UTF-8 character, mouse report or longer CSI
+      #   sequence gives no event) (default: false)
+      # @return [Array(Event, Integer)] a two-element array: the event (nil if
+      #   the sequence was not recognised or is a string sequence) and the
+      #   number of bytes it took up. The count is 0 only when +bytes+ is
+      #   empty or, with +partial+, holds just the start of a sequence.
+      #
+      # @example
+      #   Input::Parser.new.parse_prefix("\e[A\e[B")  # => [KeyEvent(up), 3]
+      #   Input::Parser.new.parse_prefix("\e_Gi=1;OK\e\\q")  # => [nil, 11]
+      #   Input::Parser.new.parse_prefix("\ePab")  # => [KeyEvent(Alt+P), 2]
+      def parse_prefix(bytes, partial: false)
+        bytes = bytes.b unless bytes.encoding == Encoding::BINARY
+        length = sequence_length(bytes)
+        length ||= partial ? 0 : incomplete_length(bytes)
+        return [nil, 0] if length.zero?
+
+        [parse(bytes.byteslice(0, length)), length]
+      end
+
       private
 
+      # Byte length of the first sequence in +bytes+ (binary), 0 if empty,
+      # or nil if +bytes+ ends before the sequence is complete.
+      def sequence_length(bytes)
+        return 0 if bytes.empty?
+
+        first = bytes.getbyte(0)
+        if first == 0x1B
+          escape_length(bytes)
+        elsif first < 0x80
+          1
+        else
+          utf8_length(bytes, 0)
+        end
+      end
+
+      # Length to take for a sequence cut short by the end of input: all of
+      # it, except that ESC ESC starts with a plain ESC key and an unfinished
+      # string sequence with its introducer (Alt+character).
+      def incomplete_length(bytes)
+        return 1 if bytes.start_with?("\e\e")
+        return 2 if bytes.getbyte(0) == 0x1B && STRING_INTRODUCERS.include?(bytes.getbyte(1))
+
+        bytes.bytesize
+      end
+
+      def escape_length(bytes)
+        second = bytes.getbyte(1)
+        case second
+        when nil then nil   # lone ESC so far
+        when 0x1B then alt_sequence_length(bytes)
+        when *STRING_INTRODUCERS
+          string_length(bytes)
+        when 0x5B           # CSI: ESC [
+          third = bytes.getbyte(2)
+          if third.nil?
+            nil
+          elsif third == 0x4D # legacy mouse: ESC [ M Cb Cx Cy
+            bytes.bytesize >= 6 ? 6 : nil
+          else
+            csi_length(bytes)
+          end
+        when 0x4F           # SS3: ESC O X
+          bytes.bytesize >= 3 ? 3 : nil
+        else                # Alt+character
+          return 2 if second < 0x80
+
+          char_length = utf8_length(bytes, 1)
+          char_length && char_length + 1
+        end
+      end
+
+      # CSI: parameter/intermediate bytes 0x20-0x3F, then a final byte 0x40-0x7E.
+      # Any other byte ends a malformed sequence just before it. With no
+      # final byte within MAX_CSI_BYTES, ESC [ alone (Alt+[).
+      def csi_length(bytes)
+        (2...[bytes.bytesize, MAX_CSI_BYTES].min).each do |i|
+          b = bytes.getbyte(i)
+          return i + 1 if b.between?(0x40, 0x7E)
+          return i unless b.between?(0x20, 0x3F)
+        end
+        bytes.bytesize >= MAX_CSI_BYTES ? 2 : nil
+      end
+
+      # ESC ESC: both ESCs and the CSI or SS3 sequence after the second, if
+      # together they are a key (Alt+key); otherwise 1, the first ESC as a
+      # plain key.
+      def alt_sequence_length(bytes)
+        rest = bytes.byteslice(1..)
+        return 1 unless [nil, 0x5B, 0x4F].include?(rest.getbyte(1))
+
+        length = escape_length(rest)
+        return nil if length.nil?
+
+        parse(bytes.byteslice(0, length + 1)).is_a?(KeyEvent) ? length + 1 : 1
+      end
+
+      # String sequence: ends after BEL or ST (ESC \), or just before any other
+      # ESC; nil while no terminator or other ESC has come.
+      def string_length(bytes)
+        stop = bytes.index(/[\a\e]/, 2)
+        return nil if stop.nil?
+        return stop + 1 if bytes.getbyte(stop) == 0x07
+
+        following = bytes.getbyte(stop + 1)
+        return nil if following.nil? # ESC at the end: may be the start of ST
+
+        following == 0x5C ? stop + 2 : stop
+      end
+
+      # Length of the UTF-8 character starting at +start+; an invalid sequence
+      # ends just before the first byte that does not continue it.
+      def utf8_length(bytes, start)
+        need = case bytes.getbyte(start)
+               when 0xC2..0xDF then 2
+               when 0xE0..0xEF then 3
+               when 0xF0..0xF4 then 4
+               else 1
+               end
+        (1...need).each do |k|
+          b = bytes.getbyte(start + k)
+          return nil if b.nil?
+          return k unless b.between?(0x80, 0xBF)
+        end
+        need
+      end
+
+      # +raw+ as a UTF-8 String if it is exactly one valid character, else nil.
+      def utf8_char(raw)
+        char = String.new(raw, encoding: Encoding::UTF_8)
+        char if char.valid_encoding? && char.length == 1
+      end
+
       def parse_single(byte)
         ord = byte.ord
 
@@ -49,11 +237,11 @@ module RubyTUI
           KeyEvent.new(code: Key::BACKSPACE)
         when 1..26
           # Ctrl+A through Ctrl+Z
-          char = (ord + 96).chr # Convert to lowercase letter
+          char = (ord + 96).chr(Encoding::UTF_8) # Convert to lowercase letter
           KeyEvent.new(code: Key::CHAR, char: char, modifiers: Key::CTRL)
         when 32..126
           # Printable ASCII
-          KeyEvent.new(code: Key::CHAR, char: byte)
+          KeyEvent.new(code: Key::CHAR, char: utf8_char(byte))
         else
           nil
         end
@@ -79,9 +267,16 @@ module RubyTUI
         # SS3 sequences: ESC O ...
         when /\A\eO([A-Za-z])\z/
           parse_ss3($1)
-        # Alt+letter: ESC + letter
-        when /\A\e(.)\z/
-          KeyEvent.new(code: Key::CHAR, char: $1, modifiers: Key::ALT)
+        # Alt+key (rxvt-style): ESC + CSI or SS3 key sequence
+        when /\A\e(\e[\[O].+)\z/m
+          key = parse_escape($1)
+          if key.is_a?(KeyEvent)
+            KeyEvent.new(code: key.code, char: key.char, modifiers: key.modifiers | Key::ALT)
+          end
+        # Alt+character: ESC + one (possibly multi-byte) character
+        when /\A\e(.+)\z/
+          char = utf8_char($1)
+          char && KeyEvent.new(code: Key::CHAR, char: char, modifiers: Key::ALT)
         else
           nil
         end
@@ -154,7 +349,7 @@ module RubyTUI
       end
 
       # SGR extended mouse mode: ESC [ < Cb ; Cx ; Cy M (press) or m (release)
-      # Cb encodes button + modifiers + drag flag
+      # Cb encodes button + modifiers + motion flag
       def parse_sgr_mouse(cb, cx, cy, terminator)
         # Coordinates are 1-based in SGR mode
         x = cx - 1
@@ -172,8 +367,12 @@ module RubyTUI
         is_scroll = (cb & 64) != 0
 
         if is_scroll
-          button = button_bits == 0 ? MouseEvent::SCROLL_UP : MouseEvent::SCROLL_DOWN
+          button = scroll_button(button_bits)
           action = MouseEvent::PRESS
+        elsif is_drag && button_bits == 3
+          # Motion with no button held
+          button = MouseEvent::NONE
+          action = MouseEvent::MOVE
         else
           button = case button_bits
                    when 0 then MouseEvent::LEFT
@@ -209,11 +408,12 @@ module RubyTUI
         button_bits = cb & 3
 
         if is_scroll
-          button = button_bits == 0 ? MouseEvent::SCROLL_UP : MouseEvent::SCROLL_DOWN
+          button = scroll_button(button_bits)
           action = MouseEvent::PRESS
         elsif button_bits == 3
+          # Release, or motion with no button held
           button = MouseEvent::NONE
-          action = MouseEvent::RELEASE
+          action = is_drag ? MouseEvent::MOVE : MouseEvent::RELEASE
         else
           button = case button_bits
                    when 0 then MouseEvent::LEFT
@@ -226,6 +426,16 @@ module RubyTUI
 
         MouseEvent.new(button: button, action: action, x: x, y: y, modifiers: mods)
       end
+
+      # Wheel button for the low two bits of a wheel report (codes 64-67)
+      def scroll_button(button_bits)
+        case button_bits
+        when 0 then MouseEvent::SCROLL_UP
+        when 1 then MouseEvent::SCROLL_DOWN
+        when 2 then MouseEvent::SCROLL_LEFT
+        else MouseEvent::SCROLL_RIGHT
+        end
+      end
     end
   end
 end