tty-reader 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 4450cd173fbc5dece09c32d0ad799bb5fcccff3a
+  data.tar.gz: e744eaefca8e5b03f79b41d502fe71a2ba8b3166
+SHA512:
+  metadata.gz: b113279156eb75f4f2c7079abe5c225993c4f0b24bd33fb07dd45366e316bf9a9356ea23b0f96cf122e36502fa85161d8ccc33f7a4e8ef2dae57faf184f4f77a
+  data.tar.gz: 21fd68ce3809c21a88dd24d18ec25348e4111fc41a7828c6c2bb3ccb6279f7fed3477c1261d9d65e3911f8d6c5656f92f908fee5ac9d1ab44609100feb9c9a5c

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--require spec_helper
+--warnings

data/.travis.yml

@@ -0,0 +1,25 @@
+---
+language: ruby
+sudo: false
+cache: 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
+  - ruby-head
+  - jruby-9000
+  - jruby-head
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+    - rvm: jruby-head
+  fast_finish: true
+branches:
+  only: master
+notifications:
+  email: false

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Change log
+
+## [v0.1.0] - 2017-08-30
+
+* Initial implementation and release
+
+[v0.1.0]: https://github.com/peter-murach/tty-reader/compare/v0.1.0

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at [email]. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,21 @@
+source "https://rubygems.org"
+
+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'
+end
+
+group :tools do
+  gem 'byebug', platform: :mri
+end
+
+group :metrics do
+  gem 'yard',      '~> 0.8.7'
+  gem 'yardstick', '~> 0.9.9'
+end

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2017 Piotr Murach
+
+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,187 @@
+# 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]
+[![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]
+[![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]
+
+[gitter]: https://gitter.im/piotrmurach/tty
+[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
+[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.
+
+**TTY::Reader** provides independent reader component for [TTY](https://github.com/piotrmurach/tty) toolkit.
+
+## Features
+
+* Reading single keypress
+* Line editing
+* Multiline input
+* History management
+* Ability to register for key events
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'tty-reader'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install tty-reader
+
+* [1. Usage](#1-usage)
+* [2. API](#2-api)
+  * [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)
+* [3. Configuration](#3-configuration)
+  * [3.1 :interrupt](#31-interrupt)
+  * [3.2 :track_history](#31-track_history)
+
+## Usage
+
+```ruby
+reader = TTY::Reader.new
+```
+
+## API
+
+### 2.1 read_keypress
+
+To read a single key stroke from the user use `read_char` or `read_keypress`:
+
+```ruby
+reader.read_char
+reader.read_keypress
+```
+
+## 2.2 read_line
+
+To read a single line terminated by new line character use `read_line` like so:
+
+```ruby
+reader.read_line
+```
+
+## 2.3 read_multiline
+
+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
+
+You can register to listen on a key pressed events. This can be done by calling `on` with a event name:
+
+```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:
+
+* `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
+prompt.on(:keypress) { |key| ... }
+      .on(:keydown)  { |key| ... }
+```
+
+The available events are:
+
+* `:keypress`
+* `:keydown`
+* `:keyup`
+* `:keyleft`
+* `:keyright`
+* `:keynum`
+* `:keytab`
+* `:keyenter`
+* `:keyreturn`
+* `:keyspace`
+* `:keyescape`
+* `:keydelete`
+* `:keybackspace`
+
+## 3. Configuration
+
+### 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:
+
+* `:signal` - sends interrupt signal
+* `:exit` - exists with status code
+* `:noop` - skips handler
+* custom proc
+
+For example, to send interrupt signal do:
+
+```ruby
+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:
+
+```ruby
+reader = TTY::Reader.new(track_history: false)
+```
+
+## 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.
+
+## 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 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.

data/Rakefile

@@ -0,0 +1,10 @@
+# encoding: utf-8
+
+require "bundler/gem_tasks"
+
+FileList['tasks/**/*.rake'].each(&method(:import))
+
+desc 'Run all specs'
+task ci: %w[ spec ]
+
+task default: :spec

data/appveyor.yml

@@ -0,0 +1,25 @@
+---
+install:
+  - SET PATH=C:\Ruby%ruby_version%\bin;%PATH%
+  - ruby --version
+  - gem --version
+  - bundle install
+build: off
+test_script:
+  - bundle exec rake ci
+environment:
+  matrix:
+    - ruby_version: "193"
+    - ruby_version: "200"
+    - ruby_version: "200-x64"
+    - ruby_version: "21"
+    - ruby_version: "21-x64"
+    - ruby_version: "22"
+    - ruby_version: "22-x64"
+    - ruby_version: "23"
+    - ruby_version: "23-x64"
+    - ruby_version: "24"
+    - ruby_version: "24-x64"
+matrix:
+  allow_failures:
+    - ruby_version: "193"

data/bin/console

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "tty/reader"
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/tty-reader.rb

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

data/lib/tty/reader.rb

@@ -0,0 +1,348 @@
+# encoding: utf-8
+# frozen_string_literal: true
+
+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'
+
+module TTY
+  # A class responsible for reading character input from STDIN
+  #
+  # Used internally to provide key and line reading functionality
+  #
+  # @api private
+  class Reader
+    include Wisper::Publisher
+
+    # Raised when the user hits the interrupt key(Control-C)
+    #
+    # @api public
+    InputInterrupt = Class.new(StandardError)
+
+    attr_reader :input
+
+    attr_reader :output
+
+    attr_reader :env
+
+    attr_reader :track_history
+    alias track_history? track_history
+
+    attr_reader :console
+
+    # Key codes
+    CARRIAGE_RETURN = 13
+    NEWLINE         = 10
+    BACKSPACE       = 127
+    DELETE          = 8
+
+    # 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
+    #   disable line history tracking, true by default
+    #
+    # @api public
+    def initialize(input = $stdin, output = $stdout, options = {})
+      @input     = input
+      @output    = output
+      @interrupt = options.fetch(:interrupt) { :error }
+      @env       = options.fetch(:env) { ENV }
+      @track_history = options.fetch(:track_history) { true }
+      @console   = select_console(input)
+      @history   = History.new do |h|
+        h.duplicates = false
+        h.exclude = proc { |line| line.strip == '' }
+      end
+      @stop = false # gathering input
+
+      subscribe(self)
+    end
+
+    # Select appropriate console
+    #
+    # @api private
+    def select_console(input)
+      if windows? && !env['TTY_TEST']
+        WinConsole.new(input)
+      else
+        Console.new(input)
+      end
+    end
+
+    # Get input in unbuffered mode.
+    #
+    # @example
+    #   unbufferred do
+    #     ...
+    #   end
+    #
+    # @api public
+    def unbufferred(&block)
+      bufferring = output.sync
+      # Immediately flush output
+      output.sync = true
+      block[] if block_given?
+    ensure
+      output.sync = bufferring
+    end
+
+    # 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
+    #   whether to echo chars back or not, defaults to false
+    # @option options [Boolean] raw
+    #   whenther raw mode enabled, defaults to true
+    #
+    # @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
+
+      trigger_key_event(char) if char
+      char
+    end
+    alias read_char read_keypress
+
+    # Get input code points
+    #
+    # @param [Hash[Symbol]] options
+    # @param [Array[Integer]] codes
+    #
+    # @return [Array[Integer]]
+    #
+    # @api private
+    def get_codes(options = {}, codes = [])
+      opts = { echo: true, raw: false }.merge(options)
+      char = console.get_char(opts)
+      handle_interrupt if char == console.keys[:ctrl_c]
+      return if char.nil?
+      codes << char.ord
+
+      condition = proc { |escape|
+        (codes - escape).empty? ||
+        (escape - codes).empty? &&
+        !(64..126).include?(codes.last)
+      }
+
+      while console.escape_codes.any?(&condition)
+        get_codes(options, codes)
+      end
+      codes
+    end
+
+    # Get a single line from STDIN. Each key pressed is echoed
+    # back to the shell. The input terminates when enter or
+    # return key is pressed.
+    #
+    # @param [String] prompt
+    #   the prompt to display before input
+    #
+    # @param [Boolean] echo
+    #   if true echo back characters, output nothing otherwise
+    #
+    # @return [String]
+    #
+    # @api public
+    def read_line(*args)
+      options = args.last.respond_to?(:to_hash) ? args.pop : {}
+      prompt = args.empty? ? '' : args.pop
+      opts = { echo: true, raw: true }.merge(options)
+      line = Line.new('')
+      ctrls = console.keys.keys.grep(/ctrl/)
+      clear_line = "\e[2K\e[1G"
+
+      while (codes = unbufferred { get_codes(opts) }) && (code = codes[0])
+        char = codes.pack('U*')
+        trigger_key_event(char)
+
+        if console.keys[:backspace] == char || BACKSPACE == code
+          next if line.start?
+          line.left
+          line.delete
+        elsif console.keys[:delete] == char || DELETE == code
+          line.delete
+        elsif [console.keys[:ctrl_d],
+                console.keys[:ctrl_z]].include?(char)
+          break
+        elsif ctrls.include?(console.keys.key(char))
+          # skip
+        elsif console.keys[:up] == char
+          next unless history_previous?
+          line.replace(history_previous)
+        elsif console.keys[:down] == char
+          line.replace(history_next? ? history_next : '')
+        elsif console.keys[:left] == char
+          line.left
+        elsif console.keys[:right] == char
+          line.right
+        else
+          if opts[:raw] && code == CARRIAGE_RETURN
+            char = "\n"
+            line.move_to_end
+          end
+          line.insert(char)
+        end
+
+        if opts[:raw] && opts[:echo]
+          output.print(clear_line)
+          output.print(prompt + line.to_s)
+          if char == "\n"
+            line.move_to_start
+          elsif !line.end?
+            output.print("\e[#{line.size - line.cursor}D")
+          end
+        end
+
+        break if (code == CARRIAGE_RETURN || code == NEWLINE)
+
+        if (console.keys[:backspace] == char || BACKSPACE == code) && opts[:echo]
+          if opts[:raw]
+            output.print("\e[1X") unless line.start?
+          else
+            output.print(?\s + (line.start? ? '' :  ?\b))
+          end
+        end
+      end
+      add_to_history(line.to_s.rstrip) if track_history?
+      line.to_s
+    end
+
+    # Read multiple lines and return them in an array.
+    # Skip empty lines in the returned lines array.
+    # The input gathering is terminated by Ctrl+d or Ctrl+z.
+    #
+    # @param [String] prompt
+    #   the prompt displayed before the input
+    #
+    # @yield [String] line
+    #
+    # @return [Array[String]]
+    #
+    # @api public
+    def read_multiline(prompt = '')
+      @stop = false
+      lines = []
+      loop do
+        line = read_line(prompt)
+        break if !line || line == ''
+        next  if line !~ /\S/ && !@stop
+        if block_given?
+          yield(line) unless line.to_s.empty?
+        else
+          lines << line unless line.to_s.empty?
+        end
+        break if @stop
+      end
+      lines
+    end
+    alias read_lines read_multiline
+
+    # Expose event broadcasting
+    #
+    # @api public
+    def trigger(event, *args)
+      publish(event, *args)
+    end
+
+    # Capture Ctrl+d and Ctrl+z key events
+    #
+    # @api private
+    def keyctrl_d(*)
+      @stop = true
+    end
+    alias keyctrl_z keyctrl_d
+
+    def add_to_history(line)
+      @history.push(line)
+    end
+
+    def history_next?
+      @history.next?
+    end
+
+    def history_next
+      @history.next
+      @history.get
+    end
+
+    def history_previous?
+      @history.previous?
+    end
+
+    def history_previous
+      line = @history.get
+      @history.previous
+      line
+    end
+
+    # Inspect class name and public attributes
+    # @return [String]
+    #
+    # @api public
+    def inspect
+      "#<#{self.class}: @input=#{input}, @output=#{output}>"
+    end
+
+    private
+
+    # Publish event
+    #
+    # @param [String] char
+    #   the key pressed
+    #
+    # @return [nil]
+    #
+    # @api private
+    def trigger_key_event(char)
+      event = KeyEvent.from(console.keys, char)
+      trigger(:"key#{event.key.name}", event) if event.trigger?
+      trigger(:keypress, event)
+    end
+
+    # Handle input interrupt based on provided value
+    #
+    # @api private
+    def handle_interrupt
+      case @interrupt
+      when :signal
+        Process.kill('SIGINT', Process.pid)
+      when :exit
+        exit(130)
+      when Proc
+        @interrupt.call
+      when :noop
+        return
+      else
+        raise InputInterrupt
+      end
+    end
+
+    # Check if Windowz mode
+    #
+    # @return [Boolean]
+    #
+    # @api public
+    def windows?
+      ::File::ALT_SEPARATOR == '\\'
+    end
+  end # Reader
+end # TTY