samagotchi 0.2.0

data/lib/samagotchi/terminal_ui/reline_seam.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "reline"
+
+module Samagotchi
+  class TerminalUI
+    # Prepended to Reline::LineEditor: while a Screen is attached, Reline
+    # keeps doing all the input work (keys, history, completion dialogs,
+    # multiline, paste) but draws nothing itself. Its rendered rows go to the
+    # Screen's editor slot, and a finished prompt goes to scrollback through
+    # the Screen. With no Screen attached every method is Reline's own.
+    #
+    # This overrides private methods of reline 0.6.x (the Gemfile pins it).
+    # .supported? checks that they are all still there; without them attached
+    # mode falls back to plain output. What each override relies on:
+    # - render_differential(lines, cursor_x, cursor_y): called by #render
+    #   with the rows it laid out; the seam hands them to the Screen and keeps
+    #   @rendered_screen as if Reline had drawn them.
+    # - reset: asks the terminal for the cursor row (base_y), which decides
+    #   whether a dialog opens below the prompt. The region's editor rows
+    #   start at 0.
+    # - screen_height: the rows Reline may draw in, cut to the Screen's
+    #   editor budget so the region fits (Reline scrolls the input inside it).
+    #   Overriding the method, not @screen_size, survives reset and resizes.
+    # - update(key): every key a read takes, for the key handler.
+    # - render_finished (Enter), handle_interrupted (Ctrl-C), finalize (every
+    #   read, including one dropped by Thread#raise), ed_clear_screen and its
+    #   alias clear_screen (Ctrl-L), handle_resized (SIGWINCH, SIGCONT).
+    module RelineSeam
+      # Reline's methods the seam overrides or calls, with their arities.
+      METHODS = { reset: -1, finalize: 0, render_finished: 0, screen_height: 0, screen_width: 0,
+                  prompt_list: 0, modified_lines: 0, clear_dialogs: 0, scroll_into_view: 0, render: 0,
+                  render_differential: 3, handle_interrupted: 0, handle_resized: 0,
+                  clear_rendered_screen_cache: 0, ed_clear_screen: 1, clear_screen: 1,
+                  split_line_by_width: -3, update: 1 }.freeze
+
+      class << self
+        # @return [Screen, nil] where Reline draws, nil for Reline's own drawing
+        attr_reader :screen
+
+        # Asked first on Ctrl-C during a read, with or without a screen: a
+        # truthy answer means it handled the key (the REPL cancelled a running
+        # turn) and the read goes on with the typed text as it is.
+        # @return [#call, nil]
+        attr_accessor :interrupt_handler
+
+        # Called with no arguments for each key a read takes (typing is
+        # activity for the REPL's idle clock).
+        # @return [#call, nil]
+        attr_accessor :key_handler
+
+        # @return [Boolean] a Reline read is open (it owns stdin)
+        def reading? = @reading == true
+
+        # Run a read (on this thread) whose submitted line leaves nothing in
+        # the scrollback: the answer to a question, which commits its own
+        # summary line instead.
+        def without_echo
+          was = Thread.current[:samagotchi_reline_no_echo]
+          Thread.current[:samagotchi_reline_no_echo] = true
+          yield
+        ensure
+          Thread.current[:samagotchi_reline_no_echo] = was
+        end
+
+        # @api private
+        attr_writer :reading
+
+        # @return [Boolean] this Reline has every method the seam relies on
+        def supported?
+          defined?(Reline::LineEditor::RenderedScreen) &&
+            (%i[base_y lines cursor_y] - Reline::LineEditor::RenderedScreen.members).empty? &&
+            METHODS.all? { |name, arity| reline_method(name)&.arity == arity }
+        end
+
+        # Reline draws into +screen+ from its next render on.
+        def attach(screen)
+          # Measuring a character like … or │ makes Reline print one and ask
+          # the terminal where the cursor went, the first time only. Do it
+          # now, before the Screen measures rows from other threads while a
+          # read owns stdin.
+          Reline.ambiguous_width
+          install
+          @screen = screen
+        end
+
+        # Put the seam in Reline without a screen: Reline draws as usual, and
+        # reading? and the interrupt handler work.
+        def install
+          Reline::LineEditor.prepend(self) unless Reline::LineEditor.include?(self)
+        end
+
+        def detach(screen)
+          @screen = nil if @screen.equal?(screen)
+        end
+
+        private
+
+        # Reline's own implementation, past this module once it is prepended.
+        def reline_method(name)
+          method = Reline::LineEditor.instance_method(name)
+          method = method.super_method while method&.owner == self
+          method
+        rescue NameError
+          nil
+        end
+      end
+
+      def reset(...)
+        super
+        RelineSeam.reading = true
+        @rendered_screen.base_y = 0 if RelineSeam.screen
+      end
+
+      def update(key)
+        RelineSeam.key_handler&.call
+        super
+      end
+
+      def screen_height
+        screen = RelineSeam.screen
+        screen ? [super, screen.editor_budget].min : super
+      end
+
+      def render_finished
+        screen = RelineSeam.screen
+        return super unless screen
+
+        screen.finish_editor(Thread.current[:samagotchi_reline_no_echo] ? nil : seam_final_lines)
+        clear_rendered_screen_cache
+      end
+
+      # A read that ends without render_finished (dropped by Thread#raise,
+      # or an I/O error) leaves its prompt in the region: take it out.
+      def finalize
+        screen = RelineSeam.screen
+        if screen && !@rendered_screen.lines.empty?
+          screen.finish_editor
+          clear_rendered_screen_cache
+        end
+        RelineSeam.reading = false
+        super
+      end
+
+      private
+
+      def render_differential(new_lines, cursor_x, cursor_y)
+        screen = RelineSeam.screen
+        return super unless screen
+
+        cursor_y = cursor_y.clamp(0, [screen_height - 1, 0].max)
+        screen.draw_editor(new_lines, cursor_x, cursor_y)
+        @rendered_screen.lines = new_lines
+        @rendered_screen.cursor_y = cursor_y
+      end
+
+      # Ctrl-C: the interrupt handler's if it takes it. Otherwise the typed
+      # text stays in scrollback with ^C, then Reline's own handling of the
+      # trap it replaced (raise Interrupt by default).
+      def handle_interrupted
+        return unless @interrupted
+
+        if RelineSeam.interrupt_handler&.call
+          @interrupted = false
+          return
+        end
+        screen = RelineSeam.screen
+        return super unless screen
+
+        @interrupted = false
+        clear_dialogs
+        screen.finish_editor(seam_final_lines.tap { |lines| lines[-1] = "#{lines[-1]}^C" })
+        clear_rendered_screen_cache
+        case @old_trap
+        when "DEFAULT", "SYSTEM_DEFAULT" then raise Interrupt
+        when "IGNORE" then nil
+        when "EXIT" then exit
+        else @old_trap.call if @old_trap.respond_to?(:call)
+        end
+      end
+
+      def handle_resized
+        screen = RelineSeam.screen
+        return super unless screen
+        return unless @resized
+
+        @screen_size = Reline::IOGate.get_screen_size
+        @resized = false
+        scroll_into_view
+        clear_rendered_screen_cache
+        render
+      end
+
+      def ed_clear_screen(key)
+        screen = RelineSeam.screen
+        return super unless screen
+
+        screen.clear_screen
+        @screen_size = Reline::IOGate.get_screen_size
+        clear_rendered_screen_cache
+      end
+
+      # Reline's alias still points at its own ed_clear_screen.
+      def clear_screen(key) = ed_clear_screen(key)
+
+      # The prompt and the text as render_finished writes them: one line per
+      # input line, with a trailing space when a line fills the width exactly.
+      def seam_final_lines
+        @buffer_of_lines.size.times.map do |i|
+          line = Reline::Unicode.strip_non_printing_start_end(prompt_list[i]) + modified_lines[i]
+          split_line_by_width(line, screen_width).last.empty? ? "#{line} " : line
+        end
+      end
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/repl_input.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "monitor"
+require_relative "line_reader"
+
+module Samagotchi
+  class TerminalUI
+    # The REPL's input on a terminal: one LineReader keeps a prompt open for
+    # the whole session, turns included, and this routes what it reads. A
+    # line goes to a question waiting at the prompt (asked at ? ), to
+    # the running turn when its handler takes it (steering), else to the
+    # inbox the REPL loop takes its next line from.
+    class ReplInput
+      # @param prompt [#call] -> the prompt when no question waits
+      # @param read [#call] (prompt, prefill) -> line (nil = Ctrl-D)
+      # @param surface [Surface] the editor slot a dropped read leaves is
+      #   cleared under its lock
+      def initialize(prompt:, read:, surface:)
+        @prompt = prompt
+        @read = read
+        @surface = surface
+        @inbox = Thread::Queue.new
+        # Lines a turn left over: they come before the inbox.
+        @front = []
+        @turn = nil
+        @lock = Monitor.new
+        @answers = nil
+      end
+
+      def start(prefill: nil)
+        @reader = LineReader.new(self, prompt: method(:prompt_text), read: @read, prefill: prefill).start
+        self
+      end
+
+      def open? = @reader&.alive? || false
+
+      def stop
+        @reader&.stop
+        @surface.clear_slot(:editor)
+      end
+
+      # From the reader thread: [:line, text] or [:interrupt, info].
+      def <<(item)
+        @lock.synchronize do
+          next @answers << item if @answers
+          taken = @turn && item.first == :line && @turn.call(item.last)
+          # Not now: the line goes back into the prompt.
+          next @reader&.prefill_next(item.last) if taken == :back
+          next if taken
+
+          @inbox << item
+        end
+        self
+      end
+
+      # @return [Array, nil] the next item, nil after +timeout+ seconds
+      def pop(timeout:)
+        @lock.synchronize { return @front.shift unless @front.empty? }
+        @inbox.pop(timeout: timeout)
+      end
+
+      # While a turn runs, +handler+ (line -> truthy when it took the line,
+      # :back to put it back into the prompt) sees each line first. Once it ends, +leftovers+ (-> lines it took that the
+      # turn never merged) come next, in order, before anything in the inbox.
+      def during_turn(handler, leftovers:)
+        @lock.synchronize { @turn = handler }
+        yield
+      ensure
+        @lock.synchronize do
+          @turn = nil
+          @front.concat(Array(leftovers.call).map { |line| [:line, line] })
+        end
+      end
+
+      def prompt_text
+        @lock.synchronize { @answers ? @choice_prompt : @prompt.call }
+      end
+
+      # Start the open read again when its prompt changed (a continue offer
+      # came or went); what was typed is kept.
+      def sync_prompt
+        return unless open?
+
+        with_surface_lock do
+          next if @reader.current == prompt_text
+
+          @surface.clear_slot(:editor)
+          @reader.reprompt(keep_text: true)
+        end
+      end
+
+      # Put +text+ into the open prompt, unless something is typed there.
+      # @return [Boolean] whether it went in
+      def prefill(text) = open? && @reader.prefill(text)
+
+      # A question answered at the open prompt: the lines submitted from now
+      # on go to it, at the ? prompt. What was typed at the prompt is put aside
+      # and comes back once the question closes.
+      # @yield [Thread::Queue] the answers ([:line, text] or [:interrupt, info])
+      # A prompt closed by Ctrl-D mid-turn (the REPL exits after the turn)
+      # opens for the question and closes again after it.
+      def ask(choice_prompt)
+        was_open = open?
+        typed = was_open ? @reader.typed_text : nil
+        answers = Thread::Queue.new
+        @lock.synchronize do
+          @answers = answers
+          @choice_prompt = choice_prompt
+        end
+        was_open ? reprompt : start
+        yield answers
+      ensure
+        @lock.synchronize { @answers = nil }
+        if !was_open
+          stop
+        elsif open?
+          reprompt(prefill: typed)
+        else
+          # Ctrl-D at the question ended the reader: start it again.
+          start(prefill: typed)
+        end
+      end
+
+      private
+
+      def reprompt(prefill: nil)
+        with_surface_lock do
+          @surface.clear_slot(:editor)
+          @reader.reprompt(prefill: prefill)
+        end
+      end
+
+      def with_surface_lock(&block)
+        @surface.respond_to?(:synchronize) ? @surface.synchronize(&block) : yield
+      end
+    end
+  end
+end

data/lib/samagotchi/terminal_ui/screen.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require "io/console"
+require "monitor"
+require "reline"
+require "stringio"
+require_relative "surface"
+
+module Samagotchi
+  class TerminalUI
+    # The only writer to the terminal while a live region is on (attached
+    # mode). The bottom of the screen is the live region, its slots top down:
+    # activity (spinner, thinking tail), editor (the Reline prompt and its
+    # completion dialog, fed by RelineSeam), then status, notes and hints.
+    # Everything above it is normal scrollback: no alternate screen, so
+    # scrolling and copy/paste stay the terminal's own.
+    #
+    # Every change is one frame under the lock: move up to the top of the
+    # region, clear to the end of the screen (ESC[J), print any committed
+    # text, and draw the region again with the cursor back in the editor.
+    # Committed text may wrap; the region's rows are clipped to the width,
+    # so the move up is exact and the region can't drift.
+    class Screen
+      include Surface
+
+      # The slots below the editor, and the order they give way in when
+      # the terminal is short: hints first, then notes, then status.
+      BELOW = %i[status notes hints].freeze
+      SYNC_BEGIN = "\e[?2026h\e[?25l"
+      SYNC_END = "\e[?25h\e[?2026l"
+
+      # @param out [IO]
+      # @param size [#call] -> [rows, columns] of the terminal
+      def initialize(out:, size: -> { IO.console&.winsize || [24, 80] })
+        @out = out
+        @size = size
+        @lock = Monitor.new
+        @slots = {}
+        @editor = []
+        @editor_cursor = [0, 0]
+        @cursor_row = 0
+      end
+
+      def synchronize(&) = @lock.synchronize(&)
+
+      # @return [Integer] terminal width in columns
+      def columns = [@size.call.last.to_i, 1].max
+
+      # @return [Integer] terminal height in rows
+      def rows = [@size.call.first.to_i, 1].max
+
+      # Print permanent output (may hold several lines) above the region.
+      def commit(text)
+        lines = text.to_s.split("\n", -1)
+        synchronize { frame { |buffer| lines.each { |line| buffer << line << "\r\n" } } }
+        nil
+      end
+
+      # The editor slot is Reline's: RelineSeam feeds it with #draw_editor.
+      def set_slot(name, rows) = set_slots(name => rows)
+
+      # One frame for all the slots given, none when nothing changed.
+      def set_slots(**rows_by_slot)
+        rows_by_slot = rows_by_slot.to_h do |name, rows|
+          check_slot!(name)
+          raise ArgumentError, "Reline draws the editor slot" if name == :editor
+
+          # Fitted content is laid out at each frame (#region).
+          [name, rows.respond_to?(:fit) ? rows : Array(rows).map { |row| one_row(row) }]
+        end
+        synchronize do
+          next if rows_by_slot.all? { |name, rows| slot(name).equal?(rows) || slot(name) == rows }
+
+          rows_by_slot.each do |name, rows|
+            rows.respond_to?(:empty?) && rows.empty? ? @slots.delete(name) : (@slots[name] = rows)
+          end
+          frame
+        end
+        nil
+      end
+
+      # Clearing the editor slot drops the prompt from the region (its read
+      # is about to be dropped and started again).
+      # @return [Boolean] whether the slot showed anything
+      def clear_slot(name)
+        check_slot!(name)
+        synchronize do
+          next finish_editor if name == :editor
+          next false unless @slots.key?(name)
+
+          @slots.delete(name)
+          frame
+          true
+        end
+      end
+
+      # Rows the editor may take (its prompt, wrapped input and completion
+      # dialog), so that the region fits on the screen with the activity and
+      # status rows. Notes and hints give way to the editor instead.
+      def editor_budget
+        synchronize { [rows - 1 - fitted(:activity, columns).size - fitted(:status, columns).size, 1].max }
+      end
+
+      # Reline rendered: +lines+ are its rows of [x, width, content] layers
+      # (prompt, input, dialog), the cursor is at (+cursor_x+, +cursor_y+)
+      # inside them.
+      def draw_editor(lines, cursor_x, cursor_y)
+        synchronize do
+          @editor = lines.map { |layers| compose(layers) }
+          @editor_cursor = [cursor_x, cursor_y]
+          frame
+        end
+        nil
+      end
+
+      # The prompt ended. +lines+ (the submitted text, or the text with ^C)
+      # go to scrollback; without them the prompt just disappears.
+      # @return [Boolean] whether a prompt was shown
+      def finish_editor(lines = nil)
+        synchronize do
+          shown = !@editor.empty?
+          next false unless shown || lines
+
+          @editor = []
+          @editor_cursor = [0, 0]
+          frame { |buffer| lines&.each { |line| buffer << line << "\r\n" } }
+          shown
+        end
+      end
+
+      # Ctrl-L: clear the screen and draw the region at the top.
+      def clear_screen
+        synchronize do
+          @cursor_row = 0
+          frame(clear: true)
+        end
+      end
+
+      # Draw the region again (after a resize).
+      def redraw
+        synchronize { frame }
+      end
+
+      # Take over what else writes to the terminal while the screen is on:
+      # $stderr (warnings from background threads would cross the region)
+      # and SIGWINCH outside a read (Reline traps it only during one, and
+      # chains to this trap then). #close gives both back.
+      # @return [self]
+      def start
+        @stderr_was = $stderr
+        $stderr = ErrorOutput.new(self)
+        # A trap handler can't take the lock: redraw from a thread.
+        @winch_was = Signal.trap("WINCH") { Thread.new { redraw } }
+        self
+      rescue ArgumentError
+        self # no SIGWINCH on this platform
+      end
+
+      # Erase the region and leave the cursor where it began; put back what
+      # #start took over.
+      def close
+        if @stderr_was
+          $stderr.flush
+          $stderr = @stderr_was
+          @stderr_was = nil
+        end
+        Signal.trap("WINCH", @winch_was) if @winch_was
+        @winch_was = nil
+        synchronize do
+          @slots.clear
+          @editor = []
+          frame
+        end
+      end
+
+      # $stderr while a Screen is on: each line written goes above the region
+      # as committed output. A line without its newline waits for the rest.
+      class ErrorOutput
+        def initialize(screen)
+          @screen = screen
+          @pending = +""
+          @lock = Mutex.new
+        end
+
+        def write(*parts)
+          text = parts.join
+          lines = @lock.synchronize do
+            @pending << text
+            *done, @pending = @pending.split("\n", -1)
+            @pending = +@pending.to_s
+            done
+          end
+          lines.each { |line| @screen.commit(line) }
+          text.bytesize
+        end
+
+        def print(*parts)
+          write(*parts)
+          nil
+        end
+
+        def puts(*items)
+          io = StringIO.new
+          io.puts(*items)
+          write(io.string)
+          nil
+        end
+
+        def <<(item)
+          write(item)
+          self
+        end
+
+        # Commit a line still waiting for its newline.
+        def flush
+          line = @lock.synchronize { @pending.empty? ? nil : @pending.dup.tap { @pending.clear } }
+          @screen.commit(line) if line
+          self
+        end
+
+        def sync = true
+        def sync=(_value); end
+        def tty? = false
+        alias isatty tty?
+        def fileno = nil
+      end
+
+      private
+
+      def slot(name) = @slots.fetch(name, [])
+
+      # A slot's rows at +width+; fitted content gets at most +height+ rows.
+      def fitted(name, width, height = nil)
+        content = slot(name)
+        return content unless content.respond_to?(:fit)
+
+        lay_out(content, width: width, height: height && [height, 0].max).map { |row| one_row(row) }
+      end
+
+      # One frame: erase the region, let the block add scrollback text, draw
+      # the region. Written in one piece and never cut short by
+      # Thread#raise (LineReader drops a read that way).
+      def frame(clear: false)
+        Thread.handle_interrupt(Object => :never) do
+          buffer = +SYNC_BEGIN
+          buffer << "\e[2J\e[H" if clear
+          buffer << "\r"
+          buffer << "\e[#{@cursor_row}A" if @cursor_row.positive?
+          buffer << "\e[J"
+          @cursor_row = 0
+          yield buffer if block_given?
+          buffer << region
+          buffer << SYNC_END
+          @out.write(buffer)
+          @out.flush
+        end
+      end
+
+      # The region's rows, leaving the cursor in the editor (or on the row
+      # below the region when no prompt is open). Sets @cursor_row.
+      def region
+        width = columns
+        above = fitted(:activity, width)
+        spare = [rows - 1 - above.size - @editor.size, 0].max
+        # Each slot below gets the rows the ones above it left.
+        below = BELOW.each_with_object([]) do |name, taken|
+          taken.concat(fitted(name, width, spare - taken.size).first([spare - taken.size, 0].max))
+        end
+        above = above.last([rows - 1 - @editor.size, 0].max)
+        all = above + @editor + below
+        return +"" if all.empty?
+
+        text = all.map { |row| clip(row, width) }.join("\r\n")
+        last = all.size - 1
+        if @editor.empty?
+          text << "\r\n"
+          @cursor_row = last + 1
+        else
+          target = above.size + @editor_cursor[1].clamp(0, @editor.size - 1)
+          text << "\e[#{last - target}A" if last > target
+          text << "\r"
+          text << "\e[#{@editor_cursor[0]}C" if @editor_cursor[0].positive?
+          @cursor_row = target
+        end
+        text
+      end
+
+      # A slot row is one line: no line breaks or tabs.
+      def one_row(row) = row.to_s.tr("\r\n\t", "   ")
+
+      # Cut a row to the terminal width, so it takes exactly one row.
+      def clip(row, width)
+        return row if Reline::Unicode.calculate_width(row, true) <= width
+
+        "#{Reline::Unicode.take_mbchar_range(row, 0, width, padding: false).first}\e[0m"
+      end
+
+      # Lay Reline's layers (prompt, input, dialog rows) over each other into
+      # one row, as Reline's own render_line_differential would draw them.
+      def compose(layers)
+        base = +""
+        layers.each do |layer|
+          next unless layer
+
+          x, w, content = layer
+          base_width = Reline::Unicode.calculate_width(base, true)
+          base << (" " * (x - base_width)) if base_width < x
+          head, = Reline::Unicode.take_mbchar_range(base, 0, x, padding: true)
+          tail, = Reline::Unicode.take_mbchar_range(base, x + w, [base_width - x - w, 0].max, padding: true)
+          base = "#{head}\e[0m#{content}\e[0m#{tail}"
+        end
+        base
+      end
+    end
+  end
+end