terminal_rb 0.20.0 → 1.0.4

data/lib/terminal/ansi/screen_viewer.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+module Terminal
+  module Ansi
+    # A scrollable text viewer for the terminal.
+    #
+    # Renders word-wrapped content and supports paging, line-by-line
+    # scrolling, and terminal resize. Intended for use with the alternate
+    # screen buffer.
+    #
+    # @example Basic pager
+    #   viewer = Terminal::Ansi::ScreenViewer.new(lines, footer_rows: 1)
+    #   Terminal.show_alt_screen
+    #   viewer.draw
+    #   Terminal.on_key_event do |event|
+    #     case event.key
+    #     when :Up then viewer.up
+    #     when :Down then viewer.down
+    #     when :PageUp then viewer.page_up
+    #     when :PageDown then viewer.page_down
+    #     when 'q' then break
+    #     end
+    #   end
+    #   Terminal.hide_alt_screen
+    #
+    class ScreenViewer
+      # Total number of terminal rows.
+      #
+      # @return [Integer]
+      attr_reader :rows
+
+      # @attribute [w] rows
+      def rows=(value)
+        resize(value, @columns)
+      end
+
+      # Total number of terminal columns.
+      #
+      # @return [Integer]
+      attr_reader :columns
+
+      # @attribute [w] columns
+      def columns=(value)
+        resize(@rows, value)
+      end
+
+      # Number of rows available for content (rows minus footer).
+      #
+      # @return [Integer]
+      attr_reader :rows_visible
+
+      # Total number of lines.
+      #
+      # @attribute [r] line_count
+      # @return [Integer, nil] +nil+ when not already calculated
+      def line_count = @buf&.size
+
+      # Index of the topmost visible line.
+      #
+      # @return [Integer]
+      attr_reader :line_top
+
+      # Index of the line just below the last visible line.
+      #
+      # @attribute [r] line_bottom
+      # @return [Integer]
+      def line_bottom = (@line_top + @rows_visible if @line_top)
+
+      # Resize to the current terminal dimensions and redraw.
+      #
+      # @return [self, nil] +nil+ when resize is not required
+      def resize_to_screen = _resize(*Terminal.size)
+
+      # Resize to specific dimensions (clamped to terminal bounds)
+      # and redraw.
+      #
+      # @param rows [Integer] new row count
+      # @param columns [Integer] new column count
+      # @return [self, nil] +nil+ when resize is not required
+      def resize(rows, columns)
+        _resize(
+          rows.clamp(1, Terminal.rows),
+          columns.clamp(1, Terminal.columns)
+        )
+      end
+
+      # Render the current viewport to the terminal.
+      #
+      # @return [self]
+      def draw
+        recalculate unless @buf
+        if @buf.empty?
+          Terminal.raw_write(SCREEN_ERASE)
+          return self
+        end
+        Terminal.raw_write(CURSOR_HOME)
+        _draw(@line_top, @rows_visible)
+      end
+
+      # Scroll to the beginning of the content.
+      #
+      # @return [self, nil] +nil+ when already on begin
+      def begin
+        return draw unless @buf
+        return if @line_top == 0
+        @line_top = 0
+        draw
+      end
+
+      # Scroll to the end of the content.
+      #
+      # @return [self, nil] +nil+ when already on end
+      def end
+        return draw unless @buf
+        idx = @buf.size - @rows_visible
+        return if idx < 0 || @line_top == idx
+        @line_top = idx
+        draw
+      end
+
+      # Scroll up by the given number of lines.
+      #
+      # @param count [Integer] number of lines to scroll
+      # @return (see #begin)
+      def up(count = 1)
+        return draw unless @buf
+        return if @line_top == 0
+        if (nidx = @line_top - count) < 0
+          count = @line_top
+          @line_top = 0
+        else
+          @line_top = nidx
+        end
+        Terminal.raw_write(Ansi.screen_scroll_down(count))
+        Terminal.raw_write(CURSOR_HOME)
+        _draw(@line_top, count)
+      end
+
+      # Scroll down by the given number of lines.
+      #
+      # @param count [Integer] number of lines to scroll
+      # @return (see #end)
+      def down(count = 1)
+        return draw unless @buf
+        lidx = @line_top + @rows_visible
+        return if (count = [count, @buf.size - lidx].min) <= 0
+        @line_top += count
+        Terminal.raw_write(Ansi.screen_scroll_up(count))
+        Terminal.raw_write(Ansi.cursor_pos(@rows_visible - count + 1))
+        _draw(lidx, count)
+      end
+
+      # Scroll up by one full page.
+      #
+      # @return (see #begin)
+      def page_up = up(@rows_visible)
+
+      # Scroll up by half a page.
+      #
+      # @return (see #begin)
+      def half_up = up(@rows_visible / 2)
+
+      # Scroll down by one full page.
+      #
+      # @return (see #end)
+      def page_down = down(@rows_visible)
+
+      # Scroll down by half a page.
+      #
+      # @return (see #end)
+      def half_down = down(@rows_visible / 2)
+
+      # Create a new screen viewer.
+      #
+      # @param lines [Array<#to_s>] content lines to display
+      # @param footer_rows [Integer] number of rows reserved at the bottom
+      #   (not scrolled with content)
+      # @param bbcode [true, false] whether to process BBCode markup
+      def initialize(lines, footer_rows: 0, bbcode: true)
+        @footer_rows = footer_rows.to_i
+        @rows, @columns = Terminal.size
+        @rows_visible = @rows - @footer_rows
+        @fmt =
+          Text::Formatter.new(
+            *lines,
+            bbcode: bbcode,
+            ansi: true,
+            eol: true,
+            spaces: true
+          )
+      end
+
+      private
+
+      def _resize(rows, columns)
+        return if @rows == rows && @columns == columns
+        @rows = rows
+        @columns = columns
+        @rows_visible = rows - @footer_rows
+        @buf = nil
+        draw
+      end
+
+      def _draw(idx, count)
+        idx -= 1
+        (count - 1).times do
+          line = @buf[idx += 1] and Terminal.raw_write(line)
+          Terminal.raw_write(NEXT_LINE)
+        end
+        line = @buf[idx + 1] and Terminal.raw_write(line)
+        Terminal.raw_write(LINE_ERASE_TO_END)
+        self
+      end
+
+      NEXT_LINE = -"#{LINE_ERASE_TO_END}#{CURSOR_NEXT_LINE}"
+      private_constant :NEXT_LINE
+
+      def recalculate
+        @buf = @fmt.lines(width: @columns)
+        @line_top = 0
+      end
+    end
+  end
+end