tty-reader 0.3.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: c03f74e7241085592fa20639a1e611fcc67236e0
-  data.tar.gz: 4e86e58a736ac624efcbb11bd4d4d09a7e80e7ed
+SHA256:
+  metadata.gz: 7f034dd9a1da1468f59ef2cf8c1ef164c5d85991d7aa0d9760eca05558d09978
+  data.tar.gz: '097df714a88a98b2352e202e69c7da48db124a8f637516449676a8647aee31f3'
 SHA512:
-  metadata.gz: ce215884478b45022b5e44a0f464906880dedcfb059f8f265ac6a016a41a622385ef2c899bb370c8f63d3417fac4ebcfb9ac284d819e7e97220c3ad0d52ee8bf
-  data.tar.gz: 7bf7f7e083acfefef98c5806f54c4e14398d286cb7e926f79a41ef7b4216f77d3d312074d1703a306bd4b280bccccc8e17ceb648d37e1419fada48aac10ab868
+  metadata.gz: 04cf6b1571693791baadf0f686f320393e17a0bd6b1a51aa61c28a34b20e65cb5a6efcca77a3ef21b0c4e2ff422ce3467cea3285b7c477783a5c91f3b1f08bde
+  data.tar.gz: ef5d9d50c2bad451a4cb326547e979a36bca173c0f02df90c202fc702823bd12c2bed8c47d0b47e16ccd6a9d1b644552d1ecea3f605629afaa0b975ac60d0b2b

data/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Change log
 
+## [v0.8.0] - 2020-06-28
+
+### Changed
+* Change gemspec to load version directly and remove test artefacts
+* Change to update tty-screen dependency
+* Change to remove bundler dev dependency and relax wisper version
+
+## [v0.7.0] - 2019-11-24
+
+### Added
+* Add support for a multi-line prompt by Katelyn Schiesser(@slowbro)
+* Add metadata to gemspec
+
+## [v0.6.0] - 2019-05-27
+
+### Added
+* Add :value option to #read_line to allow pre-populating of line content
+
+### Changed
+* Change to make InputInterrupt to derive from Interrupt by Samuel Williams(@ioquatix)
+* Change #read_line to trigger before line is printed to allow for line changes in key callbacks
+* Change Console#get_char :nonblock option to wait for readable input without blocking
+* Change to remove bundler version constraints
+* Change to update tty-screen dependency
+* Change to update tty-cursor dependency
+
+## [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
@@ -33,6 +73,11 @@
 
 * Initial implementation and release
 
+[v0.8.0]: https://github.com/piotrmurach/tty-reader/compare/v0.7.0...v0.8.0
+[v0.7.0]: https://github.com/piotrmurach/tty-reader/compare/v0.6.0...v0.7.0
+[v0.6.0]: https://github.com/piotrmurach/tty-reader/compare/v0.5.0...v0.6.0
+[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
@@ -85,6 +112,7 @@ To read a single key stroke from the user use `read_char` or `read_keypress`:
 ```ruby
 reader.read_char
 reader.read_keypress
+reader.read_keypress(nonblock: true)
 ```
 
 ### 2.2 read_line
@@ -109,11 +137,18 @@ 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(">> ")
-# >> input goes here ...
+# >>
+```
+
+To pre-populate the line content for editing use `:value` option:
+
+```ruby
+reader.read_line("> ", value: "edit me")
+# > edit me
 ```
 
 ### 2.3 read_multiline
@@ -133,7 +168,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 +176,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
@@ -189,13 +238,13 @@ class MyListener
 end
 ```
 
-Then subcribing is done:
+Then subscribing is done:
 
 ```ruby
 reader.subscribe(MyListener.new)
 ```
 
-Alternatively, `subscribe` allows you to listen to events only for the dueration of block execution like so:
+Alternatively, `subscribe` allows you to listen to events only for the duration of block execution like so:
 
 ```ruby
 reader.subscribe(MyListener) do
@@ -249,7 +298,7 @@ The available key events for character input are:
 * `:keyalpha`
 * `:keynum`
 
-The navigation relted key events are:
+The navigation related key events are:
 
 * `:keydown`
 * `:keyup`
@@ -292,7 +341,7 @@ 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:
+The `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:
 
 ```ruby
 reader = TTY::Reader.new(track_history: false)
@@ -316,7 +365,7 @@ 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:
+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 exclude empty lines. To change this:
 
 ```ruby
 reader = TTY::Reader.new(history_exclude: ->(line) { ... })
@@ -349,4 +398,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/lib/tty-reader.rb

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

data/lib/tty/reader.rb

@@ -1,16 +1,15 @@
-# encoding: utf-8
 # frozen_string_literal: true
 
-require 'tty-cursor'
-require 'tty-screen'
-require 'wisper'
+require "tty-cursor"
+require "tty-screen"
+require "wisper"
 
-require_relative 'reader/history'
-require_relative 'reader/line'
-require_relative 'reader/key_event'
-require_relative 'reader/console'
-require_relative 'reader/win_console'
-require_relative 'reader/version'
+require_relative "reader/history"
+require_relative "reader/line"
+require_relative "reader/key_event"
+require_relative "reader/console"
+require_relative "reader/win_console"
+require_relative "reader/version"
 
 module TTY
   # A class responsible for reading character input from STDIN
@@ -24,7 +23,7 @@ module TTY
     # Raised when the user hits the interrupt key(Control-C)
     #
     # @api public
-    InputInterrupt = Class.new(StandardError)
+    InputInterrupt = Class.new(Interrupt)
 
     # Check if Windowz mode
     #
@@ -32,7 +31,7 @@ module TTY
     #
     # @api public
     def self.windows?
-      ::File::ALT_SEPARATOR == '\\'
+      ::File::ALT_SEPARATOR == "\\"
     end
 
     attr_reader :input
@@ -75,7 +74,7 @@ module TTY
 
       @track_history = options.fetch(:track_history) { true }
       @history_cycle = options.fetch(:history_cycle) { false }
-      exclude_proc   = ->(line) { line.strip == '' }
+      exclude_proc   = ->(line) { line.strip == "" }
       @history_exclude    = options.fetch(:history_exclude) { exclude_proc }
       @history_duplicates = options.fetch(:history_duplicates) { false }
 
@@ -132,7 +131,7 @@ module TTY
     #
     # @api private
     def select_console(input)
-      if self.class.windows? && !env['TTY_TEST']
+      if self.class.windows? && !env["TTY_TEST"]
         WinConsole.new(input)
       else
         Console.new(input)
@@ -173,7 +172,7 @@ module TTY
     def read_keypress(options = {})
       opts  = { echo: false, raw: true }.merge(options)
       codes = unbufferred { get_codes(opts) }
-      char  = codes ? codes.pack('U*') : nil
+      char  = codes ? codes.pack("U*") : nil
 
       trigger_key_event(char) if char
       char
@@ -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
 
@@ -214,24 +215,30 @@ module TTY
     # @param [String] prompt
     #   the prompt to display before input
     #
+    # @param [String] value
+    #   the value to pre-populate line with
+    #
     # @param [Boolean] echo
     #   if true echo back characters, output nothing otherwise
     #
     # @return [String]
     #
     # @api public
-    def read_line(prompt = '', **options)
+    def read_line(prompt = "", **options)
       opts = { echo: true, raw: true }.merge(options)
-      line = Line.new(prompt, '')
+      value = options.fetch(:value, "")
+      line = Line.new(value, prompt: prompt)
       screen_width = TTY::Screen.width
 
-      output.print(line.prompt)
+      output.print(line)
 
       while (codes = get_codes(opts)) && (code = codes[0])
-        char = codes.pack('U*')
-        trigger_key_event(char)
+        char = codes.pack("U*")
 
-        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)
@@ -249,7 +256,7 @@ module TTY
         elsif console.keys[char] == :up
           line.replace(history_previous) if history_previous?
         elsif console.keys[char] == :down
-          line.replace(history_next? ? history_next : '')
+          line.replace(history_next? ? history_next : "")
         elsif console.keys[char] == :left
           line.left
         elsif console.keys[char] == :right
@@ -270,10 +277,13 @@ module TTY
           if opts[:raw]
             output.print("\e[1X") unless line.start?
           else
-            output.print(?\s + (line.start? ? '' : ?\b))
+            output.print(?\s + (line.start? ? "" : ?\b))
           end
         end
 
+        # trigger before line is printed to allow for line changes
+        trigger_key_event(char, line: line.to_s)
+
         if opts[:raw] && opts[:echo]
           output.print(line.to_s)
           if char == "\n"
@@ -352,7 +362,7 @@ module TTY
       lines = []
       loop do
         line = read_line(*args)
-        break if !line || line == ''
+        break if !line || line == ""
         next  if line !~ /\S/ && !@stop
         if block_given?
           yield(line) unless line.to_s.empty?
@@ -421,8 +431,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
@@ -433,7 +443,7 @@ module TTY
     def handle_interrupt
       case @interrupt
       when :signal
-        Process.kill('SIGINT', Process.pid)
+        Process.kill("SIGINT", Process.pid)
       when :exit
         exit(130)
       when Proc

data/lib/tty/reader/console.rb

@@ -1,14 +1,17 @@
-# encoding: utf-8
 # frozen_string_literal: true
 
-require_relative 'keys'
-require_relative 'mode'
+require "io/wait"
+
+require_relative "keys"
+require_relative "mode"
 
 module TTY
   class Reader
     class Console
-      ESC = "\e".freeze
-      CSI = "\e[".freeze
+      ESC = "\e"
+      CSI = "\e["
+
+      TIMEOUT = 0.1
 
       # Key codes
       #
@@ -42,7 +45,13 @@ 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.wait_readable(TIMEOUT) ? input.getc : nil
+            else
+              input.getc
+            end
+          end
         end
       end