tty-pager 0.12.1 → 0.13.0

data/lib/tty/pager/system.rb

@@ -1,18 +1,20 @@
 # 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
+    class SystemPager < Abstract
       # Check if command exists
       #
       # @example
-      #   command_exists?('less) # => true
+      #   command_exist?("less") # => true
       #
       # @param [String] command
       #   the command to check
@@ -20,46 +22,59 @@ module TTY
       # @return [Boolean]
       #
       # @api private
-      def self.command_exists?(command)
-        TTY::Which.exist?(command)
+      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
 
       # Run pager command silently with no input and capture output
       #
-      # @return [nil, String]
-      #   command output or nil if command fails to run
+      # @return [Boolean]
+      #   true if command runs successfully, false otherwise
       #
       # @api private
       def self.run_command(*args)
-        require 'tempfile'
-        out = Tempfile.new('tty-pager')
-        result = system(*args, out: out.path, err: out.path, in: ::File::NULL)
-        return if result.nil?
-        out.rewind
-        out.read
-      ensure
-        out.close
-        out.unlink
+        _, 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'],
-         command_exists?('git') ? `git config --get-all core.pager` : nil,
-         'less -r', 'more -r', 'most', 'cat', 'pager', 'pg'].compact
+        [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
-      #   find_executable # => 'less'
+      #   find_executable # => "less"
       #
       # @example Usage with commands
-      #   find_executable('less', 'cat')  # => 'less'
+      #   find_executable("less", "cat")  # => "less"
       #
       # @param [Array[String]] commands
       #
@@ -71,7 +86,7 @@ module TTY
         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
@@ -80,7 +95,7 @@ module TTY
       #   available?  # => true
       #
       # @example Usage with command
-      #   available?('less') # => true
+      #   available?("less") # => true
       #
       # @return [Boolean]
       #
@@ -91,60 +106,73 @@ module TTY
 
       # Create a system pager
       #
-      # @param [Hash] options
-      # @option options [String] :command
+      # @param [String] :command
       #   the command to use for paging
       #
       # @api public
-      def initialize(**options)
-        super
+      def initialize(command: nil, **options)
+        super(**options)
+        @pager_io = nil
         @pager_command = nil
-        commands = Array(options[:command])
-        pager_command(*commands)
-
-        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." \
+        pager_command(*Array(command))
+
+        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
 
-      # Use system command to page output text
+      # Send text to the pager process. Starts a new process if it hasn't been
+      # started yet.
       #
-      # @example
-      #   page('some long text...')
+      # @param [Array<String>] *args
+      #   strings to send to the pager
       #
-      # @param [String] text
-      #   the text to paginate
-      #
-      # @return [Boolean]
-      #   the success status of launching a process
+      # @raise [PagerClosed]
+      #   strings to send to the pager
       #
       # @api public
-      def page(text, &_callback)
-        return text unless output.tty?
-
-        command = pager_command
-        out = self.class.run_command(command)
-        # Issue running command, e.g. unsupported flag, fallback to just command
-        if !out.empty?
-          command = pager_command.split.first
-        end
+      def write(*args)
+        @pager_io ||= spawn_pager
+        @pager_io.write(*args)
+        self
+      end
+      alias << write
 
-        pager_io = open("|#{command}", 'w')
-        pid      = pager_io.pid
+      # Send a line of text, ending in a newline, to the pager process. Starts
+      # a new process if it hasn't been started yet.
+      #
+      # @raise [PagerClosed]
+      #   if the pager was closed
+      #
+      # @return [SystemPager]
+      #
+      # @api public
+      def puts(text)
+        @pager_io ||= spawn_pager
+        @pager_io.puts(text)
+        self
+      end
 
-        pager_io.write(text)
-        pager_io.close
+      # 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 public
+      def close
+        return true unless @pager_io
 
-        _, status = Process.waitpid2(pid, Process::WNOHANG)
-        status.success?
-      rescue Errno::ECHILD
-        # on jruby 9x waiting on pid raises
-        true
+        success = @pager_io.close
+        @pager_io = nil
+        success
       end
 
+      private
+
       # The pager command to run
       #
       # @return [String]
@@ -152,11 +180,70 @@ module TTY
       #
       # @api private
       def pager_command(*commands)
-        @pager_command = if @pager_command && commands.empty?
-                           @pager_command
-                         else
-                           self.class.find_executable(*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 @@
 # frozen_string_literal: true
 
 module TTY
-  class Pager
-    VERSION = '0.12.1'
+  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.12.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Piotr Murach
 autorequire: 
-bindir: bin
+bindir: exe
 cert_chain: []
-date: 2019-03-16 00:00:00.000000000 Z
+date: 2020-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: tty-screen
@@ -16,56 +16,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
-- !ruby/object:Gem::Dependency
-  name: tty-which
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.4'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '0.4'
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: strings
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.4
+        version: 0.1.8
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.1.4
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.1.8
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -84,55 +56,46 @@ dependencies:
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.6'
+        version: '3.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '3.6'
-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:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
-- Rakefile
-- examples/basic_pager.rb
-- examples/markdown.rb
-- examples/pager.rb
-- examples/system_pager.rb
 - 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/command_exists_spec.rb
-- spec/unit/system/executables_spec.rb
-- spec/unit/system/find_executable_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://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:
@@ -148,19 +111,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.3
+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/command_exists_spec.rb
-- spec/unit/system/executables_spec.rb
-- spec/unit/system/find_executable_spec.rb
-- spec/unit/system/new_spec.rb
-- spec/unit/system/page_spec.rb
+summary: A cross-platform terminal pager that works on all major Ruby interpreters.
+test_files: []