tty-reader 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d01c5aa8afa041b5ceae747d42f8e94a0fb5dd63dc19f6cff8e9165caa4b014b
-  data.tar.gz: b37800731d9ea2f8c25658d2d8e37069b7a253fa2229214603b79e165ece3ede
+  metadata.gz: 995b414e2605c556220168d30b3f894771e021f2956aa75821fb3504f5ae6589
+  data.tar.gz: 4bfa84cd59cab3b14410d4eac314ae819765d94230c1c9b2a1ce94c09e13c80d
 SHA512:
-  metadata.gz: e64edab17527852f8fe1caba07554adbcc9040b1cd56472c23d4b0648215bc7fcf1ad159c6cd5de6dcd79e4606b9f199da2b461ade1ed5519f3f27f3038d6189
-  data.tar.gz: f68401fc9bcc6e9227e58562b02cf20e4ee1a88614f87299acdcd374105daf80de4bdcce4d6dfbc12dc131139b44716070050b55f7127e2a963904f8f0a7006f
+  metadata.gz: 061eeb4dc0698c1ff226ad3a2bc9fe69e4c519fe455642bda6bb9675e758e52c385335bb1604256f2002c75f6b2ba8528007e8df9d332815df8f072b75bd1388
+  data.tar.gz: e964e5cf12b271ce1fee675afc1d348f7f6c59a01f007580936c2544e672f784a1297e0f7f8ee6acce2d6ee4f867ca32b2142d3d376f5a4a28c82e2ab6521713

data/CHANGELOG.md

@@ -0,0 +1,54 @@
+# Change log
+
+## [v0.5.0] - 2018-11-24
+
+### Added
+* Add KeyEvent#line to expose current line in key event callbacks
+
+### Fixed
+* Fix Esc key by differentiating between escaped keys and actual escape input
+* Fix line editing to correctly insert next to last character
+
+## [v0.4.0] - 2018-08-05
+
+### Changed
+* Change to update tty-screen & tty-cursor dependencies
+
+## [v0.3.0] - 2018-04-29
+
+### Added
+* Add Reader#unsubscribe to allow stop listening to local key events
+
+### Changed
+* Change Reader#subscribe to allow to listening for key events only inside a block
+* Change to group xterm keys for navigation
+
+## [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.5.0]: https://github.com/piotrmurach/tty-reader/compare/v0.4.0...v0.5.0
+[v0.4.0]: https://github.com/piotrmurach/tty-reader/compare/v0.3.0...v0.4.0
+[v0.3.0]: https://github.com/piotrmurach/tty-reader/compare/v0.2.0...v0.3.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/README.md

@@ -1,3 +1,7 @@
+<div align="center">
+  <a href="https://piotrmurach.github.io/tty" target="_blank"><img width="130" src="https://cdn.rawgit.com/piotrmurach/tty/master/images/tty.png" alt="tty logo" /></a>
+</div>
+
 # TTY::Reader [![Gitter](https://badges.gitter.im/Join%20Chat.svg)][gitter]
 
 [![Gem Version](https://badge.fury.io/rb/tty-reader.svg)][gem]
@@ -15,10 +19,12 @@
 [coverage]: https://coveralls.io/github/piotrmurach/tty-reader
 [inchpages]: http://inch-ci.org/github/piotrmurach/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.
+> 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.
 
 **TTY::Reader** provides independent reader component for [TTY](https://github.com/piotrmurach/tty) toolkit.
 
+![](assets/shell.gif)
+
 ## 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.
@@ -28,11 +34,11 @@ The `tty-reader` is not compatible with the GNU Readline and doesn't aim to be.
 ## Features
 
 * Pure Ruby
-* Line editing
-* Reading single keypress
-* Reading multiline input
-* History management
-* Ability to register for keystroke events
+* Reading [single keypress](#21-read_keypress)
+* [Line editing](#22-read_line)
+* Reading [multiline input](#23-read_multiline)
+* Ability to [register](#24-on) for keystroke events
+* Track input [history](#32-track_history)
 * No global state
 * Works on Linux, OS X, FreeBSD and Windows
 * Supports Ruby versions `>= 2.0.0` & JRuby
@@ -72,10 +78,31 @@ Or install it yourself as:
 
 ## Usage
 
+In just a few lines you can recreate IRB prompt.
+
+Initialize the reader:
+
 ```ruby
 reader = TTY::Reader.new
 ```
 
+Then register to listen for key events, in this case listen for `Ctrl-X` or `Esc` keys to exit:
+
+```ruby
+reader.on(:keyctrl_x, :keyescape) do
+  puts "Exiting..."
+  exit
+end
+```
+
+Finally, keep asking user for line input with a `=>` as a prompt:
+
+```ruby
+loop do
+  reader.read_line('=> ')
+end
+```
+
 ## API
 
 ### 2.1 read_keypress
@@ -109,7 +136,7 @@ Any non-interpreted characters received are written back to terminal, however yo
 reader.read_line(echo: false)
 ```
 
-You can also provide a line prefix displayed before input by passing it as a first aargument:
+You can also provide a line prefix displayed before input by passing it as a first argument:
 
 ```ruby
 reader.read_line(">> ")
@@ -133,7 +160,7 @@ If you wish for the keystrokes to be interpreted by the terminal instead, use so
 reader.read_line(raw: false)
 ```
 
-You can also provide a linke prefix displayed before input by passing a string as a first argument:
+You can also provide a line prefix displayed before input by passing a string as a first argument:
 
 ```ruby
 reader.read_multiline(">> ")
@@ -141,13 +168,27 @@ 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:
+You can register to listen on a key pressed events. This can be done by calling `on` with a event name(s):
 
 ```ruby
 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:
+or listen for multiple events:
+
+```ruby
+reader.on(:keyctrl_x, :keyescape) { |event| ... }
+```
+
+The `KeyEvent` object is yielded to a block whenever a particular key event fires. The event responds to:
+
+* `key`   - key pressed
+* `value` - value of the key pressed
+* `line`  - the content of the currently edited line, empty otherwise
+
+The `value` returns the actual key pressed and the `line` the content for the currently edited line or is empty.
+
+The `key` is an object that 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
@@ -349,4 +390,4 @@ Everyone interacting in the TTY::Reader project’s codebases, issue trackers, c
 
 ## Copyright
 
-Copyright (c) 2017-2018 Piotr Murach. See LICENSE for further details.
+Copyright (c) 2017 Piotr Murach. See LICENSE for further details.

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

data/examples/shell.rb

@@ -1,11 +1,11 @@
 require_relative '../lib/tty-reader'
 
 puts "*** TTY::Reader Shell ***"
-puts "Press Ctrl-X to exit"
+puts "Press Ctrl-X or ESC to exit"
 
 reader = TTY::Reader.new
 
-reader.on(:keyctrl_x) { puts "Exiting..."; exit }
+reader.on(:keyctrl_x, :keyescape) { puts "Exiting..."; exit }
 
 loop do
   reader.read_line('=> ')

data/lib/tty-reader.rb

@@ -1,3 +1 @@
-# encoding: utf-8
-
 require_relative 'tty/reader'

data/lib/tty/reader.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 # frozen_string_literal: true
 
 require 'tty-cursor'
@@ -202,8 +201,10 @@ module TTY
       }
 
       while console.escape_codes.any?(&condition)
-        get_codes(options, codes)
+        char_codes = get_codes(options.merge(nonblock: true), codes)
+        break if char_codes.nil?
       end
+
       codes
     end
 
@@ -222,16 +223,18 @@ module TTY
     # @api public
     def read_line(prompt = '', **options)
       opts = { echo: true, raw: true }.merge(options)
-      line = Line.new(prompt, '')
+      line = Line.new(prompt: prompt)
       screen_width = TTY::Screen.width
 
       output.print(line.prompt)
 
       while (codes = get_codes(opts)) && (code = codes[0])
         char = codes.pack('U*')
-        trigger_key_event(char)
 
-        break if [:ctrl_d, :ctrl_z].include?(console.keys[char])
+        if [:ctrl_d, :ctrl_z].include?(console.keys[char])
+          trigger_key_event(char, line: line.to_s)
+          break
+        end
 
         if opts[:raw] && opts[:echo]
           clear_display(line, screen_width)
@@ -283,6 +286,8 @@ module TTY
           end
         end
 
+        trigger_key_event(char, line: line.to_s)
+
         if [CARRIAGE_RETURN, NEWLINE].include?(code)
           output.puts unless opts[:echo]
           break
@@ -421,8 +426,8 @@ module TTY
     # @return [nil]
     #
     # @api private
-    def trigger_key_event(char)
-      event = KeyEvent.from(console.keys, char)
+    def trigger_key_event(char, line: '')
+      event = KeyEvent.from(console.keys, char, line)
       trigger(:"key#{event.key.name}", event) if event.trigger?
       trigger(:keypress, event)
     end

data/lib/tty/reader/console.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 # frozen_string_literal: true
 
 require_relative 'keys'
@@ -42,8 +41,16 @@ module TTY
       # @api private
       def get_char(options)
         mode.raw(options[:raw]) do
-          mode.echo(options[:echo]) { input.getc }
+          mode.echo(options[:echo]) do
+            if options[:nonblock]
+              input.read_nonblock(1)
+            else
+              input.getc
+            end
+          end
         end
+      rescue IO::WaitReadable, EOFError
+        # no more bytes to read
       end
 
       protected

data/lib/tty/reader/history.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 # frozen_string_literal: true
 
 require 'forwardable'

data/lib/tty/reader/key_event.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 # frozen_string_literal: true
 
 require_relative 'keys'
@@ -17,7 +16,7 @@ module TTY
     # Represents key event emitted during keyboard press
     #
     # @api public
-    class KeyEvent < Struct.new(:value, :key)
+    class KeyEvent < Struct.new(:key, :value, :line)
       # Create key event from read input codes
       #
       # @param [Hash[Symbol]] keys
@@ -27,7 +26,7 @@ module TTY
       # @return [KeyEvent]
       #
       # @api public
-      def self.from(keys, char)
+      def self.from(keys, char, line = '')
         key = Key.new
         key.name = (name = keys[char]) ? name : :ignore
 
@@ -43,7 +42,7 @@ module TTY
           key.ctrl = true
         end
 
-        new(char, key)
+        new(key, char, line)
       end
 
       # Check if key event can be triggered

data/lib/tty/reader/keys.rb

@@ -1,4 +1,3 @@
-# encoding: utf-8
 # frozen_string_literal: true
 
 module TTY

data/lib/tty/reader/line.rb

@@ -30,13 +30,19 @@ module TTY
       # @api public
       attr_reader :mode
 
+      # The prompt displayed before input
+      # @api public
       attr_reader :prompt
 
-      def initialize(prompt, text = '')
+      # Create a Line instance
+      #
+      # @api private
+      def initialize(text = '', prompt: '')
         @prompt = prompt.dup
         @text   = text.dup
         @cursor = [0, @text.length].max
         @mode   = :edit
+
         yield self if block_given?
       end
 
@@ -128,6 +134,9 @@ module TTY
       # @param [Integer] i
       #   the index to insert at
       #
+      # @param [String] chars
+      #   the characters to insert
+      #
       # @example
       #   text = 'aaa'
       #   line[5]= 'b'
@@ -136,6 +145,7 @@ module TTY
       # @api public
       def []=(i, chars)
         edit_mode
+
         if i.is_a?(Range)
           @text[i] = chars
           @cursor += chars.length
@@ -145,10 +155,7 @@ module TTY
         if i <= 0
           before_text = ''
           after_text = @text.dup
-        elsif i == @text.length - 1
-          before_text = @text.dup
-          after_text = ''
-        elsif i > @text.length - 1
+        elsif i > @text.length - 1 # insert outside of line input
           before_text = @text.dup
           after_text = ?\s * (i - @text.length)
           @cursor += after_text.length