tty-pager 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8dcb93333dbebd8cc1f528d51a3c4e28e39a90840d24b0e85bef6ba99dbee65
-  data.tar.gz: 6b874380df90294f03af9dc7a6c68c078bfcd4a078f31da6a6379fc3b15f8b88
+  metadata.gz: adbdf02c80e21f7b2c2fc7723af3a00d268c8a57bffd321e8ed5126e6b7cc120
+  data.tar.gz: 4ff28aeef0acff9e54343e498e890bb2ffde576b771b4172326ef3dcdda67fc3
 SHA512:
-  metadata.gz: b5e6eae2130ce1d007d86d76c9dac6fa8a023e8d1c9148a5bab0690d65cbcc205d1c6ace4bd4e8053bb25f63875fe24f2c22a926cfeb5fc11571f0ae5ba3e226
-  data.tar.gz: d89926ee6548e078c7036cdb22f2bd398011e8f88b422433db7835e777ac939111fc6ffcfc14247b4376754f2a84ddcb003878ad1ecddd424e8a54de56264449
+  metadata.gz: 5614a278d417950a369489d6480203150da012ea19c1d2e1c564ac989d3f3c32074ce5f7ae61952536ec758f7602512415b63027f891e73b4d96151a6e9b02e4
+  data.tar.gz: ec0c2b331343284877e199e1f1672776e967f58f58b1b608ae73653f84905c6214b30990bb928b3f912f1d345dfce42dcfcc5947fd1fdd4f13330705844accaa

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Change log
 
+## [v0.13.0] - 2020-05-30
+
+### Added
+* Add support for streaming by Andrew Radev(@AndrewRadev)
+* Add SystemPager integration tests by Andrew Radev(@AndrewRadev)
+
+### Changed
+* Change Pager structure and extract TTY::Pager::Abstract for the null, basic and
+  system pagers
+* Change BasicPager paging prompt to return only formatted prompt text and
+  account for terminal height
+* Change BasicPager to quit with a single keystroke
+* Change BasicPager internals to increase readability
+* Change SystemPager#command_exist? to search path
+* Change tests structure for ease of maintenance by Andrew Radev(@AndrewRadev)
+* Change gemspec to add metadata, remove test artefacts and dev dependencies
+* Update strings & tty-screen dependencies
+* Remove tty-which dependency
+
+### Fixed
+* Fix SystemPager to run command test silently via Open3 and thus work on JRuby
+
 ## [v0.12.1] - 2019-03-16
 
 ### Fixed
@@ -106,6 +128,8 @@
 
 * Initial release
 
+[v0.13.0]: https://github.com/piotrmurach/tty-pager/compare/v0.12.1...v0.13.0
+[v0.12.1]: https://github.com/piotrmurach/tty-pager/compare/v0.12.0...v0.12.1
 [v0.12.0]: https://github.com/piotrmurach/tty-pager/compare/v0.11.0...v0.12.0
 [v0.11.0]: https://github.com/piotrmurach/tty-pager/compare/v0.10.0...v0.11.0
 [v0.10.0]: https://github.com/piotrmurach/tty-pager/compare/v0.9.0...v0.10.0

data/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <a href="https://piotrmurach.github.io/tty" target="_blank"><img width="130" src="https://cdn.rawgit.com/piotrmurach/tty/master/images/tty.png" alt="tty logo" /></a>
+  <a href="https://piotrmurach.github.io/tty" target="_blank"><img width="130" src="https://github.com/piotrmurach/tty/raw/master/images/tty.png" alt="tty logo" /></a>
 </div>
 
 # TTY::Pager [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
@@ -19,9 +19,9 @@
 [coverage]: https://coveralls.io/github/piotrmurach/tty-pager
 [inchpages]: http://inch-ci.org/github/piotrmurach/tty-pager
 
-> Terminal output paging in a cross-platform way supporting all major ruby interpreters.
+> A cross-platform terminal pager that works on all major Ruby interpreters.
 
-**TTY::Pager** provides independent terminal output paging component for [TTY](https://github.com/piotrmurach/tty) toolkit.
+**TTY::Pager** provides independent terminal pager component for [TTY](https://github.com/piotrmurach/tty) toolkit.
 
 ## Installation
 
@@ -40,84 +40,286 @@ Or install it yourself as:
 
 ## Overview
 
-The **TTY::Pager** on initialization will choose the best available pager out of `SystemPager`, `BasicPager` or `NullPager`. If paging is disabled then a `NullPager` is used, which either returns text as is or simply prints it out to stdout on tty devices. Otherwise a check is performed to find paging command to page text with `SystemPager`. However, if no paging command is found, a `BasicPager` is used which is a pure Ruby implementation that is guaranteed to work with any ruby interpreter and any platform.
+The **TTY::Pager** will automatically choose the best available pager on a user's system. Failing to do so, it will fallback on a pure Ruby version that is guaranteed to work with any Ruby interpreter and on any platform.
+
+## Contents
+
+* [1. Usage](#1-usage)
+* [2. API](#2-api)
+  * [2.1 new](#21-new)
+    * [2.1.1 :enabled](#211-enabled)
+    * [2.1.2 :command](#212-command)
+    * [2.1.3 :width](#213-width)
+    * [2.1.4 :prompt](#214-prompt)
+  * [2.2 page](#22-page)
+  * [2.3 write](#23-write)
+  * [2.4 try_write](#24-try_write)
+  * [2.5 puts](#25-puts)
+  * [2.6 close](#26-close)
+  * [2.7 ENV](#27-env)
 
 ## 1. Usage
 
-In order to let **TTY::Pager** pick the best paging mechanism automatically do:
+The **TTY::Pager** will pick the best paging mechanism available on your system when initialized:
 
 ```ruby
 pager = TTY::Pager.new
 ```
 
-Then to perform actual content pagination invoke `page` method with the content to paginate as the argument:
+Then to start paginating text call the `page` method with the content as the first argument:
 
 ```ruby
 pager.page("Very long text...")
 ```
 
-If you want to use specific pager you can do so by invoking it directly:
+This will launch a pager in the background and wait until the user is done.
+
+Alternatively, you can pass the `:path` keyword to specify a file path:
+
+```ruby
+pager.page(path: "/path/to/filename.txt")
+```
+
+If instead you'd like to paginate a long-running operation, you could use the block form of the pager:
+
+```ruby
+TTY::Pager.page do |pager|
+  File.open("file_with_lots_of_lines.txt", "r").each_line do |line|
+    # do some work with the line
+
+    pager.write(line) # send it to the pager
+  end
+end
+```
+
+After block finishes, the pager is automatically closed.
+
+For more control, you can translate the block form into separate `write` and `close` calls:
+
+```ruby
+begin
+  pager = TTY::Pager.new
+
+  File.open("file_with_lots_of_lines.txt", "r").each_line do |line|
+    # do some work with the line
+
+    pager.write(line) # send it to the pager
+  end
+rescue TTY::Pager::PagerClosed
+  # the user closed the paginating tool
+ensure
+  pager.close
+end
+```
+
+If you want to use a specific pager you can do so by invoking it directly:
 
 ```ruby
 pager = TTY::Pager::BasicPager.new
+# or
+pager = TTY::Pager::SystemPager.new
+# or
+pager = TTY::Pager::NullPager.new
 ```
 
-## 2. Interface
+## 2. API
+
+### 2.1 new
+
+The `TTY::Pager` can be configured during initialization for terminal width, type of prompt when basic pager is invoked, and the pagination command to run.
+
+For example, to disable a pager in CI you could do:
+
+```ruby
+pager = TTY::Pager.new(enabled: false)
+````
 
-### :enabled
+#### 2.1.1 :enabled
 
-If you want to disable the pager pass the `:enabled` option set to `false`:
+If you want to disable the paging use the `:enabled` option set to `false`:
 
 ```ruby
 pager = TTY::Pager.new(enabled: false)
 ```
 
-### :width
+This will directly print all the content to the standard output. If the output isn't a tty device, the pager will return the content directly to the caller.
 
-The `BasicPager` allows to wrap content at given width:
+#### 2.1.2 :command
+
+To force `TTY::Pager` to always use a specific paging tool(s), use the `:command` option:
+
+```ruby
+TTY::Pager.new(command: "less -R")
+```
+
+The `:command` also accepts an array of pagers to use:
+
+```ruby
+pager = TTY::Pager.new(command: ["less -r", "more -r"])
+```
+
+If the provided pager command or commands don't exist on user's system, the pager will fallback automatically on a basic Ruby implementation.
+
+To skip automatic detection of pager and always use a system pager do:
+
+```ruby
+TTY::Pager::SystemPager.new(command: "less -R")
+```
+
+#### 2.1.3 :width
+
+Only the `BasicPager` allows you to wrap content at given terminal width:
 
 ```ruby
 pager = TTY::Pager.new(width: 80)
+```
+
+This option doesn't affect the `SystemPager`.
+
+To directly use `BasicPager` do:
+
+```ruby
 pager = TTY::Pager::BasicPager.new(width: 80)
 ```
 
-### :prompt
+#### 2.1.4 :prompt
+
+To change the `BasicPager` page break prompt display, use the `:prompt` option:
+
+```ruby
+prompt = -> (page) { "Page -#{page_num}- Press enter to continue" }
+pager = TTY::Pager.new(prompt: prompt)
+```
+
+### 2.2 page
+
+To start paging use the `page` method. It can be invoked on an instance or a class.
+
+The class-level `page` is a convenient shortcut. To page some text you only need to do:
+
+```ruby
+TTY::Pager.page("Some long text...")
+````
+
+You can also include extra initialization parameters. For example, if you prefer to use a specific command do this:
+
+```ruby
+TTY::Pager.page("Some long text...", command: "less -R")
+````
+
+The instance equivalent would be:
+
+```ruby
+pager = TTY::Pager.new(command: "less -R")
+pager.page("Some long text...")
+````
+
+Apart from text, you can page file content by passing the `:path` option:
+
+```ruby
+TTY::Pager.page(path: "/path/to/filename.txt")
+````
+
+The final way is to use the class-level `page` with a block. After the block is done, the pager is automatically closed. For example, to read a file line by line with additional processing you could do:
+
+```ruby
+TTY::Pager.page do |pager|
+  File.foreach("filename.txt") do |line|
+    # do some work with the line
+
+    pager.write(line) # write line to the pager
+  end
+end
+```
+
+The instance equivalent of the block version would be:
+
+```ruby
+pager = TTY::Pager.new
+begin
+  File.foreach("filename.txt") do |line|
+    # do some work with the line
+
+    pager.write(line) # write line to the pager
+  end
+rescue TTY::Pager::PagerClosed
+ensure
+  pager.close
+end
+```
+
+### 2.3 write
+
+To stream content to the pager use the `write` method.
+
+```ruby
+pager.write("Some text")
+```
 
-For the `BasicPager` you can pass a `:prompt` option to change the page break text:
+You can pass in any number of arguments:
 
 ```ruby
-prompt = -> (page_num) { output.puts "Page -#{page_num}- Press enter to continue" }
-pager = TTY::Pager::BasicPager.new(prompt: prompt)
+pager.write("one", "two", "three")
 ```
 
-### :command
+### 2.4 try_write
 
-You can force `SystemPager` to always use a specific paging tool(s) by passing the `:command` option:
+To check if a write has been successful use `try_write`:
 
 ```ruby
-TTY::Pager.new(command: 'less -R')
-TTY::Pager::SystemPager.new(command: 'less -R')
+pager.try_write("Some text")
+# => true
 ```
 
-You also specify an array of pagers to use:
+### 2.5 puts
+
+To write a line of text and end it with a new line use `puts` call:
 
 ```ruby
-pager = TTY::Pager.new(command: ['less -r', 'more -r'])
+pager.puts("Single line of content")
 ```
 
-### PAGER
+### 2.6 close
+
+When you're done streaming content manually use `close` to finish paging.
 
-By default the `SystemPager` will check the `PAGER` environment variable, if not set it will try one of the `less`, `more`, `cat`, `pager`. Therefore, if you wish to set your preferred pager you can either set up your shell like so:
+All interactions with a pager can raise an exception for various reasons, so wrap your code using the following pattern:
+
+```ruby
+pager = TTY::Pager.new
+
+begin
+  # ... perform pager writes
+rescue TTY::Pager::PagerClosed
+  # the user closed the paginating tool
+ensure
+  pager.close
+end
+```
+
+Alternatively use the class-level `page` call with a block to automatically close the pager:
+
+```ruby
+TTY::Pager.page do |pager|
+  # ... perform pager writes
+end
+```
+
+### 2.7 ENV
+
+By default the `SystemPager` will check the `PAGER` environment variable. If the `PAGER` isn't set, the pager will try one of the searched commands like `less`, `more` or `pg`.
+
+Therefore, if you wish to set your preferred pager you can either set up your shell like so:
 
 ```bash
-PAGER=less
+PAGER=less -R
 export PAGER
 ```
 
-or set `PAGER` in Ruby script:
+Or set `PAGER` in Ruby script:
 
 ```ruby
-ENV['PAGER']='less'
+ENV["PAGER"]="less -R"
 ```
 
 ## Contributing
@@ -130,6 +332,10 @@ Bug reports and pull requests are welcome on GitHub at https://github.com/piotrm
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create a new Pull Request
 
+## Code of Conduct
+
+Everyone interacting in the TTY::Pager project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/piotrmurach/tty-pager/blob/master/CODE_OF_CONDUCT.md).
+
 ## Copyright
 
 Copyright (c) 2015 Piotr Murach. See LICENSE for further details.

data/lib/tty-pager.rb

@@ -1 +1 @@
-require_relative 'tty/pager'
+require_relative "tty/pager"

data/lib/tty/pager.rb

@@ -1,103 +1,101 @@
 # frozen_string_literal: true
 
-require 'tty-screen'
-
-require_relative 'pager/basic'
-require_relative 'pager/null'
-require_relative 'pager/system'
-require_relative 'pager/version'
+require_relative "pager/basic"
+require_relative "pager/null"
+require_relative "pager/system"
+require_relative "pager/version"
 
 module TTY
-  class Pager
+  module Pager
     Error = Class.new(StandardError)
 
-    # 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.
-    #
-    # @api private
-    def self.select_pager(enabled, commands)
-      if !enabled
-        NullPager
-      elsif SystemPager.exec_available?(*commands)
-        SystemPager
-      else
-        BasicPager
-      end
-    end
+    # Raised when pager is closed
+    PagerClosed = Class.new(Error)
 
-    # 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 }
-      commands = Array(options[:command])
+    # Raised when user provides unnexpected argument
+    InvalidArgument = Class.new(Error)
 
-      if self.class == TTY::Pager
-        @pager = self.class.select_pager(@enabled, commands).new(options)
+    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
-    end
-
-    # Check if pager is enabled
-    #
-    # @return [Boolean]
-    #
-    # @api public
-    def enabled?
-      !!@enabled
-    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
+    private_class_method :select_pager
   end # Pager
 end # TTY