tty-pager 0.9.0 → 0.13.0

data/lib/tty/pager/null.rb

@@ -1,17 +1,35 @@
-# encoding: utf-8
 # 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

data/lib/tty/pager/system.rb

@@ -1,51 +1,92 @@
-# encoding: utf-8
 # frozen_string_literal: true
 
-require 'tty-which'
+require "open3"
+
+require_relative "abstract"
 
 module TTY
-  class Pager
+  module Pager
     # A system pager is used  on systems where native
     # pagination exists
     #
     # @api public
-    class SystemPager < Pager
-      # Create a system pager
+    class SystemPager < Abstract
+      # Check if command exists
       #
-      # @param [Hash] options
-      # @option options [String] :command
-      #   the command to use for paging
+      # @example
+      #   command_exist?("less") # => true
       #
-      # @api public
-      def initialize(options = {})
-        super
-        @pager_command = options[:command]
-        unless self.class.available?
-          raise TTY::Pager::Error, "#{self.class.name} cannot be used on your" \
-                                   " system due to lack of appropriate pager" \
-                                   " executable. Install `less` like pager or" \
-                                   " try using `BasicPager` instead." \
+      # @param [String] command
+      #   the command to check
+      #
+      # @return [Boolean]
+      #
+      # @api private
+      def self.command_exist?(command)
+        exts = ENV.fetch("PATHEXT", "").split(::File::PATH_SEPARATOR)
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |dir|
+          file = ::File.join(dir, command)
+          ::File.exist?(file) || exts.any? { |ext| ::File.exist?("#{file}#{ext}") }
         end
       end
 
-      # Find first available system command for paging
+      # Run pager command silently with no input and capture output
+      #
+      # @return [Boolean]
+      #   true if command runs successfully, false otherwise
+      #
+      # @api private
+      def self.run_command(*args)
+        _, err, status = Open3.capture3(*args)
+        err.empty? && status.success?
+      rescue Errno::ENOENT
+        false
+      end
+
+      # List possible executables for output paging
+      #
+      # The UNIX systems often come with "pg" and "more" but no "less" utility.
+      # The Linux usually provides "less" and "more" pager, but often no "pg".
+      # MacOS comes with "less" and "more" pager and no "pg".
+      # Windows provides "more".
+      # The "more" pager is the oldest utility and thus most compatible
+      # with many systems.
+      #
+      # @return [Array[String]]
+      #
+      # @api private
+      def self.executables
+        [ENV["GIT_PAGER"], ENV["PAGER"], git_pager,
+         "less -r", "more -r", "most", "pg", "cat", "pager"].compact
+      end
+
+      # Finds git pager configuration
+      #
+      # @api private
+      def self.git_pager
+        command_exist?("git") ? `git config --get-all core.pager` : nil
+      end
+      private_class_method :git_pager
+
+      # Find first available termainal pager program executable
       #
       # @example Basic usage
-      #   available # => 'less'
+      #   find_executable # => "less"
       #
       # @example Usage with commands
-      #   available('less', 'cat')  # => 'less'
+      #   find_executable("less", "cat")  # => "less"
       #
       # @param [Array[String]] commands
       #
-      # @return [String]
+      # @return [String, nil]
+      #   the found executable or nil when not found
       #
       # @api public
-      def self.available(*commands)
-        commands = commands.empty? ? executables : commands
-        commands
+      def self.find_executable(*commands)
+        execs = commands.empty? ? executables : commands
+        execs
           .compact.map(&:strip).reject(&:empty?).uniq
-          .find { |cmd| command_exists?(cmd.split.first) }
+          .find { |cmd| command_exist?(cmd.split.first) }
       end
 
       # Check if command is available
@@ -54,72 +95,84 @@ module TTY
       #   available?  # => true
       #
       # @example Usage with command
-      #   available?('less') # => true
+      #   available?("less") # => true
       #
       # @return [Boolean]
       #
       # @api public
-      def self.available?(*commands)
-        !available(*commands).nil?
+      def self.exec_available?(*commands)
+        !find_executable(*commands).nil?
       end
 
-      # Use system command to page output text
-      #
-      # @example
-      #   page('some long text...')
-      #
-      # @param [String] text
-      #   the text to paginate
+      # Create a system pager
       #
-      # @return [Boolean]
-      #   the success status of launching a process
+      # @param [String] :command
+      #   the command to use for paging
       #
       # @api public
-      def page(text, &callback)
-        return text unless output.tty?
+      def initialize(command: nil, **options)
+        super(**options)
+        @pager_io = nil
+        @pager_command = nil
+        pager_command(*Array(command))
 
-        write_io = open("|#{pager_command}", 'w')
-        pid      = write_io.pid
-
-        write_io.write(text)
-        write_io.close
-
-        _, status = Process.waitpid2(pid, Process::WNOHANG)
-        status.success?
-      rescue Errno::ECHILD
-        # on jruby 9x waiting on pid raises
-        true
+        if pager_command.nil?
+          raise TTY::Pager::Error,
+                "#{self.class.name} cannot be used on your system due to " \
+                "lack of appropriate pager executable. Install `less` like " \
+                "pager or try using `BasicPager` instead."
+        end
       end
 
-      private
-
-      # List possible executables for output paging
+      # Send text to the pager process. Starts a new process if it hasn't been
+      # started yet.
       #
-      # @return [Array[String]]
+      # @param [Array<String>] *args
+      #   strings to send to the pager
       #
-      # @api private
-      def self.executables
-        [ENV['GIT_PAGER'], ENV['PAGER'],
-         `git config --get-all core.pager`,
-         'less', 'more', 'cat', 'pager']
+      # @raise [PagerClosed]
+      #   strings to send to the pager
+      #
+      # @api public
+      def write(*args)
+        @pager_io ||= spawn_pager
+        @pager_io.write(*args)
+        self
       end
-      private_class_method :executables
+      alias << write
 
-      # Check if command exists
+      # Send a line of text, ending in a newline, to the pager process. Starts
+      # a new process if it hasn't been started yet.
       #
-      # @example
-      #   command_exists?('less) # => true
+      # @raise [PagerClosed]
+      #   if the pager was closed
       #
-      # @param [String] command
-      #   the command to check
+      # @return [SystemPager]
+      #
+      # @api public
+      def puts(text)
+        @pager_io ||= spawn_pager
+        @pager_io.puts(text)
+        self
+      end
+
+      # Stop the pager, wait for the process to finish. If no pager has been
+      # started, returns true.
       #
       # @return [Boolean]
+      #   the exit status of the child process
       #
-      # @api private
-      def self.command_exists?(command)
-        TTY::Which.exist?(command)
+      # @api public
+      def close
+        return true unless @pager_io
+
+        success = @pager_io.close
+        @pager_io = nil
+        success
       end
 
+      private
+
       # The pager command to run
       #
       # @return [String]
@@ -127,11 +180,70 @@ module TTY
       #
       # @api private
       def pager_command(*commands)
-        @pager_command = if @pager_command && commands.empty?
-                           @pager_command
-                         else
-                           self.class.available(*commands)
-                         end
+        if @pager_command && commands.empty?
+          @pager_command
+        else
+          @pager_command = self.class.find_executable(*commands)
+        end
+      end
+
+      # Spawn the pager process
+      #
+      # @return [PagerIO]
+      #   A wrapper for the external pager
+      #
+      # @api private
+      def spawn_pager
+        # In case there's a previous pager running:
+        close
+
+        command = pager_command
+        status = self.class.run_command(command)
+        # Issue running command, e.g. unsupported flag, fallback to just command
+        unless status
+          command = pager_command.split.first
+        end
+
+        PagerIO.new(command)
+      end
+
+      # A wrapper for an external process.
+      #
+      # @api private
+      class PagerIO
+        def initialize(command)
+          @command = command
+          @io      = IO.popen(@command, "w")
+          @pid     = @io.pid
+        end
+
+        def write(*args)
+          io_call(:write, *args)
+        end
+
+        def puts(*args)
+          io_call(:puts, *args)
+        end
+
+        def close
+          return true if @io.closed?
+
+          @io.close
+          _, status = Process.waitpid2(@pid, Process::WNOHANG)
+          status.success?
+        rescue Errno::ECHILD, Errno::EPIPE
+          # on jruby 9x waiting on pid raises ECHILD
+          # on ruby 2.5/2.6, closing a closed pipe raises EPIPE
+          true
+        end
+
+        private
+
+        def io_call(method_name, *args)
+          @io.public_send(method_name, *args)
+        rescue Errno::EPIPE
+          raise PagerClosed.new("The pager process (`#{@command}`) was closed")
+        end
       end
     end # SystemPager
   end # Pager

data/lib/tty/pager/version.rb

@@ -1,7 +1,7 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 module TTY
-  class Pager
-    VERSION = "0.9.0"
+  module Pager
+    VERSION = "0.13.0"
   end # Pager
 end # TTY

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tty-pager
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Piotr Murach
 autorequire: 
-bindir: bin
+bindir: exe
 cert_chain: []
-date: 2017-08-18 00:00:00.000000000 Z
+date: 2020-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tty-screen
@@ -16,62 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.0
+        version: '0.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.5.0
+        version: '0.8'
 - !ruby/object:Gem::Dependency
-  name: tty-which
+  name: strings
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
+        version: 0.1.8
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.3.0
-- !ruby/object:Gem::Dependency
-  name: verse
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.5.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.5.0
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.5.0
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 1.5.0
-    - - "<"
-      - !ruby/object:Gem::Version
-        version: '2.0'
+        version: 0.1.8
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -90,59 +56,46 @@ dependencies:
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 3.6.0
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 3.6.0
-description: Terminal output paging in a cross-platform way supporting all major ruby
-  interpreters.
+        version: '3.0'
+description: A cross-platform terminal pager that works on all major Ruby interpreters.
 email:
-- ''
+- piotr@piotrmurach.com
 executables: []
 extensions: []
-extra_rdoc_files: []
+extra_rdoc_files:
+- README.md
+- CHANGELOG.md
+- LICENSE.txt
 files:
-- ".gitignore"
-- ".rspec"
-- ".travis.yml"
 - CHANGELOG.md
-- CODE_OF_CONDUCT.md
-- Gemfile
 - LICENSE.txt
 - README.md
-- Rakefile
-- appveyor.yml
-- examples/basic_pager.rb
-- examples/system_pager.rb
-- examples/temp.txt
 - lib/tty-pager.rb
 - lib/tty/pager.rb
+- lib/tty/pager/abstract.rb
 - lib/tty/pager/basic.rb
 - lib/tty/pager/null.rb
 - lib/tty/pager/system.rb
 - lib/tty/pager/version.rb
-- spec/spec_helper.rb
-- spec/unit/basic/page_spec.rb
-- spec/unit/null/page_spec.rb
-- spec/unit/page_spec.rb
-- spec/unit/system/available_spec.rb
-- spec/unit/system/command_exists_spec.rb
-- spec/unit/system/new_spec.rb
-- spec/unit/system/page_spec.rb
-- tasks/console.rake
-- tasks/coverage.rake
-- tasks/spec.rake
-- tty-pager.gemspec
-homepage: https://github.com/piotrmurach/tty-pager
+homepage: https://piotrmurach.github.io/tty
 licenses:
 - MIT
-metadata: {}
+metadata:
+  allowed_push_host: https://rubygems.org
+  bug_tracker_uri: https://github.com/piotrmurach/tty-pager/issues
+  changelog_uri: https://github.com/piotrmurach/tty-pager/blob/master/CHANGELOG.md
+  documentation_uri: https://www.rubydoc.info/gems/tty-pager
+  homepage_uri: https://piotrmurach.github.io/tty
+  source_code_uri: https://github.com/piotrmurach/tty-pager
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -151,26 +104,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 2.0.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.5.1
+rubygems_version: 3.1.2
 signing_key: 
 specification_version: 4
-summary: Terminal output paging in a cross-platform way supporting all major ruby
-  interpreters.
-test_files:
-- spec/spec_helper.rb
-- spec/unit/basic/page_spec.rb
-- spec/unit/null/page_spec.rb
-- spec/unit/page_spec.rb
-- spec/unit/system/available_spec.rb
-- spec/unit/system/command_exists_spec.rb
-- spec/unit/system/new_spec.rb
-- spec/unit/system/page_spec.rb
-has_rdoc: 
+summary: A cross-platform terminal pager that works on all major Ruby interpreters.
+test_files: []