mini_readline 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 7f2544e80871d4cdeb122d167832d6e09c74fbb3
+  data.tar.gz: e072a14bf924b8f046355c499655230b220f9a3f
+SHA512:
+  metadata.gz: c8d40fe8058e368fa90d7aeb1216706fbac6de549f888fe0e91acfd59801a6d6de831c66f895f7ec6894af2fd9559174dcf457f2a0c06c8b565047c0df148aa6
+  data.tar.gz: 1b28d4f253743d843f3697c1116008d76dc9c9c9ba7081a36ccf893012399ce83fae0cea41b0ae8c93996a93afb75559da6d2b0ba330c5a30a39f3d295ce56d1

data/.gitignore

@@ -0,0 +1,15 @@
+*.bat
+*.zip
+*.tmp
+*.gem
+*.rbc
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+docs/.~lock.*
+/rdoc/
+/pkg/
+/tmp/
+temp.txt

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in mini_readline.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Peter Camilleri
+
+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,207 @@
+# MiniReadline
+
+This gem is used to get console style input from the user, with support for
+inline editing and command history.
+
+The mini readline gem is an experiment in replacing the standard readline gem
+that is part of Ruby. The reasons for doing this are somewhat shaky, but here
+is a list of what is hoped to be accomplished here.
+
+* The standard readline gem works poorly under Windows.
+<br>- The keypad arrow keys do not work.
+<br>- If the program attempts to send data to a subprocess, it breaks.
+* The code is so convoluted that it is difficult to fix or re-factor.
+* The code is just plain UGLY! With all we've learned about object oriented
+design, there just HAD to be a better way!
+* Finally, since this code will borrow a lot from the original, it is hoped
+that I will see the same bugs and fix them. Then perhaps it can be seen how
+the original code can also be fixed. In the long run, this is perhaps the
+most important goal.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'mini_readline'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install mini_readline
+
+## Usage
+
+The typical way of utilizing this gem is to place the following:
+
+```ruby
+require 'mini_readline'
+```
+
+<br>By default, the constant Readline is set to the MiniReadline module. If this
+is not desired use the following:
+
+```ruby
+$no_alias_read_line_module = true
+require 'mini_readline'
+```
+
+### Compatible Mode
+
+In this mode, mini_readline is somewhat compatible with the classic readline.
+Simply use:
+
+```ruby
+Readline.readline('>', true)
+```
+or to avoid tracking command history, use:
+
+```ruby
+Readline.readline('>', false)
+```
+Where the string argument is the prompt seen by the user and the flag controls
+the history buffer. This assumes that the $no_alias_read_line_module setting
+mentioned above was *not* used. If it was, then these somewhat less compatible
+forms are required:
+```ruby
+MiniReadline.readline('>', true)
+```
+and
+```ruby
+MiniReadline.readline('>', false)
+```
+
+
+### Native Mode
+
+In native mode, instances of the Readline class are used to get user input.
+
+```ruby
+edit = MiniReadline::Readline.new()
+```
+
+The constructor takes a single optional argument which is either:
+* An array of strings; A history buffer pre-loaded with commands.
+* An empty array; A history buffer with no pre-load.
+* The value **false**, to disable the history buffer.
+
+<br>Once an instance is created it may be used as follows:
+
+```ruby
+edit.readline(prompt, options)
+```
+Where prompt is a prompt string and options is a hash of options settings.
+More on options below. In addition, it is possible to get a hold of the
+history buffer of the edit object with:
+```ruby
+hist = edit.history
+```
+This method answers an array of strings. Entries added to this array are
+available to the edit instance. For example, the following makes a rather
+menacing part of the history buffer.
+```ruby
+hist << "launch --weapons:nuclear --all"
+```
+
+### Options
+In mini_readline, options exist at two levels:
+* The MiniReadline module hash BASE_OPTIONS. These options are shared by
+all instances of the Readline class.
+* The options hash argument of the Readline class's readline instance method.
+
+<br>The available options are described below:
+```ruby
+BASE_OPTIONS = {
+  :window_width  => 79,       #The width of the edit area.
+  :scroll_step   => 12,       #The amount scrolled.
+  :alt_prompt    => "<< ",    #The prompt when scrolled.
+                              #Set to nil for no alt prompt.
+
+  :no_blanks     => true,     #No empty lines in history.
+  :no_dups       => true,     #No duplicate lines in history.
+
+  :term          => nil,      #Filled in by raw_term.rb
+
+  :debug         => false}    #Used during development.
+```
+
+<br>The options in effect on any given call of the readline method are the
+module base options plus any options passed in as an argument. The passed in
+options override the base options for the duration of that method call.
+
+#### Notes
+* Since the compatibility mode does not accept an options hash, the only way to
+affect options in this case is to modify the MiniReadline::BASE_OPTIONS hash.
+* The :term option is the low level console io object used to get data
+from the user and control what is displayed. This gem automatically adapts to
+the environment and plugs in the needed object. This can be overridden where
+special io needs exist.
+
+## Demo
+A simple demo of mini_readline in action is available. To access this demo use
+the following from the mini_readline root folder:
+
+    $ ruby sire.rb
+
+This will launch SIRE, a Simple Interactive Ruby Environment, a sort of
+simple minded irb knock-off. This starts off by requiring the mini
+readline gem from either the system gem library or the local lib folder or
+if all fails, it will load the "classic" Readline gem. Here is a typical run:
+
+    C:\Sites\mini_readline>ruby sire.rb
+
+
+    Loaded mini_readline from the local code folder.
+
+    Welcome to a Simple Interactive Ruby Environment
+    Use the command 'q' to quit.
+
+    SIRE>
+Of note, the run method can be used to test for the shell process bug. For
+example:
+
+    SIRE>(run 'ls').split("\n")
+    ["Gemfile",
+     "LICENSE.txt",
+     "README.md",
+     "Rakefile",
+     "bin",
+     "lib",
+     "mini_readline.gemspec",
+     "rdoc",
+     "reek.txt",
+     "sire.rb",
+     "tests"]
+    SIRE>
+After this command is run, the program should continue to operate correctly
+and not go bannanas. To test the behavior of the standard readline library, use:
+
+    $ ruby sire.rb old
+
+To test the local copy of mini_readline in the lib folder instead of the
+system gem, use this instead:
+
+    $ ruby sire.rb local
+
+## Testing
+To date this code has been tested under:
+* Windows 7 with MRI ruby 2.1.6p336 (2015-04-13 revision 50298) [i386-mingw32]
+* Windows 7 + Cygwin with ruby 2.2.3p173 (2015-08-18 revision 51636) [i386-cygwin]
+
+<br>More testing is clearly called for.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/PeterCamilleri/mini_readline.
+
+
+## License
+
+The gem is available as open source under the terms of the
+[MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,40 @@
+#!/usr/bin/env rake
+# coding: utf-8
+
+require 'rake/testtask'
+require 'rdoc/task'
+require "bundler/gem_tasks"
+
+#Generate internal documentation with rdoc.
+RDoc::Task.new do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+
+  #List out all the files to be documented.
+  rdoc.rdoc_files.include("lib/**/*.rb", "license.txt", "README.md")
+
+  #Make all access levels visible.
+  rdoc.options << '--visibility' << 'private'
+  #rdoc.options << '--verbose'
+  #rdoc.options << '--coverage-report'
+
+  #Set a title.
+  rdoc.options << '--title' << 'Mini Readline Gem'
+end
+
+#Run the mini_readline unit test suite.
+Rake::TestTask.new do |t|
+  #List out all the test files.
+  t.test_files = FileList['tests/**/*.rb']
+  t.verbose = false
+end
+
+desc "Run a scan for smelly code!"
+task :reek do |t|
+  `reek --no-color lib > reek.txt`
+end
+
+desc "What version of mine_readline is this?"
+task :vers do |t|
+  puts
+  puts "mini_readline version = #{MiniReadline::VERSION}"
+end

data/lib/mini_readline.rb

@@ -0,0 +1,28 @@
+# coding: utf-8
+
+require_relative "mini_readline/version"
+require_relative "mini_readline/options"
+require_relative "mini_readline/read_line"
+require_relative "mini_readline/raw_term"
+
+#The \MiniReadline module. A replacement for the rb_readline gem predicated
+#on the notion/hope that the code shouldn't smell like an abandoned fish
+#processing plant. To this end, it drops the pretext of being compatible
+#with the GNU readline library and instead embraces OOD principles. I hope.
+#* mini_readline.rb - The root file that gathers up all the system's parts.
+module MiniReadline
+
+  #The instances of Readline with and without history.
+  @readers = {true => Readline.new([]), false => Readline.new(nil)}
+
+  #The (limited) compatibility module function.
+  #<br>Endemic Code Smells
+  #* :reek:BooleanParameter -- Required for compatibility
+  def self.readline(prompt, history = false)
+    @readers[history].readline(prompt)
+  end
+end
+
+unless $no_alias_read_line_module
+  Readline = MiniReadline
+end

data/lib/mini_readline/options.rb

@@ -0,0 +1,19 @@
+# coding: utf-8
+
+#* options.rb - Options selection, control, and access
+module MiniReadline
+
+  #The base options shared by all instances.
+  BASE_OPTIONS = {:window_width  => 79,       #The width of the edit area.
+                  :scroll_step   => 12,       #The amount scrolled.
+                  :alt_prompt    => "<< ",    #The prompt when scrolled.
+                                              #Set to nil for no alt prompt.
+
+                  :no_blanks     => true,     #No empty lines in history.
+                  :no_dups       => true,     #No duplicate lines in history.
+
+                  :term          => nil,      #Filled in by raw_term.rb
+
+                  :debug         => false     #Used during development.
+                 }
+end

data/lib/mini_readline/raw_term.rb

@@ -0,0 +1,14 @@
+# coding: utf-8
+
+#Select the type of platform in use.
+if (RUBY_PLATFORM =~ /\bcygwin\b/i) || (RUBY_PLATFORM !~ /mswin|mingw/)
+  require_relative 'raw_term/other'
+else
+  require_relative 'raw_term/windows'
+end
+
+#* raw_term.rb - Platform determination for raw terminal access.
+module MiniReadline
+  #Get an instance of a raw terminal controller object.
+  BASE_OPTIONS[:term] = RawTerm.new
+end

data/lib/mini_readline/raw_term/other.rb

@@ -0,0 +1,67 @@
+# coding: utf-8
+
+require          'io/console'
+require_relative 'other/map'
+require_relative 'other/set_posn'
+
+#* raw_term/other.rb - Support for raw terminal access in non-windows systems.
+module MiniReadline
+
+  #The detected platform is not windows.
+  PLATFORM = :other
+
+  #The class used to manipulate console i/o on a low level.
+  class RawTerm
+
+    #Carriage return
+    CARRIAGE_RETURN = "\x0D"
+
+    #Bell
+    BELL            = "\x07"
+
+    #Set up the Other Raw Terminal.
+    def initialize
+    end
+
+    #Output a string
+    def put_string(str)
+      scan_string(str)
+      print(str)
+    end
+
+    #Home the cursor and start at a known state.
+    def initialize_parms
+      put_string CARRIAGE_RETURN
+    end
+
+    #Start on a new line.
+    def put_new_line
+      print("\n")
+    end
+
+    #Sound a beep
+    def beep
+      print BELL
+    end
+
+    #Get a uncooked character keystroke.
+    #<br>Notes
+    #* This needs to be tested under Linux, Cygwin, and Apple.
+    #<br>Endemic Code Smells
+    #* :reek:UtilityFunction -- For now, the way things are.
+    def get_raw_char
+      STDIN.getch
+    end
+
+    #Determine the affect of a string on the cursor.
+    def scan_string(str)
+      str.chars.each do |char|
+        if char == CARRIAGE_RETURN
+          @cursor_posn = 0
+        else
+          @cursor_posn += 1
+        end
+      end
+    end
+  end
+end

data/lib/mini_readline/raw_term/other/map.rb

@@ -0,0 +1,75 @@
+# coding: utf-8
+
+#* other/map.rb - Character mapping for other systems.
+module MiniReadline
+
+  #* other/map.rb - Character mapping for other systems.
+  class RawTerm
+
+    #Create a hash with a default value.
+    MAP = Hash.new {|_hash, key| [:unmapped, key]}
+
+    #Map the printable characters.
+    (32..126).each do |code|
+      char = code.chr
+      MAP[char] = [:insert_text, char]
+    end
+
+    #Map the non-terminal entries.
+    MAP["\e"]   = false
+    MAP["\e["]  = false
+    MAP["\eO"]  = false
+
+    #Map the non-printing characters.
+
+    #Left Arrows
+    MAP["\e[D"]  = [:go_left]
+    MAP["\e[D"]  = [:go_left]
+
+    #Right Arrows
+    MAP["\e[C"]  = [:go_right]
+    MAP["\eOC"]  = [:go_right]
+
+    #Up Arrows
+    MAP["\e[A"]  = [:previous_history]
+    MAP["\eOA"]  = [:previous_history]
+
+    #Down Arrows
+    MAP["\e[B"]  = [:next_history]
+    MAP["\eOB"]  = [:next_history]
+
+    #The Home keys
+    MAP["\e[H"]  = [:go_home]
+    MAP["\eOH"]  = [:go_home]
+
+    #The End keys
+    MAP["\e[F"]  = [:go_end]
+    MAP["\eOF"]  = [:go_end]
+
+    #The Backspace key
+    MAP["\x7F"]  = [:delete_left]
+
+    #The Delete keys
+    MAP["\x1F"]  = [:delete_right]
+    MAP["\e[3"]  = false
+    MAP["\e[3~"] = [:delete_right]
+
+    #The Enter key
+    MAP["\x0D"]  = [:enter]
+
+    #The Cancel key
+    MAP["\x02"]  = [:cancel]
+
+    #Get a mapped sequence.
+    def get_mapped_keystroke
+      key_seq, key_cmd = "", nil
+
+      begin
+        key_seq << get_raw_char
+        key_cmd = MAP[key_seq]
+      end until key_cmd
+
+      key_cmd
+    end
+  end
+end