tty-reader 0.4.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d01c5aa8afa041b5ceae747d42f8e94a0fb5dd63dc19f6cff8e9165caa4b014b
-  data.tar.gz: b37800731d9ea2f8c25658d2d8e37069b7a253fa2229214603b79e165ece3ede
+  metadata.gz: 7766384b749f39d5646ce4ff20d95c1bdfdaac5af096d4a996a7a347379874ee
+  data.tar.gz: c5a85b72fae90d018f79acdd9303c9926b75236fb67a2b24e641f6737a001372
 SHA512:
-  metadata.gz: e64edab17527852f8fe1caba07554adbcc9040b1cd56472c23d4b0648215bc7fcf1ad159c6cd5de6dcd79e4606b9f199da2b461ade1ed5519f3f27f3038d6189
-  data.tar.gz: f68401fc9bcc6e9227e58562b02cf20e4ee1a88614f87299acdcd374105daf80de4bdcce4d6dfbc12dc131139b44716070050b55f7127e2a963904f8f0a7006f
+  metadata.gz: 74bd44d949d086d8debe53bdd571755b263fce26d991dd7798d45fbb24513cdadea0a29c31e3388a65ce8f81f3b3514955d69c44c30af87465ba32933f5f6997
+  data.tar.gz: 4ad0c8d086506a2672f2a8bb8db1fbd9f951e2f1f9200f4c258e82967cf61bbea209a33fdd86aa4cfb99adf4e5b7fcdcf6e5b0f992da6fe9956daa5d5aade238

data/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Change log
+
+## [v0.9.0] - 2020-12-08
+
+### Added
+* Add buffer to save input when traversing history and restore it back
+  similar to shell
+
+### Changed
+* Pressing :down no longer erases the #read_line input if history is disabled by Charles Pence (@pencechp)
+* Change Reader initializer to use keyword arguments in place of options hash
+* Change history to only exclude empty lines without any space or invisible characters
+* Change all input reading methods to use explicit keyword arguments
+
+### Fix
+* Fix #read_multiline :value parameter to insert content only once in the first line
+
+## [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
+* 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.9.0]: https://github.com/piotrmurach/tty-reader/compare/v0.8.0...v0.9.0
+[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/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017 Piotr Murach
+Copyright (c) 2017 Piotr Murach (https://piotrmurach.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,7 +1,11 @@
+<div align="center">
+  <a href="https://ttytoolkit.org"><img width="130" src="https://github.com/piotrmurach/tty/raw/master/images/tty.png" alt="TTY Toolkit 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]
-[![Build Status](https://secure.travis-ci.org/piotrmurach/tty-reader.svg?branch=master)][travis]
+[![Actions CI](https://github.com/piotrmurach/tty-reader/workflows/CI/badge.svg?branch=master)][gh_actions_ci]
 [![Build status](https://ci.appveyor.com/api/projects/status/cj4owy2vlty2q1ko?svg=true)][appveyor]
 [![Maintainability](https://api.codeclimate.com/v1/badges/2f68d5e8ecc271bda820/maintainability)][codeclimate]
 [![Coverage Status](https://coveralls.io/repos/github/piotrmurach/tty-reader/badge.svg)][coverage]
@@ -9,16 +13,19 @@
 
 [gitter]: https://gitter.im/piotrmurach/tty
 [gem]: http://badge.fury.io/rb/tty-reader
+[gh_actions_ci]: https://github.com/piotrmurach/tty-reader/actions?query=workflow%3ACI
 [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/maintainability
 [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 +35,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
@@ -42,7 +49,7 @@ The `tty-reader` is not compatible with the GNU Readline and doesn't aim to be.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'tty-reader'
+gem "tty-reader"
 ```
 
 And then execute:
@@ -72,10 +79,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 +113,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 +138,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 +169,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 +177,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
@@ -158,11 +208,11 @@ For example, to add listen to vim like navigation keys, one would do the followi
 
 ```ruby
 reader.on(:keypress) do |event|
-  if event.value == 'j'
+  if event.value == "j"
     ...
   end
 
-  if event.value == 'k'
+  if event.value == "k"
     ...
   end
 end
@@ -171,8 +221,8 @@ end
 You can subscribe to more than one event:
 
 ```ruby
-prompt.on(:keypress) { |key| ... }
-      .on(:keydown)  { |key| ... }
+reader.on(:keypress) { |event| ... }
+      .on(:keydown)  { |event| ... }
 ```
 
 ### 2.5 subscribe
@@ -189,13 +239,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
@@ -225,10 +275,10 @@ To add vim bindings for line editing you could discern between alphanumeric inpu
 
 ```ruby
 reader.on(:keypress) do |event|
-  if event.value == 'j'
+  if event.value == "j"
     reader.trigger(:keydown)
   end
-  if evevnt.value == 'k'
+  if evevnt.value == "k"
     reader.trigger(:keyup)
   end
 end
@@ -249,7 +299,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 +342,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 +366,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 +399,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
@@ -21,10 +20,19 @@ module TTY
   class Reader
     include Wisper::Publisher
 
+    # Key codes
+    CARRIAGE_RETURN = 13
+    NEWLINE         = 10
+    BACKSPACE       = 8
+    DELETE          = 127
+
+    # Keys that terminate input
+    EXIT_KEYS = [:ctrl_d, :ctrl_z]
+
     # 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 +40,7 @@ module TTY
     #
     # @api public
     def self.windows?
-      ::File::ALT_SEPARATOR == '\\'
+      ::File::ALT_SEPARATOR == "\\"
     end
 
     attr_reader :input
@@ -48,42 +56,44 @@ module TTY
 
     attr_reader :cursor
 
-    # Key codes
-    CARRIAGE_RETURN = 13
-    NEWLINE         = 10
-    BACKSPACE       = 8
-    DELETE          = 127
-
     # Initialize a Reader
     #
     # @param [IO] input
     #   the input stream
     # @param [IO] output
     #   the output stream
-    # @param [Hash] options
-    # @option options [Symbol] :interrupt
-    #   handling of Ctrl+C key out of :signal, :exit, :noop
-    # @option options [Boolean] :track_history
+    # @param [Symbol] interrupt
+    #   the way to handle the Ctrl+C key out of :signal, :exit, :noop
+    # @param [Hash] env
+    #   the environment variables
+    # @param [Boolean] track_history
     #   disable line history tracking, true by default
+    # @param [Boolean] history_cycle
+    #   allow cycling through history, false by default
+    # @param [Boolean] history_duplicates
+    #   allow duplicate entires, false by default
+    # @param [Proc] history_exclude
+    #   exclude lines from history, by default all lines are stored
     #
     # @api public
-    def initialize(**options)
-      @input     = options.fetch(:input) { $stdin }
-      @output    = options.fetch(:output) { $stdout }
-      @interrupt = options.fetch(:interrupt) { :error }
-      @env       = options.fetch(:env) { ENV }
-
-      @track_history = options.fetch(:track_history) { true }
-      @history_cycle = options.fetch(:history_cycle) { false }
-      exclude_proc   = ->(line) { line.strip == '' }
-      @history_exclude    = options.fetch(:history_exclude) { exclude_proc }
-      @history_duplicates = options.fetch(:history_duplicates) { false }
-
-      @console   = select_console(input)
-      @history   = History.new do |h|
-        h.cycle = @history_cycle
-        h.duplicates = @history_duplicates
-        h.exclude = @history_exclude
+    def initialize(input: $stdin, output: $stdout, interrupt: :error,
+                   env: ENV, track_history: true, history_cycle: false,
+                   history_exclude: History::DEFAULT_EXCLUDE,
+                   history_duplicates: false)
+      @input = input
+      @output = output
+      @interrupt = interrupt
+      @env = env
+      @track_history = track_history
+      @history_cycle = history_cycle
+      @history_exclude = history_exclude
+      @history_duplicates = history_duplicates
+
+      @console = select_console(input)
+      @history = History.new do |h|
+        h.cycle = history_cycle
+        h.duplicates = history_duplicates
+        h.exclude = history_exclude
       end
       @stop = false # gathering input
       @cursor = TTY::Cursor
@@ -132,7 +142,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)
@@ -156,24 +166,26 @@ module TTY
       output.sync = bufferring
     end
 
-    # Read a keypress  including invisible multibyte codes
-    # and return a character as a string.
+    # Read a keypress including invisible multibyte codes and return
+    # a character as a string.
     # Nothing is echoed to the console. This call will block for a
     # single keypress, but will not wait for Enter to be pressed.
     #
-    # @param [Hash[Symbol]] options
-    # @option options [Boolean] echo
+    # @param [Boolean] echo
     #   whether to echo chars back or not, defaults to false
-    # @option options [Boolean] raw
-    #   whenther raw mode enabled, defaults to true
+    # @option [Boolean] raw
+    #   whenther raw mode is enabled, defaults to true
+    # @option [Boolean] nonblock
+    #   whether to wait for input or not, defaults to false
     #
     # @return [String]
     #
     # @api public
-    def read_keypress(options = {})
-      opts  = { echo: false, raw: true }.merge(options)
-      codes = unbufferred { get_codes(opts) }
-      char  = codes ? codes.pack('U*') : nil
+    def read_keypress(echo: false, raw: true, nonblock: false)
+      codes = unbufferred do
+        get_codes(echo: echo, raw: raw, nonblock: nonblock)
+      end
+      char = codes ? codes.pack("U*") : nil
 
       trigger_key_event(char) if char
       char
@@ -182,19 +194,24 @@ module TTY
 
     # Get input code points
     #
-    # @param [Hash[Symbol]] options
+    # @param [Boolean] echo
+    #   whether to echo chars back or not, defaults to false
+    # @option [Boolean] raw
+    #   whenther raw mode is enabled, defaults to true
+    # @option [Boolean] nonblock
+    #   whether to wait for input or not, defaults to false
     # @param [Array[Integer]] codes
+    #   the currently read char code points
     #
     # @return [Array[Integer]]
     #
     # @api private
-    def get_codes(options = {}, codes = [])
-      opts = { echo: true, raw: false }.merge(options)
-      char = console.get_char(opts)
+    def get_codes(echo: true, raw: false, nonblock: false, codes: [])
+      char = console.get_char(echo: echo, raw: raw, nonblock: nonblock)
       handle_interrupt if console.keys[char] == :ctrl_c
       return if char.nil?
-      codes << char.ord
 
+      codes << char.ord
       condition = proc { |escape|
         (codes - escape).empty? ||
         (escape - codes).empty? &&
@@ -202,8 +219,11 @@ module TTY
       }
 
       while console.escape_codes.any?(&condition)
-        get_codes(options, codes)
+        char_codes = get_codes(echo: echo, raw: raw,
+                               nonblock: true, codes: codes)
+        break if char_codes.nil?
       end
+
       codes
     end
 
@@ -213,43 +233,51 @@ 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
+    #   whether to echo chars back or not, defaults to false
+    # @option [Boolean] raw
+    #   whenther raw mode is enabled, defaults to true
+    # @option [Boolean] nonblock
+    #   whether to wait for input or not, defaults to false
     #
     # @return [String]
     #
     # @api public
-    def read_line(prompt = '', **options)
-      opts = { echo: true, raw: true }.merge(options)
-      line = Line.new(prompt, '')
+    def read_line(prompt = "", value: "", echo: true, raw: true, nonblock: false)
+      line = Line.new(value, prompt: prompt)
       screen_width = TTY::Screen.width
+      buffer = ""
 
-      output.print(line.prompt)
+      output.print(line)
 
-      while (codes = get_codes(opts)) && (code = codes[0])
-        char = codes.pack('U*')
-        trigger_key_event(char)
+      while (codes = get_codes(echo: echo, raw: raw, nonblock: nonblock)) &&
+            (code = codes[0])
+        char = codes.pack("U*")
 
-        break if [:ctrl_d, :ctrl_z].include?(console.keys[char])
+        if EXIT_KEYS.include?(console.keys[char])
+          trigger_key_event(char, line: line.to_s)
+          break
+        end
 
-        if opts[:raw] && opts[:echo]
+        if raw && echo
           clear_display(line, screen_width)
         end
 
-        if console.keys[char] == :backspace || BACKSPACE == code
+        if console.keys[char] == :backspace || code == BACKSPACE
           if !line.start?
             line.left
             line.delete
           end
-        elsif console.keys[char] == :delete || DELETE == code
+        elsif console.keys[char] == :delete || code == DELETE
           line.delete
         elsif console.keys[char].to_s =~ /ctrl_/
           # skip
         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 : buffer) if track_history?
         elsif console.keys[char] == :left
           line.left
         elsif console.keys[char] == :right
@@ -259,22 +287,26 @@ module TTY
         elsif console.keys[char] == :end
           line.move_to_end
         else
-          if opts[:raw] && code == CARRIAGE_RETURN
+          if raw && code == CARRIAGE_RETURN
             char = "\n"
             line.move_to_end
           end
           line.insert(char)
+          buffer = line.text
         end
 
-        if (console.keys[char] == :backspace || BACKSPACE == code) && opts[:echo]
-          if opts[:raw]
+        if (console.keys[char] == :backspace || code == BACKSPACE) && echo
+          if raw
             output.print("\e[1X") unless line.start?
           else
-            output.print(?\s + (line.start? ? '' : ?\b))
+            output.print(?\s + (line.start? ? "" : ?\b))
           end
         end
 
-        if opts[:raw] && opts[:echo]
+        # trigger before line is printed to allow for line changes
+        trigger_key_event(char, line: line.to_s)
+
+        if raw && echo
           output.print(line.to_s)
           if char == "\n"
             line.move_to_start
@@ -284,13 +316,16 @@ module TTY
         end
 
         if [CARRIAGE_RETURN, NEWLINE].include?(code)
-          output.puts unless opts[:echo]
+          buffer = ""
+          output.puts unless echo
           break
         end
       end
-      if track_history? && opts[:echo]
+
+      if track_history? && echo
         add_to_history(line.text.rstrip)
       end
+
       line.text
     end
 
@@ -341,19 +376,33 @@ module TTY
     #
     # @param [String] prompt
     #   the prompt displayed before the input
+    # @param [String] value
+    #   the value to pre-populate line with
+    # @param [Boolean] echo
+    #   whether to echo chars back or not, defaults to false
+    # @option [Boolean] raw
+    #   whenther raw mode is enabled, defaults to true
+    # @option [Boolean] nonblock
+    #   whether to wait for input or not, defaults to false
     #
     # @yield [String] line
     #
     # @return [Array[String]]
     #
     # @api public
-    def read_multiline(*args)
+    def read_multiline(prompt = "", value: "", echo: true, raw: true,
+                       nonblock: false)
       @stop = false
       lines = []
+      empty_str = ""
+
       loop do
-        line = read_line(*args)
-        break if !line || line == ''
+        line = read_line(prompt, value: value, echo: echo, raw: raw,
+                                 nonblock: nonblock)
+        value = empty_str unless value.empty? # reset
+        break if !line || line == empty_str
         next  if line !~ /\S/ && !@stop
+
         if block_given?
           yield(line) unless line.to_s.empty?
         else
@@ -361,6 +410,7 @@ module TTY
         end
         break if @stop
       end
+
       lines
     end
     alias read_lines read_multiline
@@ -421,8 +471,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,13 +483,13 @@ 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
         @interrupt.call
       when :noop
-        return
+        # Noop
       else
         raise InputInterrupt
       end