tty-pager 0.9.0 → 0.13.0

data/lib/tty-pager.rb

@@ -1,3 +1 @@
-# coding: utf-8
-
-require_relative 'tty/pager'
+require_relative "tty/pager"

data/lib/tty/pager.rb

@@ -1,6 +1,4 @@
-# coding: utf-8
-
-require 'tty-screen'
+# frozen_string_literal: true
 
 require_relative "pager/basic"
 require_relative "pager/null"
@@ -8,95 +6,96 @@ require_relative "pager/system"
 require_relative "pager/version"
 
 module TTY
-  class Pager
+  module Pager
     Error = Class.new(StandardError)
 
-    # Create a pager
-    #
-    # @param [Hash] options
-    # @option options [Proc] :prompt
-    #   a proc object that accepts page number
-    # @option options [IO] :input
-    #   the object to send input to
-    # @option options [IO] :output
-    #   the object to send output to
-    # @option options [Boolean] :enabled
-    #   disable/enable text paging
-    #
-    # @api public
-    def initialize(options = {})
-      @input   = options.fetch(:input)  { $stdin }
-      @output  = options.fetch(:output) { $stdout }
-      @enabled = options.fetch(:enabled) { true }
+    # Raised when pager is closed
+    PagerClosed = Class.new(Error)
 
-      if self.class == TTY::Pager
-        @pager = find_available(options)
-      end
-    end
+    # Raised when user provides unnexpected argument
+    InvalidArgument = Class.new(Error)
 
-    # Check if pager is enabled
-    #
-    # @return [Boolean]
-    #
-    # @api public
-    def enabled?
-      !!@enabled
-    end
+    module ClassMethods
+      # Create a pager
+      #
+      # @param [Boolean] :enabled
+      #   disable/enable text paging
+      # @param [String] :command
+      #   the paging command
+      # @param [IO] :input
+      #   the object to send input to
+      # @param [IO] :output
+      #   the object to send output to
+      # @param [Proc] :prompt
+      #   a proc object that accepts page number
+      # @param [Integer] :width
+      #   the terminal width
+      # @param [Integer] :height
+      #   the terminal height
+      #
+      # @api public
+      def new(enabled: true, command: nil, **options)
+        select_pager(enabled: enabled, command: command).new(
+          enabled: enabled, command: command, **options)
+      end
 
-    # Page the given text through the available pager
-    #
-    # @param [String] text
-    #   the text to run through a pager
-    #
-    # @yield [Integer] page number
-    #
-    # @return [TTY::Pager]
-    #
-    # @api public
-    def page(text, &callback)
-      pager.page(text, &callback)
-      self
-    end
+      # Paginate content through null, basic or system pager.
+      #
+      # @example
+      #   TTY::Pager.page do |pager|
+      #     pager.write "some text"
+      #   end
+      #
+      # @param [String] :text
+      #   an optional blob of content
+      # @param [String] :path
+      #   a path to a file
+      # @param [Boolean] :enabled
+      #   whether or not to use null pager
+      # @param [String] :command
+      #   the paging command
+      # @param [IO] :input
+      #   the object to send input to
+      # @param [IO] :output
+      #   the object to send output to
+      #
+      # @api public
+      def page(text = nil, path: nil, enabled: true, command: nil,
+               **options, &block)
+        select_pager(enabled: enabled, command: command).
+          page(text, path: path, enabled: enabled, command: command,
+               **options, &block)
+      end
 
-    # The terminal height
-    #
-    # @api public
-    def page_height
-      TTY::Screen.height
-    end
+      # Select an appriopriate pager
+      #
+      # If the user disabled paging then a NullPager is returned,
+      # otherwise a check is performed to find native system
+      # command to perform pagination with SystemPager. Finally,
+      # if no system command is found, a BasicPager is used which
+      # is a pure Ruby implementation known to work on any platform.
+      #
+      # @param [Boolean] enabled
+      #   whether or not to allow paging
+      # @param [String] command
+      #   the command to run if available
+      #
+      # @api private
+      def select_pager(enabled: true, command: nil)
+        commands = Array(command)
 
-    # The terminal width
-    #
-    # @api public
-    def page_width
-      TTY::Screen.width
+        if !enabled
+          NullPager
+        elsif SystemPager.exec_available?(*commands)
+          SystemPager
+        else
+          BasicPager
+        end
+      end
     end
 
-    protected
-
-    attr_reader :output
-
-    attr_reader :input
+    extend ClassMethods
 
-    attr_reader :pager
-
-    # Find available pager
-    #
-    # If the user disabled paging then a NullPager is returned,
-    # otherwise a check is performed to find native system
-    # command to perform pagination with SystemPager. Finally,
-    # if no system command is found, a BasicPager is used which
-    # is a pure Ruby implementation known to work on any platform.
-    #
-    # @api private
-    def find_available(options)
-      if !enabled?
-        NullPager.new
-      elsif SystemPager.available?
-        SystemPager.new(options)
-      else
-        BasicPager.new(options)
-      end
-    end
+    private_class_method :select_pager
   end # Pager
 end # TTY

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,92 +1,234 @@
-# encoding: utf-8
 # frozen_string_literal: true
 
-require 'verse'
+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 " \
-                    "(or q to quit) ---".freeze
+    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 Verse.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 = Verse.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