Terminal output paging in a cross-platform way supporting all major ruby interpreters.
TTY::Pager provides independent terminal output paging component for TTY toolkit.
Add this line to your application's Gemfile:
gem 'tty-pager'
And then execute:
$ bundle
Or install it yourself as:
$ gem install tty-pager
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.
In order to let TTY::Pager pick the best paging mechanism automatically do:
pager = TTY::Pager.new
Then to perform actual content pagination invoke page
method with the content to paginate as the argument:
pager.page("Very long text...")
If you want to use specific pager you can do so by invoking it directly
pager = TTY::Pager::BasicPager.new
If you want to disable the pager pass the :enabled
option set to false
:
pager = TTY::Pager.new enabled: false
The BasicPager
allows to wrap content at given width:
pager = TTY::Pager::BasicPager.new width: 80
For the BasicPager
you can pass a :prompt
option to change the page break text:
prompt = -> (page_num) { output.puts "Page -#{page_num}- Press enter to continue" }
pager = TTY::Pager::BasicPager.new prompt: prompt
You can force SystemPager
to always use a specific paging tool by passing the :command
option:
TTY::Pager.new command; 'less -R'
TTY::Pager::SystemPager.new command: 'less -R'
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:
PAGER=less
export PAGER
or set PAGER
in Ruby script:
ENV['PAGER']='less'
Bug reports and pull requests are welcome on GitHub at https://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 ( https://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
Copyright (c) 2015-2018 Piotr Murach. See LICENSE for further details.