TTY::Reader

A pure Ruby library that provides a set of methods for processing keyboard input in character, line and multiline modes. In addition it maintains history of entered input with an ability to recall and re-edit those inputs and register to listen for keystroke events.

TTY::Reader provides independent reader component for TTY toolkit.

Features

Reading single keypress
Line editing
Multiline input
History management
Ability to register for key events

Installation

Add this line to your application's Gemfile:

gem 'tty-reader'

And then execute:

$ bundle

Or install it yourself as:

$ gem install tty-reader

1. Usage
2. API
3. Configuration
- 3.1 :interrupt
- 3.2 :track_history

Usage

reader = TTY::Reader.new

API

2.1 read_keypress

To read a single key stroke from the user use read_char or read_keypress:

reader.read_char
reader.read_keypress

2.2 read_line

To read a single line terminated by new line character use read_line like so:

reader.read_line

2.3 read_multiline

To read more than one line terminated by Ctrl+d or Ctrl+z use read_multiline:

reader.read_multiline
# => [ "line1", "line2", ... ]

2.4 events

You can register to listen on a key pressed events. This can be done by calling on with a event name:

reader.on(:keypress) { |event| .... }

The event object is yielded to a block whenever particular key event fires. The event has key and value methods. Further, the key responds to following messages:

name - the name of the event such as :up, :down, letter or digit
meta - true if event is non-standard key associated
shift - true if shift has been pressed with the key
ctrl - true if ctrl has been pressed with the key

For example, to add listen to vim like navigation keys, one would do the following:

reader.on(:keypress) do |event|
  if event.value == 'j'
    ...
  end

  if event.value == 'k'
    ...
  end
end

You can subscribe to more than one event:

prompt.on(:keypress) { |key| ... }
      .on(:keydown)  { |key| ... }

The available events are:

:keypress
:keydown
:keyup
:keyleft
:keyright
:keynum
:keytab
:keyenter
:keyreturn
:keyspace
:keyescape
:keydelete
:keybackspace

3. Configuration

3.1. :interrupt

By 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:

:signal - sends interrupt signal
:exit - exists with status code
:noop - skips handler
custom proc

For example, to send interrupt signal do:

reader = TTY::Reader.new(interrupt: :signal)

3.2. :track_history

The read_line and read_multiline provide history buffer that tracks all the lines entered during TTY::Reader.new interactions. The history buffer provides previoius or next lines when user presses up/down arrows respectively. However, if you wish to disable this behaviour use :track_history option like so:

reader = TTY::Reader.new(track_history: false)

Development

After 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.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/tty-reader. 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.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the Tty::Reader project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.