AXElements 1.0.0.beta4 → 6.0.0

data/lib/accessibility/string.rb

@@ -1,502 +0,0 @@
-# -*- 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