tty-pager 0.9.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: e2c1947e24364321ab077aa4a9426654ecba831c
-  data.tar.gz: 86a316d617688d3e644802748ab991bd599eb8fd
+SHA256:
+  metadata.gz: adbdf02c80e21f7b2c2fc7723af3a00d268c8a57bffd321e8ed5126e6b7cc120
+  data.tar.gz: 4ff28aeef0acff9e54343e498e890bb2ffde576b771b4172326ef3dcdda67fc3
 SHA512:
-  metadata.gz: 5d4a40162a5d370d66f70f6967e21b088ca09e7fc4b213d9b190e169b1111cf8cf2d37d0db421ad39372629f1213814ad6b6ceb524ee06a3c360bb6bee2865a2
-  data.tar.gz: 9258e5ecba6052965b5336a932e38140c6bcb64d8ceffb8220ca73d131f331ab1752ac6a3b82ee29a6fece8cbc960036dd1501abc955563bbeb84999e92d66a7
+  metadata.gz: 5614a278d417950a369489d6480203150da012ea19c1d2e1c564ac989d3f3c32074ce5f7ae61952536ec758f7602512415b63027f891e73b4d96151a6e9b02e4
+  data.tar.gz: ec0c2b331343284877e199e1f1672776e967f58f58b1b608ae73653f84905c6214b30990bb928b3f912f1d345dfce42dcfcc5947fd1fdd4f13330705844accaa

data/CHANGELOG.md

@@ -1,5 +1,67 @@
 # 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
+* Fix exception when use tty-pager with tty-file by @tiev
+
+## [v0.12.0] - 2018-12-09
+
+### Added
+* Add SystemPager#run_command for running pager command silently and capturing output
+
+### Changed
+* Change SystemPager#new to allow specifying more than one custom command
+* Change SystemPager#page to check if pager command can be run with flags before paging content
+* Change to update tty-screen and tty-which dependencies
+
+### Fixed
+* Fix SystemPager to page content with ANSI codes
+
+## [v0.11.0] - 2018-01-11
+
+### Added
+* Add `pg` and `most` to executables lookup
+
+### Changed
+* Change verse to strings dependency
+* Change SystemPager to make all class methods public
+* Change SystemPager#available to #find_executable
+* Change SystemPager#available? to #exec_available
+* Change Pager#find_available to #select_pager and make class method
+
+### Fixed
+* Fix Pager throwing exception if git is not installed by Katelyn Schiesser(@slowbro)
+
+## [v0.10.0] - 2017-10-29
+
+### Changed
+* Change tty-screen dependency version
+* Change gemspec to require Ruby >= 2.0.0
+* Remove encoding comments
+
 ## [v0.9.0] - 2017-08-18
 
 ### Changed
@@ -62,13 +124,22 @@
 ### Changed
 * Change SystemPager to correctly paginate inside a process.
 
-[v0.9.0]: https://github.com/peter-murach/tty-prompt/compare/v0.8.0...v0.9.0
-[v0.8.0]: https://github.com/peter-murach/tty-prompt/compare/v0.7.1...v0.8.0
-[v0.7.1]: https://github.com/peter-murach/tty-prompt/compare/v0.7.0...v0.7.1
-[v0.7.0]: https://github.com/peter-murach/tty-prompt/compare/v0.6.0...v0.7.0
-[v0.6.0]: https://github.com/peter-murach/tty-prompt/compare/v0.5.0...v0.6.0
-[v0.5.0]: https://github.com/peter-murach/tty-prompt/compare/v0.4.0...v0.5.0
-[v0.4.0]: https://github.com/peter-murach/tty-prompt/compare/v0.3.0...v0.4.0
-[v0.3.0]: https://github.com/peter-murach/tty-prompt/compare/v0.2.0...v0.3.0
-[v0.2.0]: https://github.com/peter-murach/tty-prompt/compare/v0.1.0...v0.2.0
-[v0.1.0]: https://github.com/peter-murach/tty-prompt/compare/v0.1.0
+### [v0.1.0] - 2015-05-31
+
+* 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
+[v0.9.0]: https://github.com/piotrmurach/tty-pager/compare/v0.8.0...v0.9.0
+[v0.8.0]: https://github.com/piotrmurach/tty-pager/compare/v0.7.1...v0.8.0
+[v0.7.1]: https://github.com/piotrmurach/tty-pager/compare/v0.7.0...v0.7.1
+[v0.7.0]: https://github.com/piotrmurach/tty-pager/compare/v0.6.0...v0.7.0
+[v0.6.0]: https://github.com/piotrmurach/tty-pager/compare/v0.5.0...v0.6.0
+[v0.5.0]: https://github.com/piotrmurach/tty-pager/compare/v0.4.0...v0.5.0
+[v0.4.0]: https://github.com/piotrmurach/tty-pager/compare/v0.3.0...v0.4.0
+[v0.3.0]: https://github.com/piotrmurach/tty-pager/compare/v0.2.0...v0.3.0
+[v0.2.0]: https://github.com/piotrmurach/tty-pager/compare/v0.1.0...v0.2.0
+[v0.1.0]: https://github.com/piotrmurach/tty-pager/compare/v0.1.0

data/README.md

@@ -1,8 +1,13 @@
+<div align="center">
+  <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]
+
 [![Gem Version](https://badge.fury.io/rb/tty-pager.svg)][gem]
 [![Build Status](https://secure.travis-ci.org/piotrmurach/tty-pager.svg?branch=master)][travis]
 [![Build status](https://ci.appveyor.com/api/projects/status/3auc1vi3mk5puqai?svg=true)][appveyor]
-[![Code Climate](https://codeclimate.com/github/piotrmurach/tty-pager/badges/gpa.svg)][codeclimate]
+[![Maintainability](https://api.codeclimate.com/v1/badges/636da0d02231b7f3e50f/maintainability)][codeclimate]
 [![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-pager/badge.svg)][coverage]
 [![Inline docs](http://inch-ci.org/github/piotrmurach/tty-pager.svg?branch=master)][inchpages]
 
@@ -10,13 +15,13 @@
 [gem]: http://badge.fury.io/rb/tty-pager
 [travis]: http://travis-ci.org/piotrmurach/tty-pager
 [appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-pager
-[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-pager
+[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-pager/maintainability
 [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
 
@@ -35,77 +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
 
-### :enabled
+### 2.1 new
 
-If you want to disable the pager pass the `:enabled` option set to `false`:
+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)
+````
+
+#### 2.1.1 :enabled
+
+If you want to disable the paging use the `:enabled` option set to `false`:
 
 ```ruby
-pager = TTY::Pager.new enabled: false
+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.
+
+#### 2.1.2 :command
 
-The `BasicPager` allows to wrap content at given width:
+To force `TTY::Pager` to always use a specific paging tool(s), use the `:command` option:
 
 ```ruby
-pager = TTY::Pager::BasicPager.new width: 80
+TTY::Pager.new(command: "less -R")
 ```
 
-### :prompt
+The `:command` also accepts an array of pagers to use:
 
-For the `BasicPager` you can pass a `:prompt` option to change the page break text:
+```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
-prompt = -> (page_num) { output.puts "Page -#{page_num}- Press enter to continue" }
-pager = TTY::Pager::BasicPager.new prompt: prompt
+pager = TTY::Pager::BasicPager.new(width: 80)
 ```
 
-### :command
+#### 2.1.4 :prompt
 
-You can force `SystemPager` to always use a specific paging tool by passing the `:command` option:
+To change the `BasicPager` page break prompt display, use the `:prompt` option:
 
 ```ruby
-TTY::Pager.new command; 'less -R'
-TTY::Pager::SystemPager.new command: 'less -R'
+prompt = -> (page) { "Page -#{page_num}- Press enter to continue" }
+pager = TTY::Pager.new(prompt: prompt)
 ```
 
-### PAGER
+### 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...")
+````
 
-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 prefered pager you can either set up your shell like so:
+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")
+```
+
+You can pass in any number of arguments:
+
+```ruby
+pager.write("one", "two", "three")
+```
+
+### 2.4 try_write
+
+To check if a write has been successful use `try_write`:
+
+```ruby
+pager.try_write("Some text")
+# => true
+```
+
+### 2.5 puts
+
+To write a line of text and end it with a new line use `puts` call:
+
+```ruby
+pager.puts("Single line of content")
+```
+
+### 2.6 close
+
+When you're done streaming content manually use `close` to finish paging.
+
+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
@@ -118,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-2017 Piotr Murach. See LICENSE for further details.
+Copyright (c) 2015 Piotr Murach. See LICENSE for further details.