Skip to content
Terminal output paging - cross-platform, major ruby interpreters
Ruby
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Add markdown paging example Dec 1, 2018
lib
spec
tasks
.gitignore Initial release. May 29, 2015
.rspec Initial release. May 29, 2015
.rubocop.yml Add style rules Mar 16, 2019
.travis.yml
CHANGELOG.md
CODE_OF_CONDUCT.md
Gemfile Update dev dependencies Aug 25, 2018
ISSUE_TEMPLATE.md
LICENSE.txt Initial release. May 29, 2015
PULL_REQUEST_TEMPLATE.md
README.md
Rakefile
appveyor.yml Change to restrict bundler and use latest ruby Mar 16, 2019
tty-pager.gemspec

README.md

tty logo

TTY::Pager Gitter

Gem Version Build Status Build status Maintainability Coverage Status Inline docs

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.new(width: 80)
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(s) by passing the :command option:

TTY::Pager.new(command: 'less -R')
TTY::Pager::SystemPager.new(command: 'less -R')

You also specify an array of pagers to use:

pager = TTY::Pager.new(command: ['less -r', 'more -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 preferred 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.

  1. Fork it ( https://github.com/piotrmurach/tty-pager/fork )
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Copyright

Copyright (c) 2015 Piotr Murach. See LICENSE for further details.

You can’t perform that action at this time.