Terminal output paging - cross-platform, major ruby interpreters
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Add markdown paging example Dec 1, 2018
lib Change to freeze strings Dec 9, 2018
spec Change to freeze strings Dec 9, 2018
tasks Change lib loading Oct 29, 2017
.gitignore Initial release. May 29, 2015
.rspec Initial release. May 29, 2015
.travis.yml Change to use latest ruby Feb 19, 2019
CHANGELOG.md Add release notes Dec 9, 2018
CODE_OF_CONDUCT.md Add code of conduct Jul 14, 2017
Gemfile Update dev dependencies Aug 25, 2018
ISSUE_TEMPLATE.md Add templates Aug 25, 2018
LICENSE.txt Initial release. May 29, 2015
PULL_REQUEST_TEMPLATE.md
README.md Add docs about :command option accepting multiple tools Dec 9, 2018
Rakefile Initial release. May 29, 2015
appveyor.yml Add latest ruby Aug 25, 2018
tty-pager.gemspec Change to remove bundler version restrictions Feb 19, 2019

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.