accessibility_keyboard 1.0.0

data/.yardopts

@@ -0,0 +1,14 @@
+--no-cache
+--no-output
+--verbose
+--markup markdown
+--markup-provider redcarpet
+--asset docs/images:images
+--readme README.markdown
+--hide-void-return
+lib/**/*.rb
+ext/**/*{.m,.c}
+-
+History.markdown
+CONTRIBUTING.markdown
+

data/CONTRIBUTING.markdown

@@ -0,0 +1,44 @@
+# Contributing to accessibility\_keyboard
+
+First, let me thank you for wanting to contribute! :)
+
+There are no contributions that are too small. Even if you are only fixing
+typos, adding documentation, or some example code. The goal is to make the 
+process simple and as painless as possible to encourage contributions.
+
+
+## Reporting Bugs
+
+If you think you've found a bug, feel free to log the issue. It is OK to
+make a duplicate bug report; such reports will be closed as duplicates
+with a pointer to the original issue.
+
+You may also wish to see if the bug you've reported has already been
+fixed or obsoleted on the master branch.
+
+
+## Code
+
+Try to stick within the existing style. The importance of sticking with
+existing style grows linearly with the size of the contribution.
+
+It is preferred that code contributions, whether they are new features or
+bug fixes, be accompanied by test(s) where appropriate.
+
+The best way to submit code is through a
+[pull request](https://help.github.com/articles/using-pull-requests) on the
+[Github page](https://github.com/AXElements/accessibility_keyboard),
+though email is also acceptable if privacy is a concern. Unless otherwise
+requested, commit history will always be made to reflect who made the
+contribution.
+
+
+## Documentation and Examples
+
+As with code, try to fit with the existing style. New examples are always
+welcome and the wiki could always use a new article. :)
+
+The documentation in the wiki is open and no permission is required to make
+edits or contributions. For API documentation or example code, it is best to
+submit a pull request (or create a new wiki page if appropriate).
+

data/History.markdown

@@ -0,0 +1,4 @@
+# 1.0.0
+
+  * Initial release
+

data/README.markdown

@@ -0,0 +1,98 @@
+# keyboard
+
+This  gem is a component of
+[AXElements](http://github.com/Marketcircle/AXElements). It provides
+an interface for posting keyboard events to the system as well as a
+mixin for parsing a string into a series of events.
+
+
+A port of keyboard simulator code from
+[AXElements](http://github.com/AXElements/AXElements),
+but cleaned up and released as its own gem.
+
+By itself, the `accessibility_keyboard` gem has limited use; but in
+combination with a gem for performing other GUI manipulations, like
+AXElements, this gem is very powerful and can be used for tasks such
+as automated functional testing.
+
+[![Dependency Status](https://gemnasium.com/AXElements/accessibility_keyboard.png)](https://gemnasium.com/AXElements/accessibility_keyboard)
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/AXElements/accessibility_keyboard)
+[![Build Status](https://travis-ci.org/AXElements/accessibility_keyboard.png?branch=master)](https://travis-ci.org/AXElements/accessibility_keyboard)
+
+
+## Examples
+
+The basics:
+
+```ruby
+    require 'accessibility/keyboard'
+
+    include Accessibility::Keyboard
+
+    keyboard_events_for("Hey, there!").each do |event|
+      KeyCoder.post_event event
+    end
+```
+
+Something a bit more advanced:
+
+```ruby
+    require 'accessibility/keyboard'
+
+    include Accessibility::Keyboard
+
+    keyboard_events_for("\\COMMAND+\t").each do |event|
+      KeyCoder.post_event event
+    end
+```
+
+
+## Documentation
+
+- [Keyboarding Blog Post](http://ferrous26.com/blog/2012/04/03/axelements-part1/).
+- [API documentation](http://rdoc.info/gems/accessibility_keyboard/frames)
+- The AXElements [keyboarding tutorial](https://github.com/AXElements/AXElements/wiki/Keyboarding)
+
+
+## Development
+
+Development of this library happens as part of AXElements, but tests
+and the API for this component remain separate so that it can be
+released as part of the `accessibility_keyboard` gem.
+
+
+### TODO
+
+The API for posting events is ad-hoc for the sake of demonstration;
+AXElements exposes this functionality via `Kernel#type`. The standalone
+API provided here could be improved.
+
+
+## Copyright
+
+Copyright (c) 2013, Mark Rada
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+* Neither the name of Mark Rada nor the names of its
+  contributors may be used to endorse or promote products derived
+  from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL Mark Rada BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
+GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/ext/key_coder/extconf.rb

@@ -0,0 +1,22 @@
+require 'mkmf'
+
+$CFLAGS << ' -std=c99 -Wall -Werror -ObjC'
+$LIBS   << ' -framework Cocoa -framework Carbon -framework ApplicationServices'
+
+if RUBY_ENGINE == 'macruby'
+  $CFLAGS << ' -fobjc-gc'
+else
+  unless RbConfig::CONFIG["CC"].match /clang/
+    clang = `which clang`.chomp
+    if clang.empty?
+      $stdout.puts "Clang not installed. Cannot build C extension"
+      raise "Clang not installed. Cannot build C extension"
+    else
+      RbConfig::MAKEFILE_CONFIG["CC"]  = clang
+      RbConfig::MAKEFILE_CONFIG["CXX"] = clang
+    end
+  end
+  $CFLAGS << ' -DNOT_MACRUBY'
+end
+
+create_makefile('accessibility/key_coder')

data/ext/key_coder/key_coder.c

@@ -0,0 +1,171 @@
+/*
+ *  key_coder.c
+ *  KeyCoder
+ *
+ *  Created by Mark Rada on 11-07-27.
+ *  Copyright 2013 Mark Rada. All rights reserved.
+ *  Copyright 2011-2012 Marketcircle Incorporated. All rights reserved.
+ */
+
+
+#import <Cocoa/Cocoa.h>
+#import <Carbon/Carbon.h>
+#import <ApplicationServices/ApplicationServices.h>
+
+#include "ruby.h"
+
+static VALUE rb_cEventGenerator;
+static ID sel_regenerate;
+
+#ifdef NOT_MACRUBY
+#define RELEASE(x) CFRelease(x)
+#else
+#define RELEASE(x) CFMakeCollectable(x)
+#endif
+
+
+/*
+ *  Generate the mapping of characters to key codes for keys that can be
+ *  remapped based on keyboard layout. Changing the keyboard layout at
+ *  runtime will cause the returned hash to be different.
+ *
+ *  @example
+ *
+ *    KeyCoder.dynamic_mapping  => { "a" => 0, "b" => 24, ... }
+ *
+ *  @return [Hash{String=>Number}]
+ */
+
+static
+VALUE
+keycoder_dynamic_mapping()
+{
+
+  VALUE map = rb_hash_new();
+
+#ifdef NOT_MACRUBY
+  @autoreleasepool {
+#endif
+
+  TISInputSourceRef keyboard = TISCopyCurrentKeyboardLayoutInputSource();
+  CFDataRef layout_data = (CFDataRef)TISGetInputSourceProperty(keyboard, kTISPropertyUnicodeKeyLayoutData);
+  const UCKeyboardLayout* layout = (const UCKeyboardLayout*)CFDataGetBytePtr(layout_data);
+
+  void (^key_coder)(int) = ^(int key_code) {
+    UniChar      string[255];
+    UniCharCount string_length = 0;
+    UInt32       dead_key_state = 0;
+    UCKeyTranslate(
+		   layout,
+       key_code,
+		   kUCKeyActionDown,
+		   0,
+		   LMGetKbdType(),  // kb type
+		   0,               // OptionBits keyTranslateOptions,
+		   &dead_key_state,
+		   255,
+		   &string_length,
+		   string
+		  );
+
+    NSString* nsstring = [NSString stringWithCharacters:string length:string_length];
+    rb_hash_aset(map, rb_str_new_cstr([nsstring UTF8String]), INT2FIX(key_code));
+  };
+
+  // skip 65-92 since they are hard coded and do not change
+  for (int key_code = 0;  key_code < 65;  key_code++)
+    key_coder(key_code);
+  for (int key_code = 93; key_code < 127; key_code++)
+    key_coder(key_code);
+
+  RELEASE(keyboard);
+
+#ifdef NOT_MACRUBY
+  }; // Close the autorelease pool
+#endif
+
+
+  return map;
+}
+
+
+/*
+ *  Post the given event to the system and return `true`. This method
+ *  will also add a small (9000 microsecond) delay after posting to
+ *  ensure that keyboard actions do not go too fast.
+ *
+ *  @example
+ *
+ *    KeyCoder.post_event [0, true]  -> true
+ *
+ *  @param [Array(Number, Boolean)]
+ *  @return [true]
+ */
+
+static
+VALUE
+keycoder_post_event(VALUE self, VALUE event)
+{
+  VALUE code  = rb_ary_entry(event, 0);
+  VALUE state = rb_ary_entry(event, 1);
+
+  CGEventRef event_ref = CGEventCreateKeyboardEvent(NULL, FIX2LONG(code), state);
+  CGEventPost(kCGHIDEventTap, event_ref);
+  RELEASE(event_ref);
+
+  usleep(9000); // 9000 is a magic number
+  return Qtrue;
+}
+
+
+@interface AKEventGenerator : NSObject
+- (void)regenerateDynamicMapping;
+@end
+
+@implementation AKEventGenerator
+
+- (void)regenerateDynamicMapping
+{
+  rb_funcall(rb_cEventGenerator, sel_regenerate, 0);
+}
+
+@end
+
+
+void
+Init_key_coder()
+{
+  /*
+   *  Document-class: KeyCoder
+   *
+   *  Class that encapsulates some low level work for finding key code mappings
+   *  and posting keyboard events to the system.
+   *
+   */
+  VALUE cKeyCoder = rb_define_class("KeyCoder", rb_cObject);
+  rb_define_singleton_method(cKeyCoder, "dynamic_mapping", keycoder_dynamic_mapping, 0);
+  rb_define_singleton_method(cKeyCoder, "post_event", keycoder_post_event, 1);
+
+
+
+  /* Register to be notified if the keyboard layout changes at runtime. The
+   * receiver will tell the event generator to regenerate its mapping.
+   * This will only work if a run loop is running (e.g. using the "spin"
+   * method that comes with accessibility_core).
+   */
+
+  VALUE rb_mAccessibility = rb_define_module("Accessibility");
+  VALUE rb_mKeyboard      = rb_define_module_under(rb_mAccessibility, "Keyboard");
+  rb_cEventGenerator      = rb_define_class_under(rb_mKeyboard, "EventGenerator", rb_cObject);
+
+  sel_regenerate = rb_intern("regenerate_dynamic_mapping");
+
+  static AKEventGenerator* dynamic_regenerator;
+  dynamic_regenerator = [[AKEventGenerator alloc] init];
+
+  [[NSDistributedNotificationCenter defaultCenter]
+     addObserver:dynamic_regenerator
+        selector:sel_registerName("regenerateDynamicMapping")
+            name:(NSString*)kTISNotifySelectedKeyboardInputSourceChanged
+          object:nil];
+}

data/lib/accessibility/keyboard.rb

@@ -0,0 +1,34 @@
+require 'accessibility/keyboard/version'
+require 'accessibility/keyboard/parser'
+require 'accessibility/keyboard/event_generator'
+
+
+##
+# Parses strings of human readable text into a series of events
+#
+# Events are meant to be processed by {KeyCoder.post_event} or
+# [Accessibility::Core#post](https://github.com/AXElements/accessibility_core/blob/master/lib/accessibility/core/macruby.rb#L597).
+#
+# Supports most, if not all, latin keyboard layouts, maybe some
+# international layouts as well. Japanese layouts can be made to work with
+# use of `String#transform` on MacRuby. See README for examples.
+#
+module Accessibility::Keyboard
+
+  ##
+  # Generate keyboard events for the given string
+  #
+  # Strings should be in a human readable format with a few exceptions.
+  # Command key (e.g. control, option, command) should be written in
+  # string as they appear in {Accessibility::Keyboard::EventGenerator::CUSTOM}.
+  #
+  # For more details on event generation, read the
+  # [Keyboarding wiki](http://github.com/AXElements/AXElements/wiki/Keyboarding).
+  #
+  # @param string [#to_s]
+  # @return [Array<Array(Fixnum,Boolean)>]
+  def keyboard_events_for string
+    EventGenerator.new(Parser.new(string).parse).generate
+  end
+
+end

data/lib/accessibility/keyboard/event_generator.rb

@@ -0,0 +1,351 @@
+# encoding: UTF-8
+
+require 'accessibility/keyboard/version'
+require 'accessibility/key_coder'
+
+##
+# Generate a sequence of keyboard events given a sequence of tokens.
+# The token format is defined by the
+# {Accessibility::Keyboard::EventGenerator}
+# class output; it is best to use that class to generate the tokens.
+#
+# @example
+#
+#   # Upper case 'A'
+#   EventGenerator.new(["A"]).generate  # => [[56,true],[70,true],[70,false],[56,false]]
+#
+#   # Press the volume up key
+#   EventGenerator.new([["\\F12"]]).generate # => [[0x6F,true],[0x6F,false]]
+#
+#   # Hotkey, press and hold command key and then 'a', then release both
+#   EventGenerator.new([["\\CMD",["a"]]]).generate # => [[55,true],[70,true],[70,false],[55,false]]
+#
+#   # Press the return/enter key
+#   EventGenerator.new(["\n"]).generate # => [[10,true],[10,false]]
+#
+class Accessibility::Keyboard::EventGenerator
+
+  ##
+  # Regenerate the portion of the key mapping that is set dynamically
+  # based on keyboard layout (e.g. US, Dvorak, etc.).
+  #
+  # This method should be called whenever the keyboard layout changes.
+  # This can be called automatically by registering for a notification
+  # in a run looped environment.
+  def self.regenerate_dynamic_mapping
+    # KeyCoder is declared in the Objective-C extension
+    MAPPING.merge! KeyCoder.dynamic_mapping
+    # Also add an alias to the mapping
+    MAPPING["\n"] = MAPPING["\r"]
+  end
+
+  ##
+  # Dynamic mapping of characters to keycodes. The map is generated at
+  # startup time in order to support multiple keyboard layouts.
+  #
+  # @return [Hash{String=>Fixnum}]
+  MAPPING = {}
+
+  # Initialize the table
+  regenerate_dynamic_mapping
+
+  ##
+  # @note These mappings are all static and come from `/System/Library/Frameworks/Carbon.framework/Versions/A/Frameworks/HIToolbox.framework/Versions/A/Headers/Events.h`
+  #
+  # Map of custom escape sequences to their hardcoded keycode value.
+  #
+  # @return [Hash{String=>Fixnum}]
+  CUSTOM = {
+            "\\FUNCTION"      => 0x3F,      # Standard Control Keys
+            "\\FN"            => 0x3F,
+            "\\CONTROL"       => 0x3B,
+            "\\CTRL"          => 0x3B,
+            "\\OPTION"        => 0x3A,
+            "\\OPT"           => 0x3A,
+            "\\ALT"           => 0x3A,
+            "\\COMMAND"       => 0x37,
+            "\\CMD"           => 0x37,
+            "\\LSHIFT"        => 0x38,
+            "\\SHIFT"         => 0x38,
+            "\\CAPSLOCK"      => 0x39,
+            "\\CAPS"          => 0x39,
+            "\\ROPTION"       => 0x3D,
+            "\\ROPT"          => 0x3D,
+            "\\RALT"          => 0x3D,
+            "\\RCONTROL"      => 0x3E,
+            "\\RCTRL"         => 0x3E,
+            "\\RSHIFT"        => 0x3C,
+            "\\ESCAPE"        => 0x35,      # Top Row Keys
+            "\\ESC"           => 0x35,
+            "\\VOLUMEUP"      => 0x48,
+            "\\VOLUP"         => 0x48,
+            "\\VOLUMEDOWN"    => 0x49,
+            "\\VOLDOWN"       => 0x49,
+            "\\MUTE"          => 0x4A,
+            "\\F1"            => 0x7A,
+            "\\F2"            => 0x78,
+            "\\F3"            => 0x63,
+            "\\F4"            => 0x76,
+            "\\F5"            => 0x60,
+            "\\F6"            => 0x61,
+            "\\F7"            => 0x62,
+            "\\F8"            => 0x64,
+            "\\F9"            => 0x65,
+            "\\F10"           => 0x6D,
+            "\\F11"           => 0x67,
+            "\\F12"           => 0x6F,
+            "\\F13"           => 0x69,
+            "\\F14"           => 0x6B,
+            "\\F15"           => 0x71,
+            "\\F16"           => 0x6A,
+            "\\F17"           => 0x40,
+            "\\F18"           => 0x4F,
+            "\\F19"           => 0x50,
+            "\\F20"           => 0x5A,
+            "\\HELP"          => 0x72,      # Island Keys
+            "\\HOME"          => 0x73,
+            "\\END"           => 0x77,
+            "\\PAGEUP"        => 0x74,
+            "\\PAGEDOWN"      => 0x79,
+            "\\DELETE"        => 0x75,
+            "\\LEFT"          => 0x7B,      # Arrow Keys
+            "\\<-"            => 0x7B,
+            "\\RIGHT"         => 0x7C,
+            "\\->"            => 0x7C,
+            "\\DOWN"          => 0x7D,
+            "\\UP"            => 0x7E,
+            "\\0"             => 0x52,      # Keypad Keys
+            "\\1"             => 0x53,
+            "\\2"             => 0x54,
+            "\\3"             => 0x55,
+            "\\4"             => 0x56,
+            "\\5"             => 0x57,
+            "\\6"             => 0x58,
+            "\\7"             => 0x59,
+            "\\8"             => 0x5B,
+            "\\9"             => 0x5C,
+            "\\DECIMAL"       => 0x41,
+            "\\."             => 0x41,
+            "\\PLUS"          => 0x45,
+            "\\+"             => 0x45,
+            "\\MULTIPLY"      => 0x43,
+            "\\*"             => 0x43,
+            "\\MINUS"         => 0x4E,
+            "\\-"             => 0x4E,
+            "\\DIVIDE"        => 0x4B,
+            "\\/"             => 0x4B,
+            "\\EQUALS"        => 0x51,
+            "\\="             => 0x51,
+            "\\ENTER"         => 0x4C,
+            "\\CLEAR"         => 0x47,
+           }
+
+  ##
+  # Mapping of shifted (characters written when holding shift) characters
+  # to keycodes.
+  #
+  # @return [Hash{String=>Fixnum}]
+  SHIFTED = {
+             '~'               => '`',
+             '!'               => '1',
+             '@'               => '2',
+             '#'               => '3',
+             '$'               => '4',
+             '%'               => '5',
+             '^'               => '6',
+             '&'               => '7',
+             '*'               => '8',
+             '('               => '9',
+             ')'               => '0',
+             '{'               => '[',
+             '}'               => ']',
+             '?'               => '/',
+             '+'               => '=',
+             '|'               => "\\",
+             ':'               => ';',
+             '_'               => '-',
+             '"'               => "'",
+             '<'               => ',',
+             '>'               => '.',
+             'A'               => 'a',
+             'B'               => 'b',
+             'C'               => 'c',
+             'D'               => 'd',
+             'E'               => 'e',
+             'F'               => 'f',
+             'G'               => 'g',
+             'H'               => 'h',
+             'I'               => 'i',
+             'J'               => 'j',
+             'K'               => 'k',
+             'L'               => 'l',
+             'M'               => 'm',
+             'N'               => 'n',
+             'O'               => 'o',
+             'P'               => 'p',
+             'Q'               => 'q',
+             'R'               => 'r',
+             'S'               => 's',
+             'T'               => 't',
+             'U'               => 'u',
+             'V'               => 'v',
+             'W'               => 'w',
+             'X'               => 'x',
+             'Y'               => 'y',
+             'Z'               => 'z',
+            }
+
+  ##
+  # Mapping of optioned (characters written when holding option/alt)
+  # characters to keycodes.
+  #
+  # @return [Hash{String=>Fixnum}]
+  OPTIONED = {
+              '¡'               => '1',
+              '™'               => '2',
+              '£'               => '3',
+              '¢'               => '4',
+              '∞'               => '5',
+              '§'               => '6',
+              '¶'               => '7',
+              '•'               => '8',
+              'ª'               => '9',
+              'º'               => '0',
+              '“'               => '[',
+              '‘'               => ']',
+              'æ'               => "'",
+              '≤'               => ',',
+              '≥'               => '.',
+              'π'               => 'p',
+              '¥'               => 'y',
+              'ƒ'               => 'f',
+              '©'               => 'g',
+              '®'               => 'r',
+              '¬'               => 'l',
+              '÷'               => '/',
+              '≠'               => '=',
+              '«'               => "\\",
+              'å'               => 'a',
+              'ø'               => 'o',
+              '´'               => 'e',
+              '¨'               => 'u',
+              'ˆ'               => 'i',
+              '∂'               => 'd',
+              '˙'               => 'h',
+              '†'               => 't',
+              '˜'               => 'n',
+              'ß'               => 's',
+              '–'               => '-',
+              '…'               => ';',
+              'œ'               => 'q',
+              '∆'               => 'j',
+              '˚'               => 'k',
+              '≈'               => 'x',
+              '∫'               => 'b',
+              'µ'               => 'm',
+              '∑'               => 'w',
+              '√'               => 'v',
+              'Ω'               => 'z',
+             }
+
+
+  ##
+  # Once {#generate} is called, this contains the sequence of
+  # events.
+  #
+  # @return [Array<Array(Fixnum,Boolean)>]
+  attr_reader :events
+
+  # @param tokens [Array<String,Array<String,Array...>>]
+  def initialize tokens
+    @tokens = tokens
+    # *3 since the output array will be at least *2 the
+    # number of tokens passed in, but will often be larger
+    # due to shifted/optioned characters and custom escapes;
+    # though a better number could be derived from
+    # analyzing common input...
+    @events = Array.new tokens.size*3
+  end
+
+  ##
+  # Generate the events for the tokens the event generator
+  # was initialized with. Returns the generated events, though
+  # you can also use {#events} to get the events later.
+  #
+  # @return [Array<Array(Fixnum,Boolean)>]
+  def generate
+    @index = 0
+    gen_all @tokens
+    @events.compact!
+    @events
+  end
+
+
+  private
+
+  def add event
+    @events[@index] = event
+    @index += 1
+  end
+  def previous_token; @events[@index-1] end
+  def rewind_index;   @index -= 1       end
+
+  def gen_all tokens
+    tokens.each do |token|
+      if token.kind_of? Array
+        gen_nested token.first, token[1..-1]
+      else
+        gen_single token
+      end
+    end
+  end
+
+  def gen_nested head, tail
+    ((code =   CUSTOM[head]) &&  gen_dynamic(code, tail)) ||
+     ((code =  MAPPING[head]) &&  gen_dynamic(code, tail)) ||
+     ((code =  SHIFTED[head]) &&  gen_shifted(code, tail)) ||
+     ((code = OPTIONED[head]) && gen_optioned(code, tail)) ||
+     gen_all(head.split(EMPTY_STRING)) # handling a special case :(
+  end
+
+  def gen_single token
+    ((code =  MAPPING[token]) &&  gen_dynamic(code, nil)) ||
+     ((code =  SHIFTED[token]) &&  gen_shifted(code, nil)) ||
+     ((code = OPTIONED[token]) && gen_optioned(code, nil)) ||
+     raise(ArgumentError, "#{token.inspect} has no mapping, bail!")
+  end
+
+  def gen_shifted code, tail
+    previous_token == SHIFT_UP ? rewind_index : add(SHIFT_DOWN)
+    gen_dynamic MAPPING[code], tail
+    add SHIFT_UP
+  end
+
+  def gen_optioned code, tail
+    previous_token == OPTION_UP ? rewind_index : add(OPTION_DOWN)
+    gen_dynamic MAPPING[code], tail
+    add OPTION_UP
+  end
+
+  def gen_dynamic code, tail
+    add [code,  true]
+    gen_all tail if tail
+    add [code, false]
+  end
+
+  # @private
+  # @return [String]
+  EMPTY_STRING = ""
+  # @private
+  # @return [Array(Number,Boolean)]
+  OPTION_DOWN  = [58,  true]
+  # @private
+  # @return [Array(Number,Boolean)]
+  OPTION_UP    = [58, false]
+  # @private
+  # @return [Array(Number,Boolean)]
+  SHIFT_DOWN   = [56,  true]
+  # @private
+  # @return [Array(Number,Boolean)]
+  SHIFT_UP     = [56, false]
+end

data/lib/accessibility/keyboard/parser.rb

@@ -0,0 +1,111 @@
+require 'accessibility/keyboard/version'
+
+##
+# Parse arbitrary strings into a stream of keyboard events
+#
+# This class will take a string and break it up into chunks for the keyboard
+# event generator. The structure generated here is an array that contains
+# strings and recursively other arrays of strings and arrays of strings.
+#
+# @example
+#
+#   Parser.new("Hai").parse          # => ['H','a','i']
+#   Parser.new("\\CONTROL").parse    # => [["\\CONTROL"]]
+#   Parser.new("\\COMMAND+a").parse  # => [["\\COMMAND", ['a']]]
+#   Parser.new("One\nTwo").parse     # => ['O','n','e',"\n",'T','w','o']
+#
+class Accessibility::Keyboard::Parser
+
+  ##
+  # Once a string is parsed, this contains the tokenized structure.
+  #
+  # @return [Array<String,Array<String,...>]
+  attr_accessor :tokens
+
+  # @param string [String,#to_s]
+  def initialize string
+    @chars  = string.to_s
+    @tokens = []
+  end
+
+  ##
+  # Tokenize the string that the parser was initialized with and
+  # return the sequence of tokens that were parsed.
+  #
+  # @return [Array<String,Array<String,...>]
+  def parse
+    length = @chars.length
+    @index = 0
+    while @index < length
+      @tokens << if custom?
+                   parse_custom
+                 else
+                   parse_char
+                 end
+      @index += 1
+    end
+    @tokens
+  end
+
+
+  private
+
+  ##
+  # Is it a real custom escape? Kind of a lie, there is one
+  # case it does not handle--they get handled in the generator,
+  # but maybe they should be handled here?
+  # - An upper case letter or symbol following `"\\"` that is
+  #   not mapped
+  def custom?
+    @chars[@index] == CUSTOM_ESCAPE &&
+     (next_char = @chars[@index+1]) &&
+     next_char == next_char.upcase &&
+     next_char != SPACE
+  end
+
+  # @todo refactor
+  # @return [Array]
+  def parse_custom
+    start = @index
+    loop do
+      char = @chars[@index]
+      if char == PLUS
+        if @chars[@index-1] == CUSTOM_ESCAPE # \\+ case
+          @index += 1
+          return custom_subseq start
+        else
+          tokens  = custom_subseq start
+          @index += 1
+          return tokens << parse_custom
+        end
+      elsif char == SPACE
+        return custom_subseq start
+      elsif char == nil
+        raise ArgumentError, "Bad escape sequence" if start == @index
+        return custom_subseq start
+      else
+        @index += 1
+      end
+    end
+  end
+
+  # @return [Array]
+  def custom_subseq start
+    [@chars[start...@index]]
+  end
+
+  # @return [String]
+  def parse_char
+    @chars[@index]
+  end
+
+  # @private
+  # @return [String]
+  SPACE         = " "
+  # @private
+  # @return [String]
+  PLUS          = "+"
+  # @private
+  # @return [String]
+  CUSTOM_ESCAPE = "\\"
+end

data/lib/accessibility/keyboard/version.rb

@@ -0,0 +1,8 @@
+##
+# Namespace for accessibility related objects
+module Accessibility
+  module Keyboard
+    # @return [String]
+    VERSION = '1.0.0'
+  end
+end

data/test/event_generator_test.rb

@@ -0,0 +1,149 @@
+# -*- coding: utf-8 -*-
+require 'test/helper'
+require 'accessibility/keyboard/event_generator'
+
+class TestEventGenerator < MiniTest::Unit::TestCase
+
+  def gen tokens
+    Accessibility::Keyboard::EventGenerator.new(tokens).generate
+  end
+
+  def map; @@map ||= KeyCoder.dynamic_mapping; end
+
+  def t; true; end
+  def f; false; end
+
+  def a; @@a ||= map['a']; end
+  def c; @@c ||= map['c']; end
+  def e; @@e ||= map['e']; end
+  def h; @@h ||= map['h']; end
+  def i; @@i ||= map['i']; end
+  def k; @@k ||= map['k']; end
+  def m; @@m ||= map["m"]; end
+
+  def two;  @@two  ||= map['2']; end
+  def four; @@four ||= map['4']; end
+
+  def retern; @@retern ||= map["\r"]; end
+  def tab;    @@tab    ||= map["\t"]; end
+  def space;  @@space  ||= map["\s"]; end
+
+  def dash;  @@dash  ||= map["-"]; end
+  def comma; @@comma ||= map[","]; end
+  def apos;  @@apos  ||= map["'"]; end
+  def at;    @@at    ||= map["2"]; end
+  def paren; @@paren ||= map["9"]; end
+  def chev;  @@chev  ||= map["."]; end
+
+  def sigma; @@sigma ||= map["w"]; end
+  def tm;    @@tm    ||= map["2"]; end
+  def gbp;   @@gbp   ||= map["3"]; end
+  def omega; @@omega ||= map["z"]; end
+
+  def bslash; @@blash ||= map["\\"]; end
+
+  # key code for the left shift key
+  def sd; [56,t];  end
+  def su; [56,f]; end
+
+  # key code for the left option key
+  def od; [58,t];  end
+  def ou; [58,f]; end
+
+  # key code for the left command key
+  def cd; [0x37,t]; end
+  def cu; [0x37,f]; end
+
+  # key code for right arrow key
+  def rd; [0x7c,t]; end
+  def ru; [0x7c,f]; end
+
+  # key code for left control key
+  def ctrld; [0x3B,t]; end
+  def ctrlu; [0x3B,f]; end
+
+
+  def test_generate_lowercase
+    assert_equal [[a,t],[a,f]],                                     gen(['a'])
+    assert_equal [[c,t],[c,f],[k,t],[k,f]],                         gen(['c','k'])
+    assert_equal [[e,t],[e,f],[e,t],[e,f]],                         gen(['e','e'])
+    assert_equal [[c,t],[c,f],[a,t],[a,f],[k,t],[k,f],[e,t],[e,f]], gen(['c','a','k','e'])
+  end
+
+  def test_generate_uppercase
+    assert_equal [sd,[a,t],[a,f],su],                         gen(['A'])
+    assert_equal [sd,[c,t],[c,f],[k,t],[k,f],su],             gen(['C','K'])
+    assert_equal [sd,[e,t],[e,f],[e,t],[e,f],su],             gen(['E','E'])
+    assert_equal [sd,[c,t],[c,f],[a,t],[a,f],[k,t],[k,f],su], gen(['C','A','K'])
+  end
+
+  def test_generate_numbers
+    assert_equal [[two,t],[two,f]],                   gen(['2'])
+    assert_equal [[four,t],[four,f],[two,t],[two,f]], gen(['4','2'])
+    assert_equal [[two,t],[two,f],[two,t],[two,f]],   gen(['2','2'])
+  end
+
+  def test_generate_ruby_escapes
+    assert_equal [[retern,t],[retern,f]], gen(["\r"])
+    assert_equal [[retern,t],[retern,f]], gen(["\n"])
+    assert_equal [[tab,t],[tab,f]],       gen(["\t"])
+    assert_equal [[space,t],[space,f]],   gen(["\s"])
+    assert_equal [[space,t],[space,f]],   gen([" "])
+  end
+
+  def test_generate_symbols
+    assert_equal [[dash,t],[dash,f]],         gen(["-"])
+    assert_equal [[comma,t],[comma,f]],       gen([","])
+    assert_equal [[apos,t],[apos,f]],         gen(["'"])
+    assert_equal [sd,[at,t],[at,f],su],       gen(["@"])
+    assert_equal [sd,[paren,t],[paren,f],su], gen(["("])
+    assert_equal [sd,[chev,t],[chev,f],su],   gen([">"])
+  end
+
+  def test_generate_unicode # holding option
+    assert_equal [od,[sigma,t],[sigma,f],ou],           gen(["∑"])
+    assert_equal [od,[tm,t],[tm,f],ou],                 gen(["™"])
+    assert_equal [od,[gbp,t],[gbp,f],ou],               gen(["£"])
+    assert_equal [od,[omega,t],[omega,f],ou],           gen(["Ω"])
+    assert_equal [od,[tm,t],[tm,f],[gbp,t],[gbp,f],ou], gen(["™","£"])
+  end
+
+  def test_generate_backslashes
+    assert_equal [[bslash,t],[bslash,f]],                               gen(["\\"])
+    assert_equal [[bslash,t],[bslash,f],[space,t],[space,f]],           gen(["\\"," "])
+    assert_equal [[bslash,t],[bslash,f],[h,t],[h,f],[m,t],[m,f]],       gen(["\\",'h','m'])
+    # is this the job of the parser or the lexer?
+    assert_equal [[bslash,t],[bslash,f],sd,[h,t],[h,f],[m,t],[m,f],su], gen([["\\HM"]])
+  end
+
+  def test_generate_a_custom_escape
+    assert_equal [cd,cu],       gen([["\\COMMAND"]])
+    assert_equal [cd,cu],       gen([["\\CMD"]])
+    assert_equal [ctrld,ctrlu], gen([["\\CONTROL"]])
+    assert_equal [ctrld,ctrlu], gen([["\\CTRL"]])
+  end
+
+  def test_generate_hotkey
+    assert_equal [ctrld,[a,t],[a,f],ctrlu], gen([["\\CONTROL",["a"]]])
+    assert_equal [cd,sd,rd,ru,su,cu],       gen([["\\COMMAND",['\SHIFT',['\->']]]])
+  end
+
+  def test_generate_real_use # a regression
+    assert_equal [ctrld,[a,t],[a,f],ctrlu,[h,t],[h,f]], gen([["\\CTRL",["a"]],"h"])
+  end
+
+  def test_bails_for_unmapped_token
+    # cannot generate snowmen :(
+    e = assert_raises(ArgumentError) { gen(["☃"]) }
+    assert_match /bail/i, e.message
+  end
+
+  def test_generate_arbitrary_nested_array_sequence
+    assert_equal [[c,t],[a,t],[k,t],[e,t],[e,f],[k,f],[a,f],[c,f]], gen([["c",["a",["k",["e"]]]]])
+  end
+
+  def test_generate_command_A
+    assert_equal [cd,sd,[a,t],[a,f],su,cu], gen([["\\COMMAND",["A"]]])
+  end
+
+end

data/test/helper.rb

@@ -0,0 +1,3 @@
+gem 'minitest'
+require 'minitest/autorun'
+require 'minitest/pride'

data/test/keyboard_test.rb

@@ -0,0 +1,29 @@
+require 'test/helper'
+require 'accessibility/keyboard'
+
+# @note DO NOT TEST POSTING EVENTS HERE
+# We only want to test posting events if all the tests in this file pass,
+# otherwise the posted events may be unpredictable depending on what fails.
+# Test event posting in the integration tests.
+class TestKeyboard < MiniTest::Unit::TestCase
+  include Accessibility::Keyboard
+
+  # basic test to make sure the lexer and generator get along
+  def test_keyboard_events_for
+    events = keyboard_events_for 'cheezburger'
+    assert_kind_of Array, events
+    refute_empty events
+
+    assert_equal true,  events[0][1]
+    assert_equal false, events[1][1]
+  end
+
+  def test_dynamic_map_initialized
+    refute_empty Accessibility::Keyboard::EventGenerator::MAPPING
+  end
+
+  def test_can_parse_empty_string
+    assert_equal [], keyboard_events_for('')
+  end
+
+end

data/test/parser_test.rb

@@ -0,0 +1,62 @@
+# -*- coding: utf-8 -*-
+require 'test/helper'
+require 'accessibility/keyboard/parser'
+
+class TestParser < MiniTest::Unit::TestCase
+
+  def parse string
+    Accessibility::Keyboard::Parser.new(string).parse
+  end
+
+  def test_parse_simple_string
+    assert_equal [],                                                    parse('')
+    assert_equal ['"',"J","u","s","t"," ","W","o","r","k","s",'"',"™"], parse('"Just Works"™')
+    assert_equal ["M","i","l","k",","," ","s","h","a","k","e","."],     parse("Milk, shake.")
+    assert_equal ["D","B","7"],                                         parse("DB7")
+  end
+
+  def test_parse_single_custom_escape
+    assert_equal [["\\CMD"]], parse("\\CMD")
+    assert_equal [["\\1"]],   parse("\\1")
+    assert_equal [["\\F1"]],  parse("\\F1")
+    assert_equal [["\\*"]],   parse("\\*")
+  end
+
+  def test_parse_hotkey_custom_escape
+    assert_equal [["\\COMMAND",[","]]],             parse("\\COMMAND+,")
+    assert_equal [["\\COMMAND",["\\SHIFT",["s"]]]], parse("\\COMMAND+\\SHIFT+s")
+    assert_equal [["\\COMMAND",["\\+"]]],           parse("\\COMMAND+\\+")
+    assert_equal [["\\FN",["\\F10"]]],              parse("\\FN+\\F10")
+  end
+
+  def test_parse_ruby_escapes
+    assert_equal ["\n","\r","\t","\b"],                                parse("\n\r\t\b")
+    assert_equal ["O","n","e","\n","T","w","o"],                       parse("One\nTwo")
+    assert_equal ["L","i","e","\b","\b","\b","d","e","l","i","s","h"], parse("Lie\b\b\bdelish")
+  end
+
+  def test_parse_compparse_string
+    assert_equal ["T","e","s","t",["\\CMD",["s"]]],                          parse("Test\\CMD+s")
+    assert_equal ["Z","O","M","G"," ","1","3","3","7","!","!","1"],          parse("ZOMG 1337!!1")
+    assert_equal ["F","u","u","!","@","#","%",["\\CMD",["a"]],"\b"],         parse("Fuu!@#%\\CMD+a \b")
+    assert_equal [["\\CMD",["a"]],"\b","A","l","l"," ","g","o","n","e","!"], parse("\\CMD+a \bAll gone!")
+  end
+
+  def test_parse_backslash # make sure we handle these edge cases predictably
+    assert_equal ["\\"],             parse("\\")
+    assert_equal ["\\"," "],         parse("\\ ")
+    assert_equal ["\\","h","m","m"], parse("\\hmm")
+    assert_equal [["\\HMM"]],        parse("\\HMM") # the one missed case
+  end
+
+  def test_parse_plus_escape
+    assert_equal [["\\+"]], parse("\\+")
+  end
+
+  def test_parse_bad_custom_escape_sequence
+    assert_raises ArgumentError do
+      parse("\\COMMAND+")
+    end
+  end
+
+end

data/test/runner

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH << File.expand_path('../../', __FILE__)
+$LOAD_PATH << File.expand_path('../../lib', __FILE__)
+require 'test/helper'
+
+ARGV.each do |file|
+  if file == '-v' || file == '--verbose'
+    $VERBOSE = true
+  else
+    require file
+  end
+end
+

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: accessibility_keyboard
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Mark Rada
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-03 00:00:00.000000000 Z
+dependencies: []
+description: ! 'Simulate keyboard input via the Mac OS X Accessibility Framework.
+  This
+
+  gem is a component of AXElements.
+
+'
+email: mrada@marketcircle.com
+executables: []
+extensions:
+- ext/key_coder/extconf.rb
+extra_rdoc_files:
+- README.markdown
+- History.markdown
+- CONTRIBUTING.markdown
+- .yardopts
+files:
+- lib/accessibility/keyboard.rb
+- lib/accessibility/keyboard/version.rb
+- lib/accessibility/keyboard/parser.rb
+- lib/accessibility/keyboard/event_generator.rb
+- ext/key_coder/key_coder.c
+- ext/key_coder/extconf.rb
+- test/keyboard_test.rb
+- test/parser_test.rb
+- test/event_generator_test.rb
+- test/helper.rb
+- test/runner
+- README.markdown
+- History.markdown
+- CONTRIBUTING.markdown
+- .yardopts
+homepage: http://github.com/AXElements/accessibility_keyboard
+licenses:
+- BSD 3-clause
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -4062551165478306694
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: -4062551165478306694
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Keyboard simulation for OS X
+test_files:
+- test/keyboard_test.rb
+- test/parser_test.rb
+- test/event_generator_test.rb
+- test/helper.rb
+- test/runner