mini_term 0.1.0

data/exe/mapped_key_test

@@ -0,0 +1,176 @@
+#!/usr/bin/env ruby
+#
+# Test mapped sequences coming from the keyboard.
+#
+
+require_relative '../lib/mini_term'
+
+MiniTerm.open
+no_map = false
+$mini_term_exit_info = {}
+
+# Process any arguments.
+ARGV.each do |arg|
+  if arg == '--no-map'
+    no_map = true
+  else
+    path = File.absolute_path(arg)
+    puts "Requiring '#{path}'"
+    require path
+  end
+end
+
+puts
+
+# Load the sample Windows mapping.
+unless MiniTerm.map_types.include?(:windows)
+  MiniTerm.add_map(:windows) do |map|
+
+    unless no_map
+
+      # Make local copies of the prefixes for brevity.
+      x00 = MiniTerm::PREFIX_00
+      xe0 = MiniTerm::PREFIX_E0
+
+      map[" ".."~"] = :insert_text
+
+      #Left Arrows
+      map[x00+"K"] = :go_left
+      map[xe0+"K"] = :go_left
+
+      map[x00+"s"] = :word_left
+      map[xe0+"s"] = :word_left
+
+      #Right Arrows
+      map[x00+"M"] = :go_right
+      map[xe0+"M"] = :go_right
+
+      map[x00+"t"] = :word_right
+      map[xe0+"t"] = :word_right
+
+      #Up Arrows
+      map[x00+"H"] = :previous_history
+      map[xe0+"H"] = :previous_history
+
+      #Down Arrows
+      map[x00+"P"] = :next_history
+      map[xe0+"P"] = :next_history
+
+      #The Home keys
+      map[x00+"G"] = :go_home
+      map[xe0+"G"] = :go_home
+
+      #The End keys
+      map[x00+"O"] = :go_end
+      map[xe0+"O"] = :go_end
+
+      #The Backspace key
+      map["\x08"]  = :delete_left
+
+      #The Delete keys
+      map["\x7F"]  = :delete_right
+      map[x00+"S"] = :delete_right
+      map[xe0+"S"] = :delete_right
+
+      #Auto-completion.
+      map["\t"]    = :auto_complete
+
+      #The Enter key
+      map["\x0D"]  = :enter
+
+      #The Escape key
+      map["\e"]    = :cancel
+    end
+
+    #End of Input
+    map["\x1A"]  = :end_of_input
+
+    $mini_term_exit_info[:windows] = [:end_of_input, "Ctrl+z"]
+  end
+end
+
+# Load the sample ANSI mapping.
+unless MiniTerm.map_types.include?(:ansi)
+  MiniTerm.add_map(:ansi) do |map|
+
+    unless no_map
+      map[" ".."~"] = :insert_text
+
+      #Left Arrows
+      map["\e[D"]  = :go_left
+      map["\eOD"]  = :go_left
+      map["\x02"]  = :go_left
+
+      map["\e[1;5D"] = :word_left
+      map["\eb"]     = :word_left
+
+      #Right Arrows
+      map["\e[C"]  = :go_right
+      map["\eOC"]  = :go_right
+      map["\x06"]  = :go_right
+
+      map["\e[1;5C"] = :word_right
+      map["\ef"]     = :word_right
+
+      #Up Arrows
+      map["\e[A"]  = :previous_history
+      map["\eOA"]  = :previous_history
+      map["\x12"]  = :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
+      map["\x01"]  = :go_home
+
+      #The End keys
+      map["\e[F"]  = :go_end
+      map["\eOF"]  = :go_end
+      map["\x05"]  = :go_end
+
+      #The Backspace key
+      map["\x7F"]  = :delete_left
+      map["\x08"]  = :delete_left
+      map["\x15"]  = :delete_all_left
+
+      #The Delete keys
+      map["\x1F"]  = :delete_right
+      map["\e[3~"] = :delete_right
+      map["\x0B"]  = :delete_all_right
+
+      #Auto-completion.
+      map["\t"]    = :auto_complete
+
+      #The Enter key
+      map["\x0D"]  = :enter
+
+      #The Cancel key
+      map["\f"]    = :cancel
+    end
+
+    #End of Input
+    map["\ez"] = :end_of_input
+
+    $mini_term_exit_info[:ansi] = [:end_of_input, "Alt+z"]
+  end
+end
+
+exit_action, exit_desc = $mini_term_exit_info[MiniTerm::TERM_TYPE]
+puts "Testing Mapped Keyboard input. Press #{exit_desc} to quit."
+
+puts "Current maps = #{MiniTerm.map_types.inspect}"
+puts "Current term type = #{MiniTerm::TERM_TYPE.inspect}"
+puts
+
+loop do
+  mapped = MiniTerm.get_mapped_char
+  puts "action = #{mapped[0].inspect}, text = #{mapped[1].chars.inspect}"
+  break if mapped[0] == exit_action
+end
+
+MiniTerm.close
+puts
+puts

data/exe/mini_term_blizzard

@@ -0,0 +1,54 @@
+#!/usr/bin/env ruby
+#
+# It's snowing!
+#
+
+require_relative '../lib/mini_term'
+
+begin
+  MiniTerm.open
+
+  if ARGV[0]
+    start = ARGV[0].hex
+
+    if ARGV[1]
+      finish = ARGV[1].hex
+      snow_flakes = (start..finish).map {|c| c.chr(Encoding::UTF_8)}
+    else
+      snow_flakes = [start.chr(Encoding::UTF_8)]
+    end
+
+  else
+    snow_flakes = ["*"]
+  end
+
+  gen = Random.new
+
+  y_limit, x_limit = MiniTerm.term_info
+
+  loop do
+    x = gen.rand(x_limit)
+    y = gen.rand(y_limit)
+
+    if (x < (x_limit-1)) || (y < (y_limit-1))
+      MiniTerm.set_posn(row: y, column: x)
+      snow_flakes.shuffle!
+      MiniTerm.print(snow_flakes[0])
+    end
+
+    x = gen.rand(x_limit)
+    y = gen.rand(y_limit)
+
+    if (x < (x_limit-1)) || (y < (y_limit-1))
+      MiniTerm.set_posn(row: y, column: x)
+      MiniTerm.print(" ")
+    end
+
+    break if MiniTerm.raw(&:has_raw_char?)
+  end
+
+ensure
+  MiniTerm.getch
+  MiniTerm.clear_screen
+  MiniTerm.close
+end

data/exe/mini_term_code_points

@@ -0,0 +1,42 @@
+#!/usr/bin/env ruby
+#
+# Sample the first 65536 code points.
+#
+
+# Compute the range of code points to be displayed.
+last_code, first_code = ARGV.map(&:hex).reverse
+first_code ||= 32
+last_code  ||= 65536
+last_code = 65536 if last_code > 65536
+
+puts "Code points in the range: #{"%X"%first_code}...#{"%X"%last_code}"
+
+# Compute the 64 element lines to be displayed.
+first_line = first_code/64
+last_line = (last_code+63)/64
+
+# Display the code points.
+(first_line...last_line).each do |line|
+  print "%4X " % (line*64)
+
+  8.times do |bundle|
+    print ' '
+    start = line*64 + bundle*8
+    finish = start+8
+
+    (start...finish).each do |code|
+      if code.between?(first_code, last_code) && code >= 32
+        begin
+          print code.chr(Encoding::UTF_8)
+        rescue RangeError
+          print 'E'
+        end
+      else
+        print ' '
+      end
+
+    end
+  end
+
+  puts
+end

data/exe/raw_key_test

@@ -0,0 +1,21 @@
+#!/usr/bin/env ruby
+#
+# Test raw byte sequences coming from the keyboard.
+#
+
+require_relative '../lib/mini_term'
+
+puts "Testing Raw Keyboard input. Press Q to quit."
+MiniTerm.open(pass_ctrl_s: true, pass_ctrl_c: true)
+key = nil
+
+MiniTerm.raw do |i|
+  until key == "Q"
+    key = MiniTerm.get_raw_char
+    print "[" + "%02X" % key.bytes[0] + "]"
+  end
+end
+
+MiniTerm.close
+puts
+puts

data/irbt.rb

@@ -0,0 +1,18 @@
+# coding: utf-8
+# An IRB + mini_term test session.
+
+require 'irb'
+
+puts "Starting an IRB console with mini_term loaded."
+
+if ARGV[0] == 'local'
+  require_relative 'lib/mini_term'
+  puts "mini_term loaded locally: #{MiniTerm::VERSION}"
+
+  ARGV.shift
+else
+  require 'mini_term'
+  puts "mini_term loaded from gem: #{MiniTerm::VERSION}"
+end
+
+IRB.start

data/lib/mini_term/ansi/output.rb

@@ -0,0 +1,25 @@
+# coding: utf-8
+
+# MiniTerm needs to put text on the screen! (ANSI Specific Code)
+module MiniTerm
+
+  # Put some text onto the screen.
+  def self.print(text)
+    STDOUT.print(text)
+    self
+  end
+
+  # Sound a beep
+  def self.beep
+    STDERR.write(BELL)
+    STDERR.flush
+    self
+  end
+
+  # Clear the screen and home the cursor
+  def self.clear_screen
+    STDOUT.print("\e[f\e[2J")
+    self
+  end
+
+end

data/lib/mini_term/ansi/raw_input.rb

@@ -0,0 +1,31 @@
+# coding: utf-8
+
+# Get input from the user in raw mode. (ANSI Specific Code)
+module MiniTerm
+
+  # Is there a character waiting?
+  def self.has_raw_char?
+    raw { STDIN.ready? }
+  end
+
+  #Get a uncooked character keystroke.
+  def self.get_raw_char
+    fail MiniTermNotRaw, "Not in raw mode." unless raw?
+    STDIN.getch
+  end
+
+private
+
+  # Get user input uncooked, with no echo or buffering.
+  def self.begin_raw_input
+    @raw_input = true
+    STDIN.raw!
+  end
+
+  # Done with raw mode for now.
+  def self.end_raw_input
+    STDIN.cooked!
+    @raw_input = false
+  end
+
+end

data/lib/mini_term/ansi/set_posn.rb

@@ -0,0 +1,17 @@
+# coding: utf-8
+
+# Give MiniTerm control of the cursor position. (ANSI Specific Code)
+module MiniTerm
+
+  # Set the row (optional) and column of the cursor.
+  def self.set_posn(row: nil, column:)
+    if row
+      STDOUT.print("\e[#{row};#{column}f")
+    else
+      STDOUT.print("\e#{column}G")
+    end
+
+    self
+  end
+
+end

data/lib/mini_term/ansi/term_info.rb

@@ -0,0 +1,11 @@
+# coding: utf-8
+
+# Get size info about the console window. (ANSI Specific Code)
+module MiniTerm
+
+  # Get term_info [rows, cols]
+  def self.term_info
+    IO.console.winsize
+  end
+
+end

data/lib/mini_term/ansi.rb

@@ -0,0 +1,16 @@
+# coding: utf-8
+
+require 'io/console'
+require 'io/wait'
+
+require_relative 'ansi/term_info'
+require_relative 'ansi/set_posn'
+require_relative 'ansi/raw_input'
+require_relative 'ansi/output'
+
+module MiniTerm
+
+  # What options are supported in this ANSI mode?
+  VALID_OPTIONS = [:quiet, :strict].freeze
+
+end

data/lib/mini_term/common/char_defs.rb

@@ -0,0 +1,15 @@
+# coding: utf-8
+
+# Common control character definitions. (Common Code)
+module MiniTerm
+
+  BELL = "\x07"
+  LINE_FEED = "\x0A"
+  CARRIAGE_RETURN = "\x0D"
+  ESCAPE = "\x1B"
+
+  # These are mostly used in Windows maps.
+  PREFIX_00 = 0x00.chr
+  PREFIX_E0 = 0xE0.chr
+
+end

data/lib/mini_term/common/mapped_input.rb

@@ -0,0 +1,28 @@
+# coding: utf-8
+
+# Get input from the user in mapped mode. (Common Code)
+module MiniTerm
+
+  # The different keyboard maps available.
+  @maps = Hash.new do |_h, key|
+    fail MiniTermNoMap, "No mapping for term type #{key.inspect}."
+  end
+
+  # What terminal types are mapped?
+  def self.map_types
+    @maps.keys
+  end
+
+  # Add a terminal mapping.
+  def self.add_map(type, &defn_block)
+    @maps[type] = Mapper.new(&defn_block)
+  end
+
+  # Get a mapped character. Note: The block is for testing only.
+  def self.get_mapped_char(&block)
+    mapper = @maps[MiniTerm::TERM_TYPE]
+    proc = block_given? ? block : Proc.new { get_raw_char }
+    raw { mapper.get_mapped_char(&proc) }
+  end
+
+end

data/lib/mini_term/common/mapper.rb

@@ -0,0 +1,58 @@
+# coding: utf-8
+
+# A input text mapper. (Common Code)
+module MiniTerm
+
+  # Translate raw input to mapped commands.
+  class Mapper
+
+    #Set up the keystroke mapper.
+    def initialize
+      @map = Hash.new {|_h, key| [:unmapped, key]}
+      yield self
+    end
+
+    #Add a map entry
+    def []=(indexes, value)
+      indexes = [indexes] unless indexes.is_a?(Range)
+
+      indexes.each do |index|
+        process_non_terminals(index)
+
+        if @map.has_key?(index)
+          fail MiniTermKME, "Duplicate entry #{index.inspect}"
+        end
+
+        @map[index] = [value, index]
+      end
+    end
+
+    #Handle the preamble characters in the command sequence.
+    def process_non_terminals(index)
+      seq = ""
+
+      index.chop.chars.each do |char|
+        seq << char
+
+        if @map.has_key?(seq) && @map[seq]
+          fail MiniTermKME, "Ambiguous entry #{index.inspect}"
+        end
+
+        @map[seq] = false
+      end
+    end
+
+    #Get a mapped input sequence.
+    def get_mapped_char
+      key_seq, key_cmd = "", nil
+
+      begin
+        key_seq << yield
+        key_cmd = @map[key_seq]
+      end until key_cmd
+
+      key_cmd
+    end
+  end
+
+end

data/lib/mini_term/common/raw_input.rb

@@ -0,0 +1,33 @@
+# coding: utf-8
+
+# Get input from the user in raw mode. (Common Code)
+module MiniTerm
+
+  # Is input raw or cooked?
+  @raw_input = false
+
+  # Is raw mode in effect?
+  def self.raw?
+    @raw_input
+  end
+
+  # Execute the block with input in raw mode.
+  def self.raw
+    begin_raw_input unless (already_raw = raw?)
+    yield(self)
+  ensure
+    end_raw_input unless already_raw
+  end
+
+  # Flush the keyboard buffer.
+  def self.flush
+    raw do |input|
+      while input.has_raw_char?
+        input.get_raw_char
+      end
+    end
+
+    self
+  end
+
+end

data/lib/mini_term/common/term_info.rb

@@ -0,0 +1,54 @@
+# coding: utf-8
+
+# Common Terminal Info. (Common Code)
+module MiniTerm
+
+  @options   = nil
+  @term_open = false
+
+  def self.open(options = {})
+    @term_open = true
+    @options = options
+    validate_options
+  end
+
+  def self.close
+    end_raw_input if raw?
+    @term_open = false
+    @options   = nil
+  end
+
+  # Is the mini_term open just now?
+  def self.term_open?
+    @term_open
+  end
+
+  # Make sure that mini_term is closed on exit.
+  at_exit do
+    if MiniTerm.term_open?
+      puts "Force MiniTerm.close" unless @options[:quiet]
+      MiniTerm.close
+    end
+  end
+
+  # What is the terminal width in characters?
+  def self.width
+    term_info[1]
+  end
+
+  # What is the terminal height in rows?
+  def self.height
+    term_info[0]
+  end
+
+private
+
+  def self.validate_options
+    return if (bad = @options.keys - VALID_OPTIONS).empty?
+
+    msg = "MiniTerm.open, Invalid options: #{bad.join(", ")}"
+    puts msg unless @options[:quiet]
+    fail MiniTermStrict, msg if @options[:strict]
+  end
+
+end

data/lib/mini_term/exceptions.rb

@@ -0,0 +1,19 @@
+# coding: utf-8
+
+# The abstract base exception for mini term.
+class MiniTermError < StandardError; end
+
+# The exception raised when something is really messed up.
+class MiniTermWTF < MiniTermError; end
+
+# The exception raised due to strictness.
+class MiniTermStrict < MiniTermError; end
+
+# The exception raised when no keyboard mapping is found.
+class MiniTermNoMap < MiniTermError; end
+
+# The exception raised when the keyboard mapping is invalid.
+class MiniTermKME < MiniTermError; end
+
+# The exception raised when raw mode is mandatory.
+class MiniTermNotRaw < MiniTermError; end

data/lib/mini_term/version.rb

@@ -0,0 +1,8 @@
+# coding: utf-8
+
+# A simple, portable terminal interface object.
+module MiniTerm
+  VERSION = "0.1.0".freeze
+
+  DESCRIPTION = "mini_term: A portable encapsulation of the console terminal.".freeze
+end