{"id":13819904,"url":"https://github.com/piotrmurach/tty-reader","last_synced_at":"2025-05-15T09:15:55.458Z","repository":{"id":24558115,"uuid":"101916183","full_name":"piotrmurach/tty-reader","owner":"piotrmurach","description":"A set of methods for processing keyboard input in character, line and multiline modes.","archived":false,"fork":false,"pushed_at":"2023-11-09T11:18:46.000Z","size":1036,"stargazers_count":89,"open_issues_count":12,"forks_count":17,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-15T20:15:27.342Z","etag":null,"topics":["cli","console","line-editing","ruby","ruby-gem","terminal","tty","word-completion"],"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":"2017-08-30T18:33:59.000Z","updated_at":"2024-10-23T18:47:35.000Z","dependencies_parsed_at":"2024-05-28T19:27:37.743Z","dependency_job_id":"32ba0600-32a2-4dff-9316-9b9b46f43883","html_url":"https://github.com/piotrmurach/tty-reader","commit_stats":{"total_commits":228,"total_committers":7,"mean_commits":32.57142857142857,"dds":"0.030701754385964897","last_synced_commit":"ac9257188cfd19f91f5386217ef29c218b9a83bd"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-reader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-reader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-reader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/piotrmurach%2Ftty-reader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/piotrmurach","download_url":"https://codeload.github.com/piotrmurach/tty-reader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225413743,"owners_count":17470617,"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":["cli","console","line-editing","ruby","ruby-gem","terminal","tty","word-completion"],"created_at":"2024-08-04T08:00:54.731Z","updated_at":"2024-11-19T19:30:52.454Z","avatar_url":"https://github.com/piotrmurach.png","language":"Ruby","readme":"\u003cdiv align=\"center\"\u003e\n  \u003ca href=\"https://ttytoolkit.org\"\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::Reader [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]\n\n[![Gem Version](https://badge.fury.io/rb/tty-reader.svg)][gem]\n[![Actions CI](https://github.com/piotrmurach/tty-reader/workflows/CI/badge.svg?branch=master)][gh_actions_ci]\n[![Build status](https://ci.appveyor.com/api/projects/status/cj4owy2vlty2q1ko?svg=true)][appveyor]\n[![Maintainability](https://api.codeclimate.com/v1/badges/2f68d5e8ecc271bda820/maintainability)][codeclimate]\n[![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-reader/badge.svg)][coverage]\n[![Inline docs](http://inch-ci.org/github/piotrmurach/tty-reader.svg?branch=master)][inchpages]\n\n[gitter]: https://gitter.im/piotrmurach/tty\n[gem]: http://badge.fury.io/rb/tty-reader\n[gh_actions_ci]: https://github.com/piotrmurach/tty-reader/actions?query=workflow%3ACI\n[travis]: http://travis-ci.org/piotrmurach/tty-reader\n[appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-reader\n[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-reader/maintainability\n[coverage]: https://coveralls.io/github/piotrmurach/tty-reader\n[inchpages]: http://inch-ci.org/github/piotrmurach/tty-reader\n\n\u003e A pure Ruby library that provides a set of methods for processing keyboard input in character, line and multiline modes. It maintains history of entered input with an ability to recall and re-edit those inputs. It lets you register to listen for keystroke events and trigger custom key events yourself.\n\n**TTY::Reader** provides independent reader component for [TTY](https://github.com/piotrmurach/tty) toolkit.\n\n![](assets/shell.gif)\n\n## Compatibility\n\nThe `tty-reader` is not compatible with the GNU Readline and doesn't aim to be. It originated from [tty-prompt](https://github.com/piotrmurach/tty-prompt) project to provide flexibility, independence from underlying operating system and Ruby like API interface for creating different prompts.\n\n`TTY::Reader` forges its own path to provide features necessary for building line editing in terminal applications!\n\n## Features\n\n* Pure Ruby\n* Reading [single keypress](#21-read_keypress)\n* [Line editing](#22-read_line)\n* Reading [multiline input](#23-read_multiline)\n* Ability to [register](#24-on) for keystroke events\n* Track input [history](#32-track_history)\n* No global state\n* Works on Linux, OS X, FreeBSD and Windows\n* Supports Ruby versions `\u003e= 2.0.0` \u0026 JRuby\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem \"tty-reader\"\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install tty-reader\n\n* [1. Usage](#1-usage)\n* [2. API](#2-api)\n  * [2.1 read_keypress](#21-read_keypress)\n  * [2.2 read_line](#22-read_line)\n  * [2.3 read_multiline](#23-read_multiline)\n  * [2.4 on](#24-on)\n  * [2.5 subscribe](#25-subscribe)\n  * [2.6 unsubscribe](#26-unsubscribe)\n  * [2.7 trigger](#27-trigger)\n  * [2.8 supported events](#28-supported-events)\n* [3. Configuration](#3-configuration)\n  * [3.1 :interrupt](#31-interrupt)\n  * [3.2 :track_history](#32-track_history)\n  * [3.3 :history_cycle](#33-history_cycle)\n  * [3.4 :history_duplicates](#34-history_duplicates)\n  * [3.5 :history_exclude](#35-history_exclude)\n  * [3.6 :history_size](#36-history_size)\n\n## Usage\n\nIn just a few lines you can recreate IRB prompt.\n\nInitialize the reader:\n\n```ruby\nreader = TTY::Reader.new\n```\n\nThen register to listen for key events, in this case listen for `Ctrl-X` or `Esc` keys to exit:\n\n```ruby\nreader.on(:keyctrl_x, :keyescape) do\n  puts \"Exiting...\"\n  exit\nend\n```\n\nFinally, keep asking user for line input with a `=\u003e` as a prompt:\n\n```ruby\nloop do\n  reader.read_line(\"=\u003e \")\nend\n```\n\n## API\n\n### 2.1 read_keypress\n\nTo read a single key stroke from the user use `read_char` or `read_keypress`:\n\n```ruby\nreader.read_char\nreader.read_keypress\nreader.read_keypress(nonblock: true)\n```\n\n### 2.2 read_line\n\nBy default `read_line` works in `raw mode` which means it behaves like a line editor that allows you to edit each character, respond to `control characters` such as `Control-A` to `Control-B` or navigate through history.\n\nFor example, to read a single line terminated by a new line character use `read_line` like so:\n\n```ruby\nreader.read_line\n```\n\nIf you wish for the keystrokes to be interpreted by the terminal instead, use so called `cooked` mode by providing the `:raw` option set to `false`:\n\n```ruby\nreader.read_line(raw: false)\n```\n\nAny non-interpreted characters received are written back to terminal, however you can stop this by using `:echo` option set to `false`:\n\n```ruby\nreader.read_line(echo: false)\n```\n\nYou can also provide a line prefix displayed before input by passing it as a first argument:\n\n```ruby\nreader.read_line(\"\u003e\u003e \")\n# \u003e\u003e\n```\n\nTo pre-populate the line content for editing use `:value` option:\n\n```ruby\nreader.read_line(\"\u003e \", value: \"edit me\")\n# \u003e edit me\n```\n\n### 2.3 read_multiline\n\nBy default `read_multiline` works in `raw mode` which means it behaves like a multiline editor that allows you to edit each character, respond to `control characters` such as `Control-A` to `Control-B` or navigate through history.\n\nFor example, to read more than one line terminated by `Ctrl+d` or `Ctrl+z` use `read_multiline`:\n\n```ruby\nreader.read_multiline\n# =\u003e [ \"line1\", \"line2\", ... ]\n```\n\nIf you wish for the keystrokes to be interpreted by the terminal instead, use so called `cooked` mode by providing the `:raw` option set to `false`:\n\n```ruby\nreader.read_line(raw: false)\n```\n\nYou can also provide a line prefix displayed before input by passing a string as a first argument:\n\n```ruby\nreader.read_multiline(\"\u003e\u003e \")\n```\n\n### 2.4 on\n\nYou can register to listen on a key pressed events. This can be done by calling `on` with a event name(s):\n\n```ruby\nreader.on(:keypress) { |event| .... }\n```\n\nor listen for multiple events:\n\n```ruby\nreader.on(:keyctrl_x, :keyescape) { |event| ... }\n```\n\nThe `KeyEvent` object is yielded to a block whenever a particular key event fires. The event responds to:\n\n* `key`   - key pressed\n* `value` - value of the key pressed\n* `line`  - the content of the currently edited line, empty otherwise\n\nThe `value` returns the actual key pressed and the `line` the content for the currently edited line or is empty.\n\nThe `key` is an object that responds to following messages:\n\n* `name`  - the name of the event such as :up, :down, letter or digit\n* `meta`  - true if event is non-standard key associated\n* `shift` - true if shift has been pressed with the key\n* `ctrl`  - true if ctrl has been pressed with the key\n\nFor example, to add listen to vim like navigation keys, one would do the following:\n\n```ruby\nreader.on(:keypress) do |event|\n  if event.value == \"j\"\n    ...\n  end\n\n  if event.value == \"k\"\n    ...\n  end\nend\n```\n\nYou can subscribe to more than one event:\n\n```ruby\nreader.on(:keypress) { |event| ... }\n      .on(:keydown)  { |event| ... }\n```\n\n### 2.5 subscribe\n\nYou can subscribe any object to listen for the emitted [key events](#27-supported-events) using the `subscribe` message. The listener would need to implement a method for every event it wishes to receive.\n\nFor example, if a `MyListener` class wishes to only listen for `keypress` event:\n\n```ruby\nclass MyListener\n  def keypress(event)\n    ...\n  end\nend\n```\n\nThen subscribing is done:\n\n```ruby\nreader.subscribe(MyListener.new)\n```\n\nAlternatively, `subscribe` allows you to listen to events only for the duration of block execution like so:\n\n```ruby\nreader.subscribe(MyListener) do\n  ...\nend\n```\n\n### 2.6 unsubscribe\n\nYou can unsubscribe any object from listening to the key events using the `unsubscribe` message:\n\n```ruby\nreader.unsubscribe(my_listener)\n```\n\n### 2.7 trigger\n\nThe signature for triggering key events is `trigger(event, args...)`. The first argument is a [key event name](#27-supported-events) followed by any number of actual values related to the event being triggered.\n\nFor example, to trigger `:keydown` event do:\n\n```ruby\nreader.trigger(:keydown)\n```\n\nTo add vim bindings for line editing you could discern between alphanumeric inputs like so:\n\n```ruby\nreader.on(:keypress) do |event|\n  if event.value == \"j\"\n    reader.trigger(:keydown)\n  end\n  if evevnt.value == \"k\"\n    reader.trigger(:keyup)\n  end\nend\n```\n\n### 2.8 supported events\n\nThe available key events for character input are:\n\n* `:keypress`\n* `:keyenter`\n* `:keyreturn`\n* `:keytab`\n* `:keybackspace`\n* `:keyspace`\n* `:keyescape`\n* `:keydelete`\n* `:keyalpha`\n* `:keynum`\n\nThe navigation related key events are:\n\n* `:keydown`\n* `:keyup`\n* `:keyleft`\n* `:keyright`\n* `:keyhome`\n* `:keyend`\n* `:keyclear`\n\nThe specific `ctrl` key events:\n\n* `:keyctrl_a`\n* `:keyctrl_b`\n* ...\n* `:keyctrl_z`\n\nThe key events for functional keys `f*` are:\n\n* `:keyf1`\n* `:keyf2`\n* ...\n* `:keyf24`\n\n## 3. Configuration\n\n### 3.1. `:interrupt`\n\nBy default `InputInterrupt` error will be raised when the user hits the interrupt key(Control-C). However, you can customise this behaviour by passing the `:interrupt` option. The available options are:\n\n* `:signal` - sends interrupt signal\n* `:exit` - exists with status code\n* `:noop` - skips handler\n* custom proc\n\nFor example, to send interrupt signal do:\n\n```ruby\nreader = TTY::Reader.new(interrupt: :signal)\n```\n\n### 3.2. `:track_history`\n\nThe `read_line` and `read_multiline` provide history buffer that tracks all the lines entered during `TTY::Reader.new` interactions. The history buffer provides previous or next lines when user presses up/down arrows respectively. However, if you wish to disable this behaviour use `:track_history` option like so:\n\n```ruby\nreader = TTY::Reader.new(track_history: false)\n```\n\n### 3.3. `:history_cycle`\n\nThis option determines whether the history buffer allows for infinite navigation. By default it is set to `false`. You can change this:\n\n```ruby\nreader = TTY::Reader.new(history_cycle: true)\n```\n\n### 3.4. `:history_duplicates`\n\nThis option controls whether duplicate lines are stored in history. By default set to `false`. You can change this:\n\n```ruby\nreader = TTY::Reader.new(history_duplicates: true)\n```\n\n### 3.5. `:history_exclude`\n\nThis option allows you to exclude lines from being stored in history. It accepts a `Proc` with a line as a first argument. By default it is set to exclude empty lines. To change this:\n\n```ruby\nreader = TTY::Reader.new(history_exclude: -\u003e(line) { ... })\n```\n\n### 3.6. `:history_size`\n\nBy default, the history buffer can store up to `512` lines. This can be changed with the `:history_size` configuration:\n\n```ruby\nreader = TTY::Reader.new(history_size: 2048)\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/piotrmurach/tty-reader. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n1. Clone the project on GitHub\n2. Create a feature branch\n3. Submit a Pull Request\n\nImportant notes:\n- **All new features must include test coverage.** At a bare minimum, unit tests are required. It is preferred if you include acceptance tests as well.\n- **The tests must be be idempotent.** Any test run should produce the same result when run over and over.\n- **All new features must include source code \u0026 readme documentation** Any new method you add should include yarddoc style documentation with clearly specified parameter and return types.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the TTY::Reader project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/piotrmurach/tty-reader/blob/master/CODE_OF_CONDUCT.md).\n\n## Copyright\n\nCopyright (c) 2017 Piotr Murach. See LICENSE for further details.\n","funding_links":["https://github.com/sponsors/piotrmurach"],"categories":["Ruby","Happy Exploring 🤘"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiotrmurach%2Ftty-reader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpiotrmurach%2Ftty-reader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpiotrmurach%2Ftty-reader/lists"}