TTY::Pager

Terminal output paging in a cross-platform way supporting all major ruby interpreters.

TTY::Pager provides independent terminal output paging 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 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.

1. Usage

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

2. Interface

:enabled

If you want to disable the pager pass the :enabled option set to false:

pager = TTY::Pager.new enabled: false

:width

The BasicPager allows to wrap content at given width:

pager = TTY::Pager::BasicPager.new width: 80

:prompt

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

:command

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'

PAGER

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'

Contributing

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

slowbro/tty-pager