keyboard_map 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad97855210bbcfc5569c0e179eccd55e03429b114b148c5222dede98f06d9a44
-  data.tar.gz: d604867d99759803d8c1dedda23ac64f328f51a538015655e661db286f6cb5b7
+  metadata.gz: d26c9809ebcc1a3c96e7880a2ba11dcd661376271914d1835331b6b065a8c040
+  data.tar.gz: 45e5461eefa006f0e1babd9f3077943c545cfd82610225f9ff697426aeb4121c
 SHA512:
-  metadata.gz: 8bcdbdd51c0696d7622c8e6bb2ffb189db619c4e72d45b5019773908949750413322d6c695a89b7352e0dff715942d7d8b8816d841b7c59489f40f0fb3662858
-  data.tar.gz: 822319cc6e5c2596d4ec04d86af0d14de91dc32a9a2142dccf8928454fb276c395bd918eb1ed026a0f362d908587468d16b9cb3bfeebd8645279d57716672012
+  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.3"
+  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)
@@ -89,6 +93,10 @@ 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),
@@ -103,7 +111,12 @@ class KeyboardMap
   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"
@@ -114,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)
@@ -189,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.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Vidar Hokstad
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-10-02 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