tty-reader 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4450cd173fbc5dece09c32d0ad799bb5fcccff3a
-  data.tar.gz: e744eaefca8e5b03f79b41d502fe71a2ba8b3166
+  metadata.gz: f1b83301002055869c17bb4ecb0571be89b2d8e0
+  data.tar.gz: 39bd25b1b47c2542c000a407a2839bd4cba12c31
 SHA512:
-  metadata.gz: b113279156eb75f4f2c7079abe5c225993c4f0b24bd33fb07dd45366e316bf9a9356ea23b0f96cf122e36502fa85161d8ccc33f7a4e8ef2dae57faf184f4f77a
-  data.tar.gz: 21fd68ce3809c21a88dd24d18ec25348e4111fc41a7828c6c2bb3ccb6279f7fed3477c1261d9d65e3911f8d6c5656f92f908fee5ac9d1ab44609100feb9c9a5c
+  metadata.gz: 08c4198829dcc5a4f95c865c4dfcb2c4be9711885a3d071c6f1d9f917e8dc20083d558dde98ffc38af0d7e6ce6de9f4fbfeecb1158109f2905adb047aa6970f1
+  data.tar.gz: 3899ba4f5461099024379df0058deb177dbf1a45d6fb250970f3a639adf792f9563773adeae1b240f2feb41241d6ec45b4a012c15f4b1c234ad6bf582f7c0ac4

data/.travis.yml

@@ -2,17 +2,17 @@
 language: ruby
 sudo: false
 cache: bundler
+before_install: "gem update bundler"
 bundler_args: --without tools
 script: "bundle exec rake ci"
 rvm:
-  - 1.9.3
   - 2.0.0
   - 2.1.10
-  - 2.2.6
-  - 2.3.3
-  - 2.4.1
+  - 2.2.9
+  - 2.3.6
+  - 2.4.3
   - ruby-head
-  - jruby-9000
+  - jruby-9.1.1.0
   - jruby-head
 matrix:
   allow_failures:

data/CHANGELOG.md

@@ -1,7 +1,28 @@
 # Change log
 
+## [v0.2.0] - 2018-01-01
+
+### Added
+* Add home & end keys support in #read_line
+* Add tty-screen & tty-cursor dependencies
+
+### Changed
+* Change Codes to Keys and inverse keys lookup to allow for different system keys matching same name.
+* Change Reader#initialize to only accept options and make input and output options as well.
+* Change #read_line to print newline character in noecho mode
+* Change Reader::Line to include prompt prefix
+* Change Reader#initialize to only accept options in place of positional arguments
+* Change Reader to expose history options
+
+### Fixed
+* Fix issues with recognising :home & :end keys on different terminals
+* Fix #read_line to work with strings spanning multiple screen widths and allow copy-pasting a long string without repeating prompt
+* Fix backspace keystroke in cooked mode
+* Fix history to only save lines in echo mode
+
 ## [v0.1.0] - 2017-08-30
 
 * Initial implementation and release
 
-[v0.1.0]: https://github.com/peter-murach/tty-reader/compare/v0.1.0
+[v0.2.0]: https://github.com/piotrmurach/tty-reader/compare/v0.1.0...v0.2.0
+[v0.1.0]: https://github.com/piotrmurach/tty-reader/compare/v0.1.0

data/Gemfile

@@ -5,10 +5,9 @@ git_source(:github) {|repo_name| "https://github.com/#{repo_name}" }
 gemspec
 
 group :test do
-  gem 'benchmark-ips', '~> 2.0.0'
-  gem 'simplecov', '~> 0.10.0'
-  gem 'coveralls', '~> 0.8.2'
-  gem 'term-ansicolor', '=1.3.2'
+  gem 'benchmark-ips', '~> 2.7.2'
+  gem 'simplecov', '~> 0.14.1'
+  gem 'coveralls', '~> 0.8.21'
 end
 
 group :tools do
@@ -16,6 +15,6 @@ group :tools do
 end
 
 group :metrics do
-  gem 'yard',      '~> 0.8.7'
+  gem 'yard',      '~> 0.9.12'
   gem 'yardstick', '~> 0.9.9'
 end

data/README.md

@@ -3,7 +3,7 @@
 [![Gem Version](https://badge.fury.io/rb/tty-reader.svg)][gem]
 [![Build Status](https://secure.travis-ci.org/piotrmurach/tty-reader.svg?branch=master)][travis]
 [![Build status](https://ci.appveyor.com/api/projects/status/cj4owy2vlty2q1ko?svg=true)][appveyor]
-[![Code Climate](https://codeclimate.com/github/piotrmurach/tty-reader/badges/gpa.svg)][codeclimate]
+[![Maintainability](https://api.codeclimate.com/v1/badges/2f68d5e8ecc271bda820/maintainability)][codeclimate]
 [![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-reader/badge.svg)][coverage]
 [![Inline docs](http://inch-ci.org/github/piotrmurach/tty-reader.svg?branch=master)][inchpages]
 
@@ -11,7 +11,7 @@
 [gem]: http://badge.fury.io/rb/tty-reader
 [travis]: http://travis-ci.org/piotrmurach/tty-reader
 [appveyor]: https://ci.appveyor.com/project/piotrmurach/tty-reader
-[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-reader
+[codeclimate]: https://codeclimate.com/github/piotrmurach/tty-reader/maintainability
 [coverage]: https://coveralls.io/github/piotrmurach/tty-reader
 [inchpages]: http://inch-ci.org/github/piotrmurach/tty-reader
 
@@ -19,13 +19,23 @@
 
 **TTY::Reader** provides independent reader component for [TTY](https://github.com/piotrmurach/tty) toolkit.
 
+## Compatibility
+
+The `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.
+
+`TTY::Reader` forges its own path to provide features necessary for building line editing in terminal applications!
+
 ## Features
 
-* Reading single keypress
+* Pure Ruby
 * Line editing
-* Multiline input
+* Reading single keypress
+* Reading multiline input
 * History management
-* Ability to register for key events
+* Ability to register for keystroke events
+* No global state
+* Works on Linux, OS X, FreeBSD and Windows
+* Supports Ruby versions `>= 2.0.0` & JRuby
 
 ## Installation
 
@@ -48,10 +58,16 @@ Or install it yourself as:
   * [2.1 read_keypress](#21-read_keypress)
   * [2.2 read_line](#22-read_line)
   * [2.3 read_multiline](#23-read_multiline)
-  * [2.4 events](#24-events)
+  * [2.4 on](#24-on)
+  * [2.5 subscribe](#25-subscribe)
+  * [2.6 trigger](#26-trigger)
+  * [2.7 supported events](#27-supported-events)
 * [3. Configuration](#3-configuration)
   * [3.1 :interrupt](#31-interrupt)
-  * [3.2 :track_history](#31-track_history)
+  * [3.2 :track_history](#32-track_history)
+  * [3.3 :history_cycle](#33-history_cycle)
+  * [3.4 :history_duplicates](#34-history_duplicates)
+  * [3.5 :history_exclude](#35-history_exclude)
 
 ## Usage
 
@@ -70,24 +86,59 @@ reader.read_char
 reader.read_keypress
 ```
 
-## 2.2 read_line
+### 2.2 read_line
+
+By 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.
 
-To read a single line terminated by new line character use `read_line` like so:
+For example, to read a single line terminated by a new line character use `read_line` like so:
 
 ```ruby
 reader.read_line
 ```
 
-## 2.3 read_multiline
+If 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`:
+
+```ruby
+reader.read_line(raw: false)
+```
+
+Any non-interpreted characters received are written back to terminal, however you can stop this by using `:echo` option set to `false`:
+
+```ruby
+reader.read_line(echo: false)
+```
+
+You can also provide a line prefix displayed before input by passing it as a first aargument:
+
+```ruby
+reader.read_line(">> ")
+# >> input goes here ...
+```
+
+### 2.3 read_multiline
 
-To read more than one line terminated by `Ctrl+d` or `Ctrl+z` use `read_multiline`:
+By 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.
+
+For example, to read more than one line terminated by `Ctrl+d` or `Ctrl+z` use `read_multiline`:
 
 ```ruby
 reader.read_multiline
 # => [ "line1", "line2", ... ]
 ```
 
-## 2.4 events
+If 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`:
+
+```ruby
+reader.read_line(raw: false)
+```
+
+You can also provide a linke prefix displayed before input by passing a string as a first argument:
+
+```ruby
+reader.read_multiline(">> ")
+```
+
+### 2.4 on
 
 You can register to listen on a key pressed events. This can be done by calling `on` with a event name:
 
@@ -123,25 +174,92 @@ prompt.on(:keypress) { |key| ... }
       .on(:keydown)  { |key| ... }
 ```
 
-The available events are:
+### 2.5 subscribe
+
+You 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.
+
+For example, if a `Context` class wishes to only listen for `keypress` event:
+
+```ruby
+class Context
+  def keypress(event)
+    ...
+  end
+end
+```
+
+Then subcribing is done:
+
+```ruby
+context = Context.new
+reader.subscribe(context)
+```
+
+### 2.6 trigger
+
+The 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.
+
+For example, to trigger `:keydown` event do:
+
+```ruby
+reader.trigger(:keydown)
+```
+
+To add vim bindings for line editing you could discern between alphanumeric inputs like so:
+
+```ruby
+reader.on(:keypress) do |event|
+  if event.value == 'j'
+    reader.trigger(:keydown)
+  end
+  if evevnt.value == 'k'
+    reader.trigger(:keup)
+  end
+end
+```
+
+### 2.7 supported events
+
+The available key events for character input are:
 
 * `:keypress`
-* `:keydown`
-* `:keyup`
-* `:keyleft`
-* `:keyright`
-* `:keynum`
-* `:keytab`
 * `:keyenter`
 * `:keyreturn`
+* `:keytab`
+* `:keybackspace`
 * `:keyspace`
 * `:keyescape`
 * `:keydelete`
-* `:keybackspace`
+* `:keyalpha`
+* `:keynum`
+
+The navigation relted key events are:
+
+* `:keydown`
+* `:keyup`
+* `:keyleft`
+* `:keyright`
+* `:keyhome`
+* `:keyend`
+* `:keyclear`
+
+The specific `ctrl` key events:
+
+* `:keyctrl_a`
+* `:keyctrl_b`
+* ...
+* `:keyctrl_z`
+
+The key events for functional keys `f*` are:
+
+* `:keyf1`
+* `:keyf2`
+* ...
+* `:keyf24`
 
 ## 3. Configuration
 
-### 3.1. :interrupt
+### 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:
 
@@ -156,7 +274,7 @@ For example, to send interrupt signal do:
 reader = TTY::Reader.new(interrupt: :signal)
 ```
 
-### 3.2. :track_history
+### 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:
 
@@ -164,15 +282,46 @@ The `read_line` and `read_multiline` provide history buffer that tracks all the
 reader = TTY::Reader.new(track_history: false)
 ```
 
+### 3.3. `:history_cycle`
+
+This option determines whether the history buffer allows for infinite navigation. By default it is set to `false`. You can change this:
+
+```ruby
+reader = TTY::Reader.new(history_cycle: true)
+```
+
+### 3.4. `:history_duplicates`
+
+This option controls whether duplicate lines are stored in history. By default set to `true`. You can change this:
+
+```ruby
+reader = TTY::Reader.new(history_duplicates: false)
+```
+
+### 3.5. `:history_exclude`
+
+This 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 exlude empty lines. To change this:
+
+```ruby
+reader = TTY::Reader.new(history_exclude: ->(line) { ... })
+```
+
 ## 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](https://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](http://contributor-covenant.org) code of conduct.
+Bug 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.
+
+1. Clone the project on GitHub
+2. Create a feature branch
+3. Submit a Pull Request
+
+Important notes:
+- **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.
+- **The tests must be be idempotent.** Any test run should produce the same result when run over and over.
+- **All new features must include source code & readme documentation** Any new method you add should include yarddoc style documentation with clearly specified parameter and return types.
 
 ## License
 
@@ -180,8 +329,8 @@ The gem is available as open source under the terms of the [MIT License](http://
 
 ## 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](https://github.com/piotrmurach/tty-reader/blob/master/CODE_OF_CONDUCT.md).
+Everyone 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).
 
 ## Copyright
 
-Copyright (c) 2017 Piotr Murach. See LICENSE for further details.
+Copyright (c) 2017-2018 Piotr Murach. See LICENSE for further details.

data/appveyor.yml

@@ -9,7 +9,6 @@ test_script:
   - bundle exec rake ci
 environment:
   matrix:
-    - ruby_version: "193"
     - ruby_version: "200"
     - ruby_version: "200-x64"
     - ruby_version: "21"
@@ -20,6 +19,3 @@ environment:
     - ruby_version: "23-x64"
     - ruby_version: "24"
     - ruby_version: "24-x64"
-matrix:
-  allow_failures:
-    - ruby_version: "193"

data/benchmarks/speed_read_char.rb

@@ -0,0 +1,34 @@
+require 'benchmark/ips'
+require 'tty-reader'
+
+input = StringIO.new("a")
+output = StringIO.new
+$stdin = input
+reader = TTY::Reader.new(input, output)
+
+Benchmark.ips do |x|
+  x.report('getc') do
+    input.rewind
+    $stdin.getc
+  end
+
+  x.report('read_char') do
+    input.rewind
+    reader.read_char
+  end
+
+  x.compare!
+end
+
+# v0.1.0
+#
+# Calculating -------------------------------------
+#                 getc     52462 i/100ms
+#            read_char       751 i/100ms
+# -------------------------------------------------
+#                 getc  2484819.4 (±4.1%) i/s -   12433494 in   5.013438s
+#            read_char     7736.4 (±2.9%) i/s -      39052 in   5.052628s
+#
+# Comparison:
+#                 getc:  2484819.4 i/s
+#            read_char:     7736.4 i/s - 321.19x slower

data/benchmarks/speed_read_line.rb

@@ -0,0 +1,34 @@
+require 'benchmark/ips'
+require 'tty-reader'
+
+input = StringIO.new("abc\n")
+output = StringIO.new
+$stdin = input
+reader = TTY::Reader.new(input, output)
+
+Benchmark.ips do |x|
+  x.report('gets') do
+    input.rewind
+    $stdin.gets
+  end
+
+  x.report('read_line') do
+    input.rewind
+    reader.read_line
+  end
+
+  x.compare!
+end
+
+# v0.1.0
+#
+# Calculating -------------------------------------
+#                 gets     51729 i/100ms
+#            read_line       164 i/100ms
+# -------------------------------------------------
+#                 gets  1955255.2 (±3.7%) i/s -    9776781 in   5.008004s
+#            read_line     1215.1 (±33.1%) i/s -       5248 in   5.066569s
+#
+# Comparison:
+#                 gets:  1955255.2 i/s
+#            read_line:     1215.1 i/s - 1609.19x slower