lib/accessibility/string.rb
# -*- coding: utf-8 -*-
require 'accessibility/version'
require 'accessibility/key_coder'
##
# Parses strings of human readable text into a series of events meant to
# be processed by {Accessibility::Core#post} or {KeyCoder.post_event}.
#
# 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`.
#
# @example
#
# app = AXUIElementCreateApplication(3456)
# include Accessibility::String
# app.post keyboard_events_for "Hello, world!\n"
#
module Accessibility::String
##
# Generate keyboard events for the given string. Strings should be in a
# human readable with a few exceptions. Command key (e.g. control, option,
# command) should be written in string as they appear in
# {Accessibility::String::EventGenerator::CUSTOM}.
#
# For more details on event generation, read the
# [Keyboarding wiki](http://github.com/Marketcircle/AXElements/wiki/Keyboarding).
#
# @param string [#to_s]
# @return [Array<Array(Fixnum,Boolean)>]
def keyboard_events_for string
EventGenerator.new(Lexer.new(string).lex).generate
end
##
# Tokenizer for strings. This class will take a string and break
# it up into chunks for the event generator. The structure generated
# here is an array that contains strings and recursively other arrays
# of strings and arrays of strings.
#
# @example
#
# Lexer.new("Hai").lex # => ['H','a','i']
# Lexer.new("\\CONTROL").lex # => [["\\CONTROL"]]
# Lexer.new("\\COMMAND+a").lex # => [["\\COMMAND", ['a']]]
# Lexer.new("One\nTwo").lex # => ['O','n','e',"\n",'T','w','o']
#
class Lexer
##
# Once a string is lexed, this contains the tokenized structure.
#
# @return [Array<String,Array<String,...>]
attr_accessor :tokens
# @param string [#to_s]
def initialize string
@chars = string.to_s
@tokens = []
end
##
# Tokenize the string that the lexer was initialized with and
# return the sequence of tokens that were lexed.
#
# @return [Array<String,Array<String,...>]
def lex
length = @chars.length
@index = 0
while @index < length
@tokens << if custom?
lex_custom
else
lex_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
# @return [Array]
def lex_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 << lex_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 lex_char
@chars[@index]
end
# @private
# @return [String]
SPACE = " "
# @private
# @return [String]
PLUS = "+"
# @private
# @return [String]
CUSTOM_ESCAPE = "\\"
end
##
# Generate a sequence of keyboard events given a sequence of tokens.
# The token format is defined by the {Lexer} 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 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
end
##
# @note This will only work if a run loop is running
# framework 'ApplicationServices' if defined? MACRUBY_VERSION
# Register to be notified if the keyboard layout changes at runtime
# NSDistributedNotificationCenter.defaultCenter.addObserver Accessibility::String::EventGenerator,
# selector: 'regenerate_dynamic_mapping',
# name: KTISNotifySelectedKeyboardInputSourceChanged,
# object: nil