keyboard_map 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 73f42043d059844447e80fadb95e205f0322d878d6916adb150bb884422b9ea6
-  data.tar.gz: 116ca240612ee19ceb90b8541364cae3fba201998c9cff9a74688959b8c2037d
+  metadata.gz: d26c9809ebcc1a3c96e7880a2ba11dcd661376271914d1835331b6b065a8c040
+  data.tar.gz: 45e5461eefa006f0e1babd9f3077943c545cfd82610225f9ff697426aeb4121c
 SHA512:
-  metadata.gz: a95f1a9d85e9ee5313f2251801c64bf026f21b7fd5c2f18ba4f4627481c311b0f63bbfdbfe51db6b66b770ca154dcdc2dc6eff872dfb7e0ffc24f3b0adde1777
-  data.tar.gz: be940b88650dd017a2bdb66b86e7c6f6e6b326830572c60249e4c00f0d3f393d7e5b3aa6e570df997ee077c37e7e138de9d2e3a30306497c6b65ecf4ed054632
+  metadata.gz: e3fcde7cb8fef76c77de741c35d2d0eb6dc70ac95ce27fe6a782506c67358e5a0fb16a0798a29778e4d898b8c985a732a0cb6ca1657fe7ffa07bd21b3de1b17b
+  data.tar.gz: 29708ba703f28777f05c86482e80af5265b947ac0499bd258896e4077e8af086328d9ec758b7507601f74f0780c1b2409dad005ac653d168b6e0e7cc8d6e8bfc

data/README.md

@@ -2,16 +2,37 @@
 
 Process key-presses and map escape-sequences to symbols.
 
-Dealing with raw keyboard input is painful because something like cursor-up
-can return several different sequences depending on terminal, *and* because
-there is no terribly simple algorithm determining what represents the
-end of a single sequence. In fact some software relies on key-presses being
-slow enough to set a timeout and read character by character.
+E.g instead of getting ASCII 0x03 you'll get `:ctrl_c`
+
+Dealing with raw keyboard input is painful because something like
+cursor-up can return several different sequences depending on terminal,
+*and* because there is no terribly simple algorithm determining what
+represents the end of a single sequence. In fact some software relies on
+key-presses being slow enough to set a timeout and read character by
+character.
 
 KeyboardMap allows you to handle the reads in whichever way you prefer.
 It simply provides a simple state machine that will return an array of
 the keyboard events found so far.
 
+### Current state
+
+This is currently usable and I rely on it daily in my personal editor,
+which uses this gem for keyboard processing.
+
+However there are many missing sequences (PR's welcome), and it's likely
+that it will misreport sequences for certain terminals (PR's also
+welcome), so use with some caution.
+
+Eventually it's likely it will need to deal with termcaps etc., but at
+the moment I'm "cheating" and relying on the fact that most modern
+terminals support a mostly shared subset of VT100.
+
+You can use the example in examples/example.rb to get an idea of what
+your terminal returns for a given keyboard sequence. If you run into
+problems, please include the output from that when filing an issue,
+combined with your *expected* result.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -30,18 +51,56 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+See a full example in `examples/example.rb`, but the basics:
+
+```ruby
+require 'bundler'
+require 'io/console'
+require 'keyboard_map'
+
+kb = KeyboardMap.new
+
+IO.console.raw do # You want to get individual keypresses.
+  loop do
+    ch = $stdin.getc
+
+    # events can include zero or more events.
+    # Zero events will happen if the character
+    # is part of a compound sequence
+
+    events = kb.call(ch)
+    events.each do |e|
+      # Process events here.
+      p e
+    end
+  end
+end
+```
+
+### But I want to catch "Esc"
+
+If you're sure you've read a complete sequence, you can do this
+by passing :finished as a second argument to call, or by calling the
+`#finish` method. You can see this done in `examples/example.rb`
 
 ## 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.
+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).
+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/vidarh/keyboard_map.
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/vidarh/keyboard_map.
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT
+License](https://opensource.org/licenses/MIT).

data/example/example.rb

@@ -0,0 +1,51 @@
+
+$: << File.dirname(__FILE__)+"/lib"
+require 'io/console'
+require_relative '../lib/keyboard_map'
+
+kb = KeyboardMap.new
+
+puts "'q' to quit"
+
+at_exit do
+    STDOUT.print "\e[?2004l" #Disable bracketed paste
+    STDOUT.print "\e[?1000l" #Disable mouse reporting
+end
+
+STDOUT.print "\e[?2004h" # Enable bracketed paste
+STDOUT.print "\e[?1000h" # Enable mouse reporting
+STDOUT.print "\e[?1006h" # Enable extended reporting
+
+IO.console.raw do
+  loop do
+    # We use a non-blocking read of multiple characters
+    # in the hope of the read returning a complete sequence,
+    # which allows us to assume a singular ESC is a single press of
+    # the Esc key.
+    #
+    # If you don't need/care about Esc, you can replace the below
+    # with ch = $stdin.getc and omit the `:finished` argument passed to
+    # `call` below.
+    #
+    begin
+      ch = $stdin.read_nonblock(32)
+    rescue IO::WaitReadable
+      IO.select([$stdin])
+      retry
+    end
+    print "\rRaw:    #{ch.inspect}\n\r"
+    r = kb.call(ch, :finished)
+    r.each do |ev|
+      case ev
+      when KeyboardMap::Event
+        puts "Event:  #{ev.inspect}"
+        print "\r"
+        puts "Symbol: #{ev.to_sym}"
+      else
+        print "Text:   #{ev}\n\r"
+      end
+    end
+    print "\r"
+    break if r.first == "q"
+  end
+end

data/keyboard_map.gemspec

@@ -23,7 +23,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler", "~> 1.16"
+  spec.add_development_dependency "bundler", "~> 2"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"
 end

data/lib/keyboard_map/version.rb

@@ -1,3 +1,3 @@
 class KeyboardMap
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/keyboard_map.rb

@@ -5,7 +5,7 @@ require "keyboard_map/version"
 require 'set'
 
 class KeyboardMap
-  attr_reader :buf
+  attr_reader :buf, :state
 
   class Event
     attr_reader :modifiers,:key, :args
@@ -16,8 +16,12 @@ class KeyboardMap
       @args = args
     end
 
+    def to_s
+      (modifiers.to_a.sort << key).join("_")
+    end
+
     def to_sym
-      (modifiers.to_a.sort << key).join("_").to_sym
+      to_s.to_sym
     end
 
     def ==(ev)
@@ -49,16 +53,19 @@ class KeyboardMap
     "E"    => :keypad_5,
     "F"    => :end,
     "H"    => :home,
-    "P"    => :f1,
+    "J"    => :ctrl_end,    # st reports this
+    "L"    => :ctrl_insert, # st reports this
+    "P"    => :delete,
     "Q"    => :f2,
     "R"    => :f3,
-    "S"    => :f4,
+    "S"    => :f4
   }.freeze
 
   # \e[{parameter1}{;...}~ from parameter1 => key
   CSI_TILDE_MAP = {
     "2"   => :insert,
     "3"   => :delete,
+    "4"   => :end,        # st reports this
     "5"   => :page_up,
     "6"   => :page_down,
     "11"  => :f1,
@@ -86,19 +93,30 @@ class KeyboardMap
     @@key_events[k]
   end
 
+  def event(key, *modifiers)
+    self.class.event(key,*modifiers)
+  end
+
   # Map of simple/non-parameterised escape sequences to symbols
   ESCAPE_MAP = {
     "\e[Z"    => event(:tab,:shift),
     "\eOP"    => :f1,
     "\eOQ"    => :f2,
     "\eOR"    => :f3,
-    "\eOS"    => :f4
+    "\eOS"    => :f4,
+    "\e[M"    => event(:delete,:ctrl), # st reports this
+    "\e[4h"   => :insert       # st reports this
   }.freeze
 
   CSI_FINAL_BYTE = 0x40..0x7e
 
   def meta(key)
-    self.class.event(key,:meta)
+    mod = [:meta]
+    if key.ord < 32
+      mod << :ctrl
+      key = (key.ord+96).chr
+    end
+    self.class.event(key,*mod)
   end
 
   ESC = "\e"
@@ -109,9 +127,13 @@ class KeyboardMap
     @state = :text
   end
 
-  def call(input)
+  def finish
+    run || (@state == :esc ? :esc : nil)
+  end
+      
+  def call(input, opt = nil)
     @buf << input
-    run
+    opt == :finished ? finish : run
   end
 
   def map_escape(seq)
@@ -184,7 +206,7 @@ class KeyboardMap
     elsif ch == "\t"
       @state = :text
       @tmp = ""
-      return meta(:tab)
+      return event(:tab, :meta)
     elsif ch == "\e"
       return :esc
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: keyboard_map
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Vidar Hokstad
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-11-11 00:00:00.000000000 Z
+date: 2022-10-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,14 +16,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.16'
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -68,6 +68,7 @@ files:
 - Rakefile
 - bin/console
 - bin/setup
+- example/example.rb
 - keyboard_map.gemspec
 - lib/keyboard_map.rb
 - lib/keyboard_map/version.rb