tty-pager 0.12.1 → 0.13.0

data/lib/tty/pager/abstract.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module TTY
+  module Pager
+    class Abstract
+      UndefinedMethodError = Class.new(StandardError)
+
+      # Paginate content through null, basic or system pager.
+      #
+      # @param [String] text
+      #   an optional blob of content
+      # @param [String] path
+      #   a path to a file
+      #
+      # @api public
+      def self.page(text = nil, path: nil, **options, &block)
+        validate_arguments(text, path, block)
+
+        instance = new(**options)
+
+        begin
+          if block_given?
+            block.call(instance)
+          else
+            instance.page(text, path: path)
+          end
+        rescue PagerClosed
+          # do nothing
+        ensure
+          instance.close
+        end
+      end
+
+      # Disallow mixing input arguments
+      #
+      # @raise [IvalidArgument]
+      #
+      # @api private
+      def self.validate_arguments(text, path, block)
+        message = if !text.nil? && !block.nil?
+                    "Cannot give text argument and block at the same time."
+                  elsif !text.nil? && !path.nil?
+                    "Cannot give text and :path arguments at the same time."
+                  elsif !path.nil? && !block.nil?
+                    "Cannot give :path argument and block at the same time."
+                  end
+        raise(InvalidArgument, message) if message
+      end
+      private_class_method :validate_arguments
+
+      # Create a pager
+      #
+      # @param [IO] :input
+      #   the object to send input to
+      # @param [IO] :output
+      #   the object to send output to
+      # @param [Boolean] :enabled
+      #   disable/enable text paging
+      #
+      # @api public
+      def initialize(input: $stdin, output: $stdout, enabled: true, **_options)
+        @input   = input
+        @output  = output
+        @enabled = enabled
+      end
+
+      # Check if pager is enabled
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def enabled?
+        !!@enabled
+      end
+
+      # Page text
+      #
+      # @example
+      #   page('some long text...')
+      #
+      # @param [String] text
+      #   the text to paginate
+      #
+      # @api public
+      def page(text = nil, path: nil)
+        if path
+          IO.foreach(path) do |line|
+            write(line)
+          end
+        else
+          write(text)
+        end
+      rescue PagerClosed
+        # do nothing
+      ensure
+        close
+      end
+
+      # Try writing to the pager. Return false if the pager was closed.
+      #
+      # In case of system pager, send text to
+      # the pager process. Start a new process if it hasn't been
+      # started yet.
+      #
+      # @param [Array<String>] *args
+      #   strings to send to the pager
+      #
+      # @return [Boolean]
+      #   the success status of writing to the pager process
+      #
+      # @api public
+      def try_write(*args)
+        write(*args)
+        true
+      rescue PagerClosed
+        false
+      end
+
+      def write(*)
+        raise UndefinedMethodError
+      end
+
+      def puts(*)
+        raise UndefinedMethodError
+      end
+
+      def close(*)
+        raise UndefinedMethodError
+      end
+
+      protected
+
+      attr_reader :output
+
+      attr_reader :input
+    end # Abstract
+  end # Pager
+end # TTY

data/lib/tty/pager/basic.rb

@@ -1,91 +1,234 @@
 # frozen_string_literal: true
 
-require 'strings'
+require "io/console"
+require "strings"
+require "tty-screen"
+
+require_relative "abstract"
 
 module TTY
-  class Pager
+  module Pager
     # A basic pager is used to work on systems where
     # system pager is not supported.
     #
     # @api public
-    class BasicPager < Pager
-      PAGE_BREAK = "\n--- Page -%s- " \
-                    "Press enter/return to continue " \
+    class BasicPager < Abstract
+      PAGE_BREAK = "\n--- Page -%<page>s- Press enter/return to continue " \
                     "(or q to quit) ---"
 
+      # Default prompt for paging
+      #
+      # @return [Proc]
+      #
+      # @api private
+      DEFAULT_PROMPT = ->(page) { format(PAGE_BREAK, page: page) }
+
       # Create a basic pager
       #
-      # @option options [Integer] :height
+      # @param [Integer] :height
       #   the terminal height
-      # @option options [Integer] :width
+      # @param [Integer] :width
       #   the terminal width
+      # @param [Proc] :prompt
+      #   a proc object that accepts page number
       #
       # @api public
-      def initialize(**options)
-        super
-        @height  = options.fetch(:height) { page_height }
-        @width   = options.fetch(:width)  { page_width }
-        @prompt  = options.fetch(:prompt) { default_prompt }
-        prompt_height = PAGE_BREAK.lines.to_a.size
-        @height -= prompt_height
+      def initialize(height: TTY::Screen.height, width: TTY::Screen.width,
+                     prompt: DEFAULT_PROMPT, **options)
+        super(**options)
+        @width   = width
+        @prompt  = prompt
+        prompt_height = Strings.wrap(prompt.call(100).to_s, width).lines.count
+        @page_cursor = PageCursor.new(height - prompt_height)
+
+        reset
       end
 
-      # Default prompt for paging
+      # Write text to the pager, prompting on page end.
       #
-      # @return [Proc]
+      # @raise [PagerClosed]
+      #   if the pager was closed
       #
-      # @api private
-      def default_prompt
-        proc { |page_num| output.puts Strings.wrap(PAGE_BREAK % page_num, @width) }
+      # @return [TTY::Pager::BasicPager]
+      #
+      # @api public
+      def write(*args)
+        args.each do |text|
+          send_text(:write, text)
+        end
+        self
+      end
+      alias << write
+
+      # Print a line of text to the pager, prompting on page end.
+      #
+      # @raise [PagerClosed]
+      #   if the pager was closed
+      #
+      # @api public
+      def puts(text)
+        send_text(:puts, text)
       end
 
-      # Page text
+      # Stop the pager, wait for it to clean up
       #
       # @api public
-      def page(text, &callback)
-        page_num = 1
-        leftover = []
-        lines_left = @height
+      def close
+        reset
+        true
+      end
+
+      private
+
+      # Reset internal state
+      #
+      # @api private
+      def reset
+        @page_cursor.reset
+        @leftover = []
+      end
 
+      # Tracks page cursor
+      #
+      # @api private
+      class PageCursor
+        attr_reader :page_num
+
+        def initialize(height)
+          @height = height
+          reset
+        end
+
+        def reset
+          @page_num = 1
+          @lines_left = @height
+        end
+
+        # Move cursor to the next page
+        #
+        # @api public
+        def next_page
+          @page_num += 1
+          @lines_left = @height
+        end
+
+        # Move coursor down the page by count
+        #
+        # @param [Integer] count
+        #
+        # @api public
+        def down_by(count)
+          @lines_left -= count
+        end
+
+        # Check if time to break a page
+        #
+        # @return [Boolean]
+        #
+        # @api private
+        def page_break?
+          @lines_left.zero?
+        end
+      end
+
+      # The lower-level common implementation of printing methods
+      #
+      # @return [Boolean]
+      #   the success status of writing to the screen
+      #
+      # @api private
+      def send_text(write_method, text)
         text.lines.each do |line|
-          chunk = []
-          if !leftover.empty?
-            chunk = leftover
-            leftover = []
-          end
-          wrapped_line = Strings.wrap(line, @width)
-          wrapped_line.lines.each do |line_part|
-            if lines_left > 0
-              chunk << line_part
-              lines_left -= 1
-            else
-              leftover << line_part
-            end
-          end
-          output.print(chunk.join)
-
-          if lines_left == 0
-            break unless continue_paging?(page_num)
-            lines_left = @height
-            if leftover.size > 0
-              lines_left -= leftover.size
-            end
-            page_num += 1
-            return !callback.call(page_num) unless callback.nil?
+          chunk = create_chunk_from(line)
+
+          output.public_send(write_method, chunk)
+
+          next unless @page_cursor.page_break?
+
+          output.puts(page_break_prompt)
+
+          continue_paging?(input)
+
+          next_page
+        end
+
+        if !remaining_content.empty?
+          output.public_send(write_method, remaining_content)
+        end
+      end
+
+      # Convert line to a chunk of text to fit display
+      #
+      # @param [String] line
+      #
+      # @return [String]
+      #
+      # @api private
+      def create_chunk_from(line)
+        chunk = []
+
+        if !@leftover.empty?
+          chunk.concat(@leftover)
+          @leftover.clear
+        end
+
+        Strings.wrap(line, @width).lines.each do |line_part|
+          if !@page_cursor.page_break?
+            chunk << line_part
+            @page_cursor.down_by(1)
+          else
+            @leftover << line_part
           end
         end
 
-        if leftover.size > 0
-          output.print(leftover.join)
+        chunk.join
+      end
+
+      # Any remaining content
+      #
+      # @return [String]
+      #
+      # @api private
+      def remaining_content
+        @leftover.join
+      end
+
+      # Switch over to the next page
+      #
+      # @api private
+      def next_page
+        @page_cursor.next_page
+        if @leftover.size > 0
+          @page_cursor.down_by(@leftover.size)
         end
       end
 
-      private
+      # Dispaly prompt at page break
+      #
+      # @api private
+      def page_break_prompt
+        Strings.wrap(@prompt.call(@page_cursor.page_num), @width)
+      end
+
+      # Check if paging should be continued
+      #
+      # @param [Integer] page
+      #   the page number
+      #
+      # @return [Boolean]
+      #
+      # @api private
+      def continue_paging?(input)
+        if getchar.chomp[/q/i]
+          raise PagerClosed.new("The pager tool was closed")
+        end
+      end
 
+      # Find available character reading method
+      #
       # @api private
-      def continue_paging?(page_num)
-        instance_exec(page_num, &@prompt)
-        !@input.gets.chomp[/q/i]
+      def getchar
+        input.respond_to?(:getch) ? input.getch : input.getc
       end
     end # BasicPager
   end # Pager

data/lib/tty/pager/null.rb

@@ -1,16 +1,35 @@
 # frozen_string_literal: true
 
+require_relative "abstract"
+
 module TTY
-  class Pager
-    class NullPager < Pager
+  module Pager
+    class NullPager < Abstract
+      # Pass output directly to stdout
+      #
+      # @api public
+      def write(text)
+        return text unless output.tty?
+
+        output.write(text)
+      end
+      alias << write
+
       # Pass output directly to stdout
       #
       # @api public
-      def page(text, &callback)
+      def puts(text)
         return text unless output.tty?
 
         output.puts(text)
       end
+
+      # Do nothing, always return success
+      #
+      # @api public
+      def close
+        true
+      end
     end
   end # Pager
 end # TTY