tty2-reader 0.9.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a44587ade2b8c04804f0af10d8254767432ef48fbf44b846b6139b71ec2bcd66
+  data.tar.gz: 419ad00150ac5a27e006fd193483a1babdc7ccc81d5045e9e45586879803bb05
+SHA512:
+  metadata.gz: 2aefc8c61704b430c04380ffc70317d3770578736d5596120d5a0459c1f28fd7dfea83922fc6bf0625d87ab7989f20eb870cb3475b6b2460bde9a08ca1ae7d1d
+  data.tar.gz: df40cf0b823f887d94a569568121363738b655afd127b0e6e21d9f8e4f2c258a3b12af72f61f3894c8c1f4ce38a659e85e4ea27b6fd4546e440a46f8f8d1235c

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Change log
+
+## [v0.9.0] - unreleased
+
+### Added
+* Added word completion
+
+### Changed
+* Forked TTY and reworked to TTY2
+* Extended KeyEvent with Line object
+
+### Fix
+
+
+[v0.9.0]: https://github.com/zzyzwicz/tty2-reader/compare/v0.9.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+
+# TTY2::Reader
+
+[![Gem Version](https://badge.fury.io/rb/tty2-reader.svg)][gem]
+[![Build status](https://ci.appveyor.com/api/projects/status/cj4owy2vlty2q1ko?svg=true)][appveyor]
+
+[gem]: http://badge.fury.io/rb/tty2-reader
+[gh_actions_ci]: https://github.com/zzyzwicz/tty2-reader/actions?query=workflow%3ACI
+
+> A tty-reader fork with the objective of adding a customized word completion mechanism.
+
+**TTY2::Reader** intends to be an up to date clone of [TTY::Reader](https://github.com/piotrmurach/tty-reader), solely extending it with a customized word completion mechanism.
+This page only covers the applied modifications.
+
+
+## Modifications
+
+* Renamed to TTY2::Reader
+* Extended KeyEvent with Line object
+* Added word completion
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "tty2-reader"
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install tty2-reader
+
+* [1. API (only the modified parts)](#1-api)
+  * [1.1 on](#11-on)
+* [2. Configuration (only the modified parts)](#2-configuration)
+  * [2.1 completion_handler](#21-completion_handler)
+  * [2.2 completion_suffix](#22-completion_suffix)
+  * [2.3 completion_cycling](#23-completion_cycling)
+
+## API
+
+### 1.1 on
+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| .... }
+```
+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 `Line` object of the currently edited line, a new `Line` object with empty content 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
+* `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:
+```ruby
+reader.on(:keypress) do |event|
+  if event.value == "j"
+    ...
+  end
+  if event.value == "k"
+    ...
+  end
+end
+```
+You can subscribe to more than one event:
+```ruby
+reader.on(:keypress) { |event| ... }
+      .on(:keydown)  { |event| ... }
+```
+
+## Configuration
+
+### 2.1. `:completion_handler`
+This option allows you to define possible completions. It accepts a `proc` with the word that is to be completed as a first, and a context in which the word is to be completed as a second argument. By default set to nil. To use this:
+```ruby
+reader = TTY2::Reader.new(completion_handler: ->(word, context) { ... })
+```
+
+### 2.2. `:completion_suffix`
+This option allows you to add a suffix to completed words. By default, no suffix is added. To add a suffix:
+```ruby
+reader = TTY2::Reader.new(completion_suffix: " ")
+```
+
+### 2.3. `:completion_cycling`
+This option controls cycling through completion suggestions. By default set to `true`, and can be disabled with:
+```ruby
+reader = TTY2::Reader.new(completion_cycling: false)
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/zzyzwicz/tty2-reader.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the TTY2::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) 2021 zzyzwicz. See LICENSE for further details.

data/lib/tty2/reader/completer.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require_relative "completions"
+
+module TTY2
+  class Reader
+    # Responsible for word completion
+    #
+    # @api private
+    class Completer
+      # The completion suggestions
+      attr_reader :completions
+
+      # The handler for finding word completion suggestions
+      attr_accessor :handler
+
+      # The suffix to add to suggested word completion
+      attr_accessor :suffix
+
+      # Enable / Disable Cycling
+     attr_accessor :cycling
+
+      # The word to complete
+      attr_reader :word
+
+      # Create a Completer instance
+      #
+      # @api private
+      def initialize(handler: nil, suffix: "", cycling: true)
+        @handler = handler
+        @suffix = suffix
+        @cycling = cycling
+        @completions = Completions.new
+        @show_initial = false
+        @word = ""
+      end
+
+      # Find a suggestion to complete a word
+      #
+      # @param [Line] line
+      #   the line to complete a word in
+      # @param [Symbol] direction
+      #   the direction in which to cycle through completions
+      # @param [Boolean] initial
+      #   whether to find initial or next completion suggestion
+      #
+      # @return [String, nil]
+      #   the completed word or nil when no suggestion is found
+      #
+      # @api public
+      def complete(line, direction: :next, initial: false)
+        if initial
+          complete_initial(line, direction: direction)
+        elsif @cycling
+          complete_next(line, direction: direction)
+        end
+      end
+
+      # Complete the initial word
+      #
+      # @param [Line] line
+      #   the line to complete a word in
+      # @param [Symbol] direction
+      #   the direction in which to cycle through completions
+      #
+      # @return [String, nil]
+      #   the completed word or nil when no suggestion is found
+      #
+      # @api public
+      def complete_initial(line, direction: :next)
+        completed_word = complete_word(line)
+        return if @completions.empty?
+        if @cycling && completions.size > 1
+          @word = line.word_to_complete
+          position = word.length
+          completions.previous if direction == :previous
+          completed_word = completions.get
+          line.insert(completed_word[position..-1])
+        end
+        completed_word
+      end
+
+      # Complete a word with the next suggestion from completions
+      #
+      # @param [Line] line
+      #   the line to complete a word in
+      # @param [Symbol] direction
+      #   the direction in which to cycle through completions
+      #
+      # @return [String, nil]
+      #   the completed word or nil when no suggestion is found
+      #
+      # @api public
+      def complete_next(line, direction: :next)
+        return if completions.size < 2
+
+        previous_suggestion = completions.get
+        first_or_last = direction == :previous ? :first? : :last?
+        if completions.send(first_or_last) && !@show_initial
+          @show_initial = true
+          completed_word = word
+        else
+          if @show_initial
+            @show_initial = false
+            previous_suggestion = word
+          end
+          completions.send(direction)
+          completed_word = completions.get
+        end
+
+        length_to_remove = previous_suggestion.length
+
+        line.remove(length_to_remove)
+        #Due to a suspected timeing issue, verify all chars have actually been removed
+        if line.word_to_complete.length == 0
+          line.insert(completed_word)
+          completed_word
+        else
+          completions.previous
+          return
+        end
+
+      end
+
+      # Get suggestions and populate completions
+      #
+      # @param [Line] line
+      #   the line to complete a word in
+      #
+      # @api public
+      def load_completions(line)
+        @word = line.word_to_complete
+        context = line.subtext[0..-@word.length]
+        suggestions = handler.(word, context)
+        suggestions = suggestions.grep(/^#{Regexp.escape(@word)}/)
+        completions.clear
+        return if suggestions.empty?
+        completions.concat(suggestions)
+      end
+
+      # Find suggestions and complete the current word as far as it is unambigous
+      #
+      # @param [Line] line
+      #   the line to complete a word in
+      #
+      # @return [String]
+      #   the completed word
+      #
+      # @api public
+      def complete_word(line)
+        load_completions(line)
+
+        return if completions.empty?
+
+        position = @word.length
+        if completions.size > 1
+          char = completions.first[position]
+          while completions.all? { |candidate| candidate[position] == char }
+            line.insert(char)
+            @word = line.word_to_complete
+            position = @word.length
+            char = completions.first[position]
+          end
+          completed_word = word
+        elsif completions.size == 1
+          completed_word = completions.first
+          line.insert(completions.first[position..-1] + suffix)
+        end
+
+        completed_word
+      end
+
+      # Cancel completion suggestion and revert to the initial word
+      #
+      # @param [Line] line
+      #   the line to cancel word completion in
+      #
+      # @api public
+      def cancel(line)
+        return if completions.empty?
+
+        completed_word = @show_initial ? word : completions.get
+        line.remove(completed_word.length)
+        line.insert(word)
+      end
+    end # Completer
+  end # Reader
+end # TTY2

data/lib/tty2/reader/completion_event.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module TTY2
+  class Reader
+    class CompletionEvent
+      # The suggested word completion
+      attr_reader :completion
+
+      # The completion suggestions
+      attr_reader :completions
+
+      # The line with word to complete
+      attr_reader :line
+
+      # The initial word to complete
+      attr_reader :word
+
+      # Create a CompletionEvent
+      #
+      # @param [Completer] completer
+      #   the word completer
+      # @param [String] completion
+      #   the word completion
+      # @param [String] line
+      #   the line with the word to complete
+      #
+      # @api public
+      def initialize(completer, completion, line)
+        @completion = completion
+        @completions = completer.completions.to_a
+        @line = line
+        @word = completer.word
+      end
+    end # CompletionEvent
+  end # Reader
+end # TTY2

data/lib/tty2/reader/completions.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module TTY2
+  class Reader
+    # Responsible for storing and navigating completion suggestions
+    #
+    # @api private
+    class Completions
+      include Enumerable
+      extend Forwardable
+
+      def_delegators :@completions, :size, :empty?
+
+      # Create a Completions collection
+      #
+      # @api public
+      def initialize
+        @completions = []
+        @index = 0
+      end
+
+      # Clear current completions
+      #
+      # @api public
+      def clear
+        @completions.clear
+        @index = 0
+      end
+
+      # Check whether the current index is at the first completion or not
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def first?
+        @index.zero?
+      end
+
+      # Check whether the current index is at the last completion or not
+      #
+      # @return [Boolean]
+      #
+      # @api public
+      def last?
+        @index == size - 1
+      end
+
+      # Add completion suggestions
+      #
+      # @param [Array<String>] suggestions
+      #   the suggestions to add
+      #
+      # @api public
+      def concat(suggestions)
+        suggestions.each { |suggestion| @completions << suggestion.dup }
+      end
+
+      # Iterate over all completions
+      #
+      # @api public
+      def each(&block)
+        if block_given?
+          @completions.each(&block)
+        else
+          @completions.to_enum
+        end
+      end
+
+      # Retrieve completion at the current index
+      #
+      # @return [String]
+      #
+      # @api public
+      def get
+        @completions[@index]
+      end
+
+      # Move index to the next completion
+      #
+      # @api public
+      def next
+        return if size.zero?
+
+        if @index == size - 1
+          @index = 0
+        else
+          @index += 1
+        end
+      end
+
+      # Move index to the previous completion
+      #
+      # @api public
+      def previous
+        return if size.zero?
+
+        if @index.zero?
+          @index = size - 1
+        else
+          @index -= 1
+        end
+      end
+    end # Completions
+  end # Reader
+end # TTY2

data/lib/tty2/reader/console.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "io/wait"
+
+require_relative "keys"
+require_relative "mode"
+
+module TTY2
+  class Reader
+    class Console
+      ESC = "\e"
+      CSI = "\e["
+
+      TIMEOUT = 0.1
+
+      # Key codes
+      #
+      # @return [Hash[Symbol]]
+      #
+      # @api public
+      attr_reader :keys
+
+      # Escape codes
+      #
+      # @return [Array[Integer]]
+      #
+      # @api public
+      attr_reader :escape_codes
+
+      def initialize(input)
+        @input = input
+        @mode  = Mode.new(input)
+        @keys  = Keys.ctrl_keys.merge(Keys.keys)
+        @escape_codes = [[ESC.ord], CSI.bytes.to_a]
+      end
+
+      # Get a character from console with echo
+      #
+      # @param [Boolean] echo
+      #   whether to echo input back or not, defaults to true
+      # @param [Boolean] raw
+      #   whether to use raw mode or not, defaults to false
+      # @param [Boolean] nonblock
+      #   whether to wait for input or not, defaults to false
+      #
+      # @return [String]
+      #
+      # @api private
+      def get_char(echo: true, raw: false, nonblock: false)
+        mode.raw(raw) do
+          mode.echo(echo) do
+            if nonblock
+              input.wait_readable(TIMEOUT) ? input.getc : nil
+            else
+              input.getc
+            end
+          end
+        end
+      end
+
+      protected
+
+      attr_reader :mode
+
+      attr_reader :input
+    end # Console
+  end # Reader
+end # TTY2