{"id":28630945,"url":"https://github.com/piotrmurach/tty-pager","last_synced_at":"2025-06-12T13:09:25.491Z","repository":{"id":32934579,"uuid":"36530537","full_name":"piotrmurach/tty-pager","owner":"piotrmurach","description":"Terminal output paging - cross-platform, major ruby interpreters","archived":false,"fork":false,"pushed_at":"2025-04-29T19:37:19.000Z","size":214,"stargazers_count":41,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-29T22:18:26.316Z","etag":null,"topics":["console","console-tool","pager","ruby-gem","terminal","tty","tty-components"],"latest_commit_sha":null,"homepage":"https://ttytoolkit.org","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/piotrmurach.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"piotrmurach"}},"created_at":"2015-05-29T21:39:14.000Z","updated_at":"2025-04-29T19:37:22.000Z","dependencies_parsed_at":"2024-06-18T18:20:00.052Z","dependency_job_id":"f413e0cc-845b-4d78-8f2b-a645314eaf8d","html_url":"https://github.com/piotrmurach/tty-pager","commit_stats":{"total_commits":229,"total_committers":7,"mean_commits":"32.714285714285715","dds":0.04366812227074235,"last_synced_commit":"89f1cd80e3bba7865ac94eae940c7e2095d3bba4"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/piotrmurach/tty-pager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-pager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-pager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-pager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-pager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piotrmurach","download_url":"https://codeload.github.com/piotrmurach/tty-pager/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-pager/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259470951,"owners_count":22862999,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["console","console-tool","pager","ruby-gem","terminal","tty","tty-components"],"created_at":"2025-06-12T13:09:24.775Z","updated_at":"2025-06-12T13:09:25.478Z","avatar_url":"https://github.com/piotrmurach.png","language":"Ruby","funding_links":["https://github.com/sponsors/piotrmurach"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://ttytoolkit.org\" target=\"_blank\"\u003e\u003cimg width=\"130\" src=\"https://github.com/piotrmurach/tty/raw/master/images/tty.png\" alt=\"TTY Toolkit logo\" /\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n# TTY::Pager\n\n[![Gem Version](https://badge.fury.io/rb/tty-pager.svg)][gem]\n[![Actions CI](https://github.com/piotrmurach/tty-pager/actions/workflows/ci.yml/badge.svg)][gh_actions_ci]\n[![Build status](https://ci.appveyor.com/api/projects/status/3auc1vi3mk5puqai?svg=true)][appveyor]\n[![Maintainability](https://api.codeclimate.com/v1/badges/636da0d02231b7f3e50f/maintainability)][codeclimate]\n[![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-pager/badge.svg)][coverage]\n\n[gem]: https://badge.fury.io/rb/tty-pager\n[gh_actions_ci]: https://github.com/piotrmurach/tty-pager/actions/workflows/ci.yml\n[appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-pager\n[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-pager/maintainability\n[coverage]: https://coveralls.io/github/piotrmurach/tty-pager\n\n\u003e A cross-platform terminal pager that works on all major Ruby interpreters.\n\n**TTY::Pager** provides independent terminal pager component for [TTY](https://github.com/piotrmurach/tty) toolkit.\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n    gem 'tty-pager'\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install tty-pager\n\n\n## Overview\n\nThe **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.\n\n## Contents\n\n* [1. Usage](#1-usage)\n* [2. API](#2-api)\n  * [2.1 new](#21-new)\n    * [2.1.1 :enabled](#211-enabled)\n    * [2.1.2 :command](#212-command)\n    * [2.1.3 :width](#213-width)\n    * [2.1.4 :prompt](#214-prompt)\n  * [2.2 page](#22-page)\n  * [2.3 write](#23-write)\n  * [2.4 try_write](#24-try_write)\n  * [2.5 puts](#25-puts)\n  * [2.6 close](#26-close)\n  * [2.7 ENV](#27-env)\n\n## 1. Usage\n\nThe **TTY::Pager** will pick the best paging mechanism available on your system when initialized:\n\n```ruby\npager = TTY::Pager.new\n```\n\nThen to start paginating text call the `page` method with the content as the first argument:\n\n```ruby\npager.page(\"Very long text...\")\n```\n\nThis will launch a pager in the background and wait until the user is done.\n\nAlternatively, you can pass the `:path` keyword to specify a file path:\n\n```ruby\npager.page(path: \"/path/to/filename.txt\")\n```\n\nIf instead you'd like to paginate a long-running operation, you could use the block form of the pager:\n\n```ruby\nTTY::Pager.page do |pager|\n  File.open(\"file_with_lots_of_lines.txt\", \"r\").each_line do |line|\n    # do some work with the line\n\n    pager.write(line) # send it to the pager\n  end\nend\n```\n\nAfter block finishes, the pager is automatically closed.\n\nFor more control, you can translate the block form into separate `write` and `close` calls:\n\n```ruby\nbegin\n  pager = TTY::Pager.new\n\n  File.open(\"file_with_lots_of_lines.txt\", \"r\").each_line do |line|\n    # do some work with the line\n\n    pager.write(line) # send it to the pager\n  end\nrescue TTY::Pager::PagerClosed\n  # the user closed the paginating tool\nensure\n  pager.close\nend\n```\n\nIf you want to use a specific pager you can do so by invoking it directly:\n\n```ruby\npager = TTY::Pager::BasicPager.new\n# or\npager = TTY::Pager::SystemPager.new\n# or\npager = TTY::Pager::NullPager.new\n```\n\n## 2. API\n\n### 2.1 new\n\nThe `TTY::Pager` can be configured during initialization for terminal width, type of prompt when basic pager is invoked, and the pagination command to run.\n\nFor example, to disable a pager in CI you could do:\n\n```ruby\npager = TTY::Pager.new(enabled: false)\n````\n\n#### 2.1.1 :enabled\n\nIf you want to disable the paging use the `:enabled` option set to `false`:\n\n```ruby\npager = TTY::Pager.new(enabled: false)\n```\n\nThis 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.\n\n#### 2.1.2 :command\n\nTo force `TTY::Pager` to always use a specific paging tool(s), use the `:command` option:\n\n```ruby\nTTY::Pager.new(command: \"less -R\")\n```\n\nThe `:command` also accepts an array of pagers to use:\n\n```ruby\npager = TTY::Pager.new(command: [\"less -r\", \"more -r\"])\n```\n\nIf the provided pager command or commands don't exist on user's system, the pager will fallback automatically on a basic Ruby implementation.\n\nTo skip automatic detection of pager and always use a system pager do:\n\n```ruby\nTTY::Pager::SystemPager.new(command: \"less -R\")\n```\n\n#### 2.1.3 :width\n\nOnly the `BasicPager` allows you to wrap content at given terminal width:\n\n```ruby\npager = TTY::Pager.new(width: 80)\n```\n\nThis option doesn't affect the `SystemPager`.\n\nTo directly use `BasicPager` do:\n\n```ruby\npager = TTY::Pager::BasicPager.new(width: 80)\n```\n\n#### 2.1.4 :prompt\n\nTo change the `BasicPager` page break prompt display, use the `:prompt` option:\n\n```ruby\nprompt = -\u003e (page) { \"Page -#{page_num}- Press enter to continue\" }\npager = TTY::Pager.new(prompt: prompt)\n```\n\n### 2.2 page\n\nTo start paging use the `page` method. It can be invoked on an instance or a class.\n\nThe class-level `page` is a convenient shortcut. To page some text you only need to do:\n\n```ruby\nTTY::Pager.page(\"Some long text...\")\n````\n\nYou can also include extra initialization parameters. For example, if you prefer to use a specific command do this:\n\n```ruby\nTTY::Pager.page(\"Some long text...\", command: \"less -R\")\n````\n\nThe instance equivalent would be:\n\n```ruby\npager = TTY::Pager.new(command: \"less -R\")\npager.page(\"Some long text...\")\n````\n\nApart from text, you can page file content by passing the `:path` option:\n\n```ruby\nTTY::Pager.page(path: \"/path/to/filename.txt\")\n````\n\nThe 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:\n\n```ruby\nTTY::Pager.page do |pager|\n  File.foreach(\"filename.txt\") do |line|\n    # do some work with the line\n\n    pager.write(line) # write line to the pager\n  end\nend\n```\n\nThe instance equivalent of the block version would be:\n\n```ruby\npager = TTY::Pager.new\nbegin\n  File.foreach(\"filename.txt\") do |line|\n    # do some work with the line\n\n    pager.write(line) # write line to the pager\n  end\nrescue TTY::Pager::PagerClosed\nensure\n  pager.close\nend\n```\n\n### 2.3 write\n\nTo stream content to the pager use the `write` method.\n\n```ruby\npager.write(\"Some text\")\n```\n\nYou can pass in any number of arguments:\n\n```ruby\npager.write(\"one\", \"two\", \"three\")\n```\n\n### 2.4 try_write\n\nTo check if a write has been successful use `try_write`:\n\n```ruby\npager.try_write(\"Some text\")\n# =\u003e true\n```\n\n### 2.5 puts\n\nTo write a line of text and end it with a new line use `puts` call:\n\n```ruby\npager.puts(\"Single line of content\")\n```\n\n### 2.6 close\n\nWhen you're done streaming content manually use `close` to finish paging.\n\nAll interactions with a pager can raise an exception for various reasons, so wrap your code using the following pattern:\n\n```ruby\npager = TTY::Pager.new\n\nbegin\n  # ... perform pager writes\nrescue TTY::Pager::PagerClosed\n  # the user closed the paginating tool\nensure\n  pager.close\nend\n```\n\nAlternatively use the class-level `page` call with a block to automatically close the pager:\n\n```ruby\nTTY::Pager.page do |pager|\n  # ... perform pager writes\nend\n```\n\n### 2.7 ENV\n\nBy 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`.\n\nTherefore, if you wish to set your preferred pager you can either set up your shell like so:\n\n```bash\nPAGER=less -R\nexport PAGER\n```\n\nOr set `PAGER` in Ruby script:\n\n```ruby\nENV[\"PAGER\"]=\"less -R\"\n```\n\n## Contributing\n\nBug 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 [code of conduct](https://github.com/piotrmurach/tty-pager/blob/master/CODE_OF_CONDUCT.md).\n\n1. Fork it ( https://github.com/piotrmurach/tty-pager/fork )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n\n## Code of Conduct\n\nEveryone interacting in the TTY::Pager project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/piotrmurach/tty-pager/blob/master/CODE_OF_CONDUCT.md).\n\n## Copyright\n\nCopyright (c) 2015 Piotr Murach. See LICENSE for further details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiotrmurach%2Ftty-pager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiotrmurach%2Ftty-pager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiotrmurach%2Ftty-pager/lists"}