TTY::Pager
¶ ↑
A cross-platform terminal pager that works on all major Ruby interpreters.
TTY::Pager provides independent terminal pager component for TTY toolkit.
Installation¶ ↑
Add this line to your application's Gemfile:
gem 'tty-pager'
And then execute:
$ bundle
Or install it yourself as:
$ gem install tty-pager
Overview¶ ↑
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¶ ↑
The TTY::Pager will pick the best paging mechanism available on your system when initialized:
pager = TTY::Pager.new
Then to start paginating text call the page
method with the content as the first argument:
pager.page("Very long text...")
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:
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:
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:
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:
pager = TTY::Pager::BasicPager.new # or pager = TTY::Pager::SystemPager.new # or pager = TTY::Pager::NullPager.new
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:
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)
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 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)
#### 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:
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:
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 -R export PAGER
Or set `PAGER` in Ruby script:
ruby ENV=“less -R”
“`
Contributing¶ ↑
Bug reports and pull requests are welcome on GitHub at github.com/piotrmurach/tty-pager. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
-
Fork it ( github.com/piotrmurach/tty-pager/fork )
-
Create your feature branch (
git checkout -b my-new-feature
) -
Commit your changes (
git commit -am 'Add some feature'
) -
Push to the branch (
git push origin my-new-feature
) -
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.
Copyright¶ ↑
Copyright © 2015 Piotr Murach. See LICENSE for further details.