keyboardjs-rails 0.2.2 → 0.4.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f9aa6f3d3905e55159d80e25b33798dc3fd9c817
+  data.tar.gz: 49a95410dbaacec8a20d3251a6890e4b05e19c8d
+SHA512:
+  metadata.gz: 4a9c678da87fdfc14ec1cc4fc8c1073c860a9b65b036e2b2efe397dceeba413991cda3d4c85eb336575bdff5122a93ca367c2b911659761b0f9f184b89101ad4
+  data.tar.gz: 8bf8a4969fcd0444ec6e7912c5e5f4d91c2303004a22be7a19710bc3be92c1d53426f1ce625f649ce6ce6df3fa253503377ae360541821e2a819fe4414dc340f

data/.ruby-gemset

@@ -0,0 +1 @@
+keyboardjs-rails

data/.ruby-version

@@ -0,0 +1 @@
+1.9.3

data/README.md

@@ -51,6 +51,14 @@ You're done!
 5. Create new Pull Request
 
 
+## Contributors
+
+Many thanks go to the following who have contributed to making this cookbook even better:
+
+* **[@kmmndr](https://github.com/kmmndr)**
+    * upgrade keyboardjs to v0.4.1
+
+
 ## License
 
 **keyboardjs-rails**

data/keyboardjs-rails.gemspec

@@ -16,6 +16,6 @@ Gem::Specification.new do |gem|
   gem.version       = KeyboardJS::Rails::VERSION
 
   gem.add_dependency "railties", ">= 3.0.0"
-  gem.add_development_dependency "bundler", "~> 1.1.3"
-  gem.add_development_dependency "rake", "~> 0.9.2.2"
+  gem.add_development_dependency "bundler"
+  gem.add_development_dependency "rake"
 end

data/lib/keyboardjs/rails/version.rb

@@ -1,6 +1,6 @@
 module KeyboardJS
   module Rails
-    VERSION = "0.2.2"
-    KEYBOARDJS_VERSION = "0.2.2"
+    VERSION = "0.4.1"
+    KEYBOARDJS_VERSION = "0.4.1"
   end
 end

data/vendor/assets/javascripts/keyboardjs.js

@@ -1,483 +1,926 @@
-/*!
- * KeyboardJS
- * 
+/**
+ * Title: KeyboardJS
+ * Version: v0.4.1
+ * Description: KeyboardJS is a flexible and easy to use keyboard binding
+ * library.
+ * Author: Robert Hurst.
+ *
  * Copyright 2011, Robert William Hurst
  * Licenced under the BSD License.
  * See https://raw.github.com/RobertWHurst/KeyboardJS/master/license.txt
  */
-(function (root, factory) {
-    if (typeof define === 'function' && define.amd) {
-        // AMD. Register as an anonymous module.
-        define(factory);
-    } else {
-        // Browser globals
-        root.KeyboardJS = factory();
-    }
-}(this, function() {
-
-	//polyfills for ms's peice o' shit browsers
-	function bind(target, type, handler) { if (target.addEventListener) { target.addEventListener(type, handler, false); } else { target.attachEvent("on" + type, function(event) { return handler.call(target, event); });Â } }
+(function(context, factory) {
+
+	//INDEXOF POLLYFILL
 	[].indexOf||(Array.prototype.indexOf=function(a,b,c){for(c=this.length,b=(c+~~b)%c;b<c&&(!(b in this)||this[b]!==a);b++);return b^c?b:-1;});
 
-	//locals
-	var locals = {
-		'us': {
-			"backspace": 8,
-			"tab": 9,
-			"enter": 13,
-			"shift": 16,
-			"ctrl": 17,
-			"alt": 18,
-			"pause": 19, "break": 19,
-			"capslock": 20,
-			"escape": 27, "esc": 27,
-			"space": 32, "spacebar": 32,
-			"pageup": 33,
-			"pagedown": 34,
-			"end": 35,
-			"home": 36,
-			"left": 37,
-			"up": 38,
-			"right": 39,
-			"down": 40,
-			"insert": 45,
-			"delete": 46,
-			"0": 48, "1": 49, "2": 50, "3": 51, "4": 52, "5": 53, "6": 54, "7": 55, "8": 56, "9": 57,
-			"a": 65, "b": 66, "c": 67, "d": 68, "e": 69, "f": 70, "g": 71, "h": 72, "i": 73, "j": 74, "k": 75, "l": 76, "m": 77, "n": 78, "o": 79, "p": 80, "q": 81, "r": 82, "s": 83, "t": 84, "u": 85, "v": 86, "w": 87, "x": 88, "y": 89, "z": 90,
-			"meta": 91, "command": 91, "windows": 91, "win": 91,
-			"_91": 92,
-			"select": 93,
-			"num0": 96, "num1": 97, "num2": 98, "num3": 99, "num4": 100, "num5": 101, "num6": 102, "num7": 103, "num8": 104, "num9": 105,
-			"multiply": 106,
-			"add": 107,
-			"subtract": 109,
-			"decimal": 110,
-			"divide": 111,
-			"f1": 112, "f2": 113, "f3": 114, "f4": 115, "f5": 116, "f6": 117, "f7": 118, "f8": 119, "f9": 120, "f10": 121, "f11": 122, "f12": 123,
-			"numlock": 144, "num": 144,
-			"scrolllock": 145, "scroll": 145,
-			"semicolon": 186,
-			"equal": 187, "equalsign": 187,
-			"comma": 188,
-			"dash": 189,
-			"period": 190,
-			"slash": 191, "forwardslash": 191,
-			"graveaccent": 192,
-			"openbracket": 219,
-			"backslash": 220,
-			"closebracket": 221,
-			"singlequote": 222
-		}
+	//AMD
+	if(typeof define === 'function' && define.amd) { define(constructAMD); }
 
-		//If you create a new local please submit it as a pull request or post it in the issue tracker at
-		// http://github.com/RobertWhurst/KeyboardJS/issues/
-	}
+	//GLOBAL
+	else { constructGlobal(); }
 
-	//keys
-	var keys = locals['us'],
-		activeKeys = [],
-		activeBindings = {},
-		keyBindingGroups = [];
+	/**
+	 * Construct AMD version of the library
+	 */
+	function constructAMD() {
 
-	//adds keys to the active keys array
-	bind(document, "keydown", function(event) {
+		//create a library instance
+		return init();
 
-		//lookup the key pressed and save it to the active keys array
-		for (var key in keys) {
-			if(keys.hasOwnProperty(key) && event.keyCode === keys[key]) {
-				if(activeKeys.indexOf(key) < 0) {
-					activeKeys.push(key);
-				}
-			}
+		//spawns a library instance
+		function init() {
+			var library;
+			library = factory('amd');
+			library.fork = init;
+			return library;
 		}
+	}
+
+	/**
+	 * Construct a Global version of the library
+	 */
+	function constructGlobal() {
+		var library;
 
-		//execute the first callback the longest key binding that matches the active keys
-		return executeActiveKeyBindings(event);
+		//create a library instance
+		library = init();
+		library.noConflict('KeyboardJS', 'k');
 
-	});
+		//spawns a library instance
+		function init() {
+			var library, namespaces = [], previousValues = {};
 
-	//removes keys from the active array
-	bind(document, "keyup", function (event) {
+			library = factory('global');
+			library.fork = init;
+			library.noConflict = noConflict;
+			return library;
 
-		//lookup the key released and prune it from the active keys array
-		for(var key in keys) {
-			if(keys.hasOwnProperty(key) && event.keyCode === keys[key]) {
+			//sets library namespaces
+			function noConflict(    ) {
+				var args, nI, newNamespaces;
 
-				var iAK = activeKeys.indexOf(key);
+				newNamespaces = Array.prototype.slice.apply(arguments);
 
-				if(iAK > -1) {
-					activeKeys.splice(iAK, 1);
+				for(nI = 0; nI < namespaces.length; nI += 1) {
+					if(typeof previousValues[namespaces[nI]] === 'undefined') {
+						delete context[namespaces[nI]];
+					} else {
+						context[namespaces[nI]] = previousValues[namespaces[nI]];
+					}
 				}
+
+				previousValues = {};
+
+				for(nI = 0; nI < newNamespaces.length; nI += 1) {
+					if(typeof newNamespaces[nI] !== 'string') {
+						throw new Error('Cannot replace namespaces. All new namespaces must be strings.');
+					}
+					previousValues[newNamespaces[nI]] = context[newNamespaces[nI]];
+					context[newNamespaces[nI]] = library;
+				}
+
+				namespaces = newNamespaces;
+
+				return namespaces;
 			}
 		}
+	}
+})(this, function(env) {
+	var KeyboardJS = {}, locales = {}, locale, map, macros, activeKeys = [], bindings = [], activeBindings = [],
+	activeMacros = [], aI, usLocale;
+
+
+	///////////////////////
+	// DEFUALT US LOCALE //
+	///////////////////////
+
+	//define US locale
+	//If you create a new locale please submit it as a pull request or post
+	// it in the issue tracker at
+	// http://github.com/RobertWhurst/KeyboardJS/issues/
+	usLocale = {
+		"map": {
+
+			//general
+			"3": ["cancel"],
+			"8": ["backspace"],
+			"9": ["tab"],
+			"12": ["clear"],
+			"13": ["enter"],
+			"16": ["shift"],
+			"17": ["ctrl"],
+			"18": ["alt", "menu"],
+			"19": ["pause", "break"],
+			"20": ["capslock"],
+			"27": ["escape", "esc"],
+			"32": ["space", "spacebar"],
+			"33": ["pageup"],
+			"34": ["pagedown"],
+			"35": ["end"],
+			"36": ["home"],
+			"37": ["left"],
+			"38": ["up"],
+			"39": ["right"],
+			"40": ["down"],
+			"41": ["select"],
+			"42": ["printscreen"],
+			"43": ["execute"],
+			"44": ["snapshot"],
+			"45": ["insert", "ins"],
+			"46": ["delete", "del"],
+			"47": ["help"],
+			"91": ["command", "windows", "win", "super", "leftcommand", "leftwindows", "leftwin", "leftsuper"],
+			"92": ["command", "windows", "win", "super", "rightcommand", "rightwindows", "rightwin", "rightsuper"],
+			"145": ["scrolllock", "scroll"],
+			"186": ["semicolon", ";"],
+			"187": ["equal", "equalsign", "="],
+			"188": ["comma", ","],
+			"189": ["dash", "-"],
+			"190": ["period", "."],
+			"191": ["slash", "forwardslash", "/"],
+			"192": ["graveaccent", "`"],
+			"219": ["openbracket", "["],
+			"220": ["backslash", "\\"],
+			"221": ["closebracket", "]"],
+			"222": ["apostrophe", "'"],
+
+			//0-9
+			"48": ["zero", "0"],
+			"49": ["one", "1"],
+			"50": ["two", "2"],
+			"51": ["three", "3"],
+			"52": ["four", "4"],
+			"53": ["five", "5"],
+			"54": ["six", "6"],
+			"55": ["seven", "7"],
+			"56": ["eight", "8"],
+			"57": ["nine", "9"],
+
+			//numpad
+			"96": ["numzero", "num0"],
+			"97": ["numone", "num1"],
+			"98": ["numtwo", "num2"],
+			"99": ["numthree", "num3"],
+			"100": ["numfour", "num4"],
+			"101": ["numfive", "num5"],
+			"102": ["numsix", "num6"],
+			"103": ["numseven", "num7"],
+			"104": ["numeight", "num8"],
+			"105": ["numnine", "num9"],
+			"106": ["nummultiply", "num*"],
+			"107": ["numadd", "num+"],
+			"108": ["numenter"],
+			"109": ["numsubtract", "num-"],
+			"110": ["numdecimal", "num."],
+			"111": ["numdevide", "num/"],
+			"144": ["numlock", "num"],
+
+			//function keys
+			"112": ["f1"],
+			"113": ["f2"],
+			"114": ["f3"],
+			"115": ["f4"],
+			"116": ["f5"],
+			"117": ["f6"],
+			"118": ["f7"],
+			"119": ["f8"],
+			"120": ["f9"],
+			"121": ["f10"],
+			"122": ["f11"],
+			"123": ["f12"]
+		},
+		"macros": [
+
+			//secondary key symbols
+			['shift + `', ["tilde", "~"]],
+			['shift + 1', ["exclamation", "exclamationpoint", "!"]],
+			['shift + 2', ["at", "@"]],
+			['shift + 3', ["number", "#"]],
+			['shift + 4', ["dollar", "dollars", "dollarsign", "$"]],
+			['shift + 5', ["percent", "%"]],
+			['shift + 6', ["caret", "^"]],
+			['shift + 7', ["ampersand", "and", "&"]],
+			['shift + 8', ["asterisk", "*"]],
+			['shift + 9', ["openparen", "("]],
+			['shift + 0', ["closeparen", ")"]],
+			['shift + -', ["underscore", "_"]],
+			['shift + =', ["plus", "+"]],
+			['shift + (', ["opencurlybrace", "opencurlybracket", "{"]],
+			['shift + )', ["closecurlybrace", "closecurlybracket", "}"]],
+			['shift + \\', ["verticalbar", "|"]],
+			['shift + ;', ["colon", ":"]],
+			['shift + \'', ["quotationmark", "\""]],
+			['shift + !,', ["openanglebracket", "<"]],
+			['shift + .', ["closeanglebracket", ">"]],
+			['shift + /', ["questionmark", "?"]]
+		]
+	};
+	//a-z and A-Z
+	for (aI = 65; aI <= 90; aI += 1) {
+		usLocale.map[aI] = String.fromCharCode(aI + 32);
+		usLocale.macros.push(['shift + ' + String.fromCharCode(aI + 32) + ', capslock + ' + String.fromCharCode(aI + 32), [String.fromCharCode(aI)]]);
+	}
+	registerLocale('us', usLocale);
+	getSetLocale('us');
+
+
+	//////////
+	// INIT //
+	//////////
+
+	//enable the library
+	enable();
+
+
+	/////////
+	// API //
+	/////////
+
+	//assemble the library and return it
+	KeyboardJS.enable = enable;
+	KeyboardJS.disable = disable;
+	KeyboardJS.activeKeys = getActiveKeys;
+	KeyboardJS.on = createBinding;
+	KeyboardJS.clear = removeBindingByKeyCombo;
+	KeyboardJS.clear.key = removeBindingByKeyName;
+	KeyboardJS.locale = getSetLocale;
+	KeyboardJS.locale.register = registerLocale;
+	KeyboardJS.macro = createMacro;
+	KeyboardJS.macro.remove = removeMacro;
+	KeyboardJS.key = {};
+	KeyboardJS.key.name = getKeyName;
+	KeyboardJS.key.code = getKeyCode;
+	KeyboardJS.combo = {};
+	KeyboardJS.combo.active = isSatisfiedCombo;
+	KeyboardJS.combo.parse = parseKeyCombo;
+	KeyboardJS.combo.stringify = stringifyKeyCombo;
+	return KeyboardJS;
+
+
+	//////////////////////
+	// INSTANCE METHODS //
+	//////////////////////
 
-		//execute the end callback on the active key binding
-		return pruneActiveKeyBindings(event);
+	/**
+	 * Enables KeyboardJS
+	 */
+	function enable() {
+		if(window.addEventListener) {
+			document.addEventListener('keydown', keydown, false);
+			document.addEventListener('keyup', keyup, false);
+			window.addEventListener('blur', reset, false);
+		} else if(window.attachEvent) {
+			document.attachEvent('onkeydown', keydown);
+			document.attachEvent('onkeyup', keyup);
+			window.attachEvent('onblur', reset);
+		}
+	}
+
+	/**
+	 * Exits all active bindings and disables KeyboardJS
+	 */
+	function disable() {
+		reset();
+		if(window.removeEventListener) {
+			document.removeEventListener('keydown', keydown, false);
+			document.removeEventListener('keyup', keyup, false);
+			window.removeEventListener('blur', reset, false);
+		} else if(window.detachEvent) {
+			document.detachEvent('onkeydown', keydown);
+			document.detachEvent('onkeyup', keyup);
+			window.detachEvent('onblur', reset);
+		}
+	}
+
+
+	////////////////////
+	// EVENT HANDLERS //
+	////////////////////
+
+	/**
+	 * Exits all active bindings. Optionally passes an event to all binding
+	 *  handlers.
+	 * @param  {KeyboardEvent}	event	[Optional]
+	 */
+	function reset(event) {
+		activeKeys = [];
+		pruneMacros();
+		pruneBindings(event);
+	}
 
-	});
+	/**
+	 * Key down event handler.
+	 * @param  {KeyboardEvent}	event
+	 */
+	function keydown(event) {
+		var keyNames, kI;
+		keyNames = getKeyName(event.keyCode);
+		if(keyNames.length < 1) { return; }
+		for(kI = 0; kI < keyNames.length; kI += 1) {
+			addActiveKey(keyNames[kI]);
+		}
+		executeMacros();
+		executeBindings(event);
+	}
+
+	/**
+	 * Key up event handler.
+	 * @param  {KeyboardEvent} event
+	 */
+	function keyup(event) {
+		var keyNames, kI;
+		keyNames = getKeyName(event.keyCode);
+		if(keyNames.length < 1) { return; }
+		for(kI = 0; kI < keyNames.length; kI += 1) {
+			removeActiveKey(keyNames[kI]);
+		}
+		pruneMacros();
+		pruneBindings(event);
+	}
 
 	/**
-	 * Generates an array of active key bindings
+	 * Accepts a key code and returns the key names defined by the current
+	 *  locale.
+	 * @param  {Number}	keyCode
+	 * @return {Array}	keyNames	An array of key names defined for the key
+	 *  code as defined by the current locale.
 	 */
-	function queryActiveBindings() {
-		var bindingStack = [];
+	function getKeyName(keyCode) {
+		return map[keyCode] || [];
+	}
 
-		//loop through the key binding groups by number of keys.
-		for(var keyCount = keyBindingGroups.length; keyCount > -1; keyCount -= 1) {
-			if(keyBindingGroups[keyCount]) {
-				var KeyBindingGroup = keyBindingGroups[keyCount];
+	/**
+	 * Accepts a key name and returns the key code defined by the current
+	 *  locale.
+	 * @param  {Number}	keyName
+	 * @return {Number|false}
+	 */
+	function getKeyCode(keyName) {
+		var keyCode;
+		for(keyCode in map) {
+			if(!map.hasOwnProperty(keyCode)) { continue; }
+			if(map[keyCode].indexOf(keyName) > -1) { return keyCode; }
+		}
+		return false;
+	}
 
-				//loop through the key bindings of the same key length.
-				for(var bindingIndex = 0; bindingIndex < KeyBindingGroup.length; bindingIndex += 1) {
-					var binding = KeyBindingGroup[bindingIndex],
 
-					//assume the binding is active till a required key is found to be unsatisfied
-						keyBindingActive = true;
+	////////////
+	// MACROS //
+	////////////
 
-					//loop through each key required by the binding.
-					for(var keyIndex = 0; keyIndex < binding.keys.length;  keyIndex += 1) {
-						var key = binding.keys[keyIndex];
+	/**
+	 * Accepts a key combo and an array of key names to inject once the key
+	 *  combo is satisfied.
+	 * @param  {String}	combo
+	 * @param  {Array}	injectedKeys
+	 */
+	function createMacro(combo, injectedKeys) {
+		if(typeof combo !== 'string' && (typeof combo !== 'object' || typeof combo.push !== 'function')) {
+			throw new Error("Cannot create macro. The combo must be a string or array.");
+		}
+		if(typeof injectedKeys !== 'object' || typeof injectedKeys.push !== 'function') {
+			throw new Error("Cannot create macro. The injectedKeys must be an array.");
+		}
+		macros.push([combo, injectedKeys]);
+	}
 
-						//if the current key is not in the active keys array the mark the binding as inactive
-						if(activeKeys.indexOf(key) < 0) {
-							keyBindingActive = false;
-						}
-					}
+	/**
+	 * Accepts a key combo and clears any and all macros bound to that key
+	 * combo.
+	 * @param  {String} combo
+	 */
+	function removeMacro(combo) {
+		var macro;
+		if(typeof combo !== 'string' && (typeof combo !== 'object' || typeof combo.push !== 'function')) { throw new Error("Cannot remove macro. The combo must be a string or array."); }
+		for(mI = 0; mI < macros.length; mI += 1) {
+			macro = macros[mI];
+			if(compareCombos(combo, macro[0])) {
+				removeActiveKey(macro[1]);
+				macros.splice(mI, 1);
+				break;
+			}
+		}
+	}
 
-					//if the key combo is still active then push it into the binding stack
-					if(keyBindingActive) {
-						bindingStack.push(binding);
-					}
+	/**
+	 * Executes macros against the active keys. Each macro's key combo is
+	 *  checked and if found to be satisfied, the macro's key names are injected
+	 *  into active keys.
+	 */
+	function executeMacros() {
+		var mI, combo, kI;
+		for(mI = 0; mI < macros.length; mI += 1) {
+			combo = parseKeyCombo(macros[mI][0]);
+			if(activeMacros.indexOf(macros[mI]) === -1 && isSatisfiedCombo(combo)) {
+				activeMacros.push(macros[mI]);
+				for(kI = 0; kI < macros[mI][1].length; kI += 1) {
+					addActiveKey(macros[mI][1][kI]);
 				}
 			}
 		}
+	}
 
-		return bindingStack;
+	/**
+	 * Prunes active macros. Checks each active macro's key combo and if found
+	 *  to no longer to be satisfied, each of the macro's key names are removed
+	 *  from active keys.
+	 */
+	function pruneMacros() {
+		var mI, combo, kI;
+		for(mI = 0; mI < activeMacros.length; mI += 1) {
+			combo = parseKeyCombo(activeMacros[mI][0]);
+			if(isSatisfiedCombo(combo) === false) {
+				for(kI = 0; kI < activeMacros[mI][1].length; kI += 1) {
+					removeActiveKey(activeMacros[mI][1][kI]);
+				}
+				activeMacros.splice(mI, 1);
+				mI -= 1;
+			}
+		}
 	}
 
+
+	//////////////
+	// BINDINGS //
+	//////////////
+
 	/**
-	 * Collects active keys, sets active binds and fires on key down callbacks
-	 * @param event
+	 * Creates a binding object, and, if provided, binds a key down hander and
+	 *  a key up handler. Returns a binding object that emits keyup and
+	 *  keydown events.
+	 * @param  {String}		keyCombo
+	 * @param  {Function}	keyDownCallback	[Optional]
+	 * @param  {Function}	keyUpCallback	[Optional]
+	 * @return {Object}		binding
 	 */
-	function executeActiveKeyBindings(event) {
+	function createBinding(keyCombo, keyDownCallback, keyUpCallback) {
+		var api = {}, binding, subBindings = [], bindingApi = {}, kI,
+		subCombo;
 
-		if(activeKeys < 1) {
-			return true;
+		//break the combo down into a combo array
+		if(typeof keyCombo === 'string') {
+			keyCombo = parseKeyCombo(keyCombo);
 		}
 
-		var bindingStack = queryActiveBindings(),
-			spentKeys = [],
-			output;
-
-		//loop through each active binding
-		for (var bindingIndex = 0; bindingIndex < bindingStack.length; bindingIndex += 1) {
-			var binding = bindingStack[bindingIndex],
-				usesSpentKey = false;
-
-			//check each of the required keys. Make sure they have not been used by another binding
-			for(var keyIndex = 0; keyIndex < binding.keys.length; keyIndex += 1) {
-				var key = binding.keys[keyIndex];
-				if(spentKeys.indexOf(key) > -1) {
-					usesSpentKey = true;
-					break;
-				}
-			}
+		//bind each sub combo contained within the combo string
+		for(kI = 0; kI < keyCombo.length; kI += 1) {
+			binding = {};
 
-			//if the binding does not use a key that has been spent then execute it
-			if(!usesSpentKey) {
+			//stringify the combo again
+			subCombo = stringifyKeyCombo([keyCombo[kI]]);
 
-				//fire the callback
-				if(typeof binding.callback === "function") {
-					if(!binding.callback(event, binding.keys, binding.keyCombo)) {
-						output = false
-					}
-				}
+			//validate the sub combo
+			if(typeof subCombo !== 'string') { throw new Error('Failed to bind key combo. The key combo must be string.'); }
+
+			//create the binding
+			binding.keyCombo = subCombo;
+			binding.keyDownCallback = [];
+			binding.keyUpCallback = [];
+
+			//inject the key down and key up callbacks if given
+			if(keyDownCallback) { binding.keyDownCallback.push(keyDownCallback); }
+			if(keyUpCallback) { binding.keyUpCallback.push(keyUpCallback); }
 
-				//add the binding's combo to the active bindings array
-				if(!activeBindings[binding.keyCombo]) {
-					activeBindings[binding.keyCombo] = binding;
+			//stash the new binding
+			bindings.push(binding);
+			subBindings.push(binding);
+		}
+
+		//build the binding api
+		api.clear = clear;
+		api.on = on;
+		return api;
+
+		/**
+		 * Clears the binding
+		 */
+		function clear() {
+			var bI;
+			for(bI = 0; bI < subBindings.length; bI += 1) {
+				bindings.splice(bindings.indexOf(subBindings[bI]), 1);
+			}
+		}
+
+		/**
+		 * Accepts an event name. and any number of callbacks. When the event is
+		 *  emitted, all callbacks are executed. Available events are key up and
+		 *  key down.
+		 * @param  {String}	eventName
+		 * @return {Object}	subBinding
+		 */
+		function on(eventName    ) {
+			var api = {}, callbacks, cI, bI;
+
+			//validate event name
+			if(typeof eventName !== 'string') { throw new Error('Cannot bind callback. The event name must be a string.'); }
+			if(eventName !== 'keyup' && eventName !== 'keydown') { throw new Error('Cannot bind callback. The event name must be a "keyup" or "keydown".'); }
+
+			//gather the callbacks
+			callbacks = Array.prototype.slice.apply(arguments, [1]);
+
+			//stash each the new binding
+			for(cI = 0; cI < callbacks.length; cI += 1) {
+				if(typeof callbacks[cI] === 'function') {
+					if(eventName === 'keyup') {
+						for(bI = 0; bI < subBindings.length; bI += 1) {
+							subBindings[bI].keyUpCallback.push(callbacks[cI]);
+						}
+					} else if(eventName === 'keydown') {
+						for(bI = 0; bI < subBindings.length; bI += 1) {
+							subBindings[bI].keyDownCallback.push(callbacks[cI]);
+						}
+					}
 				}
+			}
 
-				//add the current key binding's keys to the spent keys array
-				for(var keyIndex = 0; keyIndex < binding.keys.length; keyIndex += 1) {
-					var key = binding.keys[keyIndex];
-					if(spentKeys.indexOf(key) < 0) {
-						spentKeys.push(key);
+			//construct and return the sub binding api
+			api.clear = clear;
+			return api;
+
+			/**
+			 * Clears the binding
+			 */
+			function clear() {
+				var cI, bI;
+				for(cI = 0; cI < callbacks.length; cI += 1) {
+					if(typeof callbacks[cI] === 'function') {
+						if(eventName === 'keyup') {
+							for(bI = 0; bI < subBindings.length; bI += 1) {
+								subBindings[bI].keyUpCallback.splice(subBindings[bI].keyUpCallback.indexOf(callbacks[cI]), 1);
+							}
+						} else {
+							for(bI = 0; bI < subBindings.length; bI += 1) {
+								subBindings[bI].keyDownCallback.splice(subBindings[bI].keyDownCallback.indexOf(callbacks[cI]), 1);
+							}
+						}
 					}
 				}
 			}
 		}
+	}
 
-		//if there are spent keys then we know a binding was fired
-		// and that we need to tell jQuery to prevent event bubbling.
-		if(spentKeys.length) {
-			return false;
+	/**
+	 * Clears all binding attached to a given key combo. Key name order does not
+	 * matter as long as the key combos equate.
+	 * @param  {String}	keyCombo
+	 */
+	function removeBindingByKeyCombo(keyCombo) {
+		var bI, binding, keyName;
+		for(bI = 0; bI < bindings.length; bI += 1) {
+			binding = bindings[bI];
+			if(compareCombos(keyCombo, binding.keyCombo)) {
+				bindings.splice(bI, 1); bI -= 1;
+			}
 		}
-
-		return output;
 	}
 
 	/**
-	 * Removes no longer active keys and fires the on key up callbacks for associated active bindings.
-	 * @param event
+	 * Clears all binding attached to key combos containing a given key name.
+	 * @param  {String}	keyName
 	 */
-	function pruneActiveKeyBindings(event) {
-		var bindingStack = queryActiveBindings();
-		var output;
-
-		//loop through the active combos
-		for(var bindingCombo in activeBindings) {
-			if(activeBindings.hasOwnProperty(bindingCombo)) {
-				var binding = activeBindings[bindingCombo],
-					active = false;
-
-				//loop thorugh the active bindings
-				for(var bindingIndex = 0; bindingIndex < bindingStack.length; bindingIndex += 1) {
-					var activeCombo = bindingStack[bindingIndex].keyCombo;
-
-					//check to see if the combo is still active
-					if(activeCombo === bindingCombo) {
-						active = true;
+	function removeBindingByKeyName(keyName) {
+		var bI, cI, binding;
+		if(keyName) {
+			for(bI = 0; bI < bindings.length; bI += 1) {
+				binding = bindings[bI];
+				for(cI = 0; cI < binding.keyCombo.length; cI += 1) {
+					if(binding.keyCombo[kI].indexOf(keyName) > -1) {
+						bindings.splice(bI, 1); bI -= 1;
 						break;
 					}
 				}
+			}
+		} else {
+			bindings = [];
+		}
+	}
 
-				//if the combo is no longer active then fire its end callback and remove it
-				if(!active) {
-
-					if(typeof binding.endCallback === "function") {
-						if(!binding.endCallback(event, binding.keys, binding.keyCombo)) {
-							output = false
+	/**
+	 * Executes bindings that are active. Only allows the keys to be used once
+	 *  as to prevent binding overlap.
+	 * @param  {KeyboardEvent}	event	The keyboard event.
+	 */
+	function executeBindings(event) {
+		var bI, sBI, binding, bidningKeys, remainingKeys, cI, killEventBubble, kI, bindingKeysSatisfied,
+		index, sortedBindings = [], bindingWeight;
+
+		remainingKeys = [].concat(activeKeys);
+		for(bI = 0; bI < bindings.length; bI += 1) {
+			bindingWeight = extractComboKeys(bindings[bI].keyCombo).length;
+			if(!sortedBindings[bindingWeight]) { sortedBindings[bindingWeight] = []; }
+			sortedBindings[bindingWeight].push(bindings[bI]);
+		}
+		for(sBI = sortedBindings.length - 1; sBI >= 0; sBI -= 1) {
+			if(!sortedBindings[sBI]) { continue; }
+			for(bI = 0; bI < sortedBindings[sBI].length; bI += 1) {
+				binding = sortedBindings[sBI][bI];
+				bindingKeys = extractComboKeys(binding.keyCombo);
+				bindingKeysSatisfied = true;
+				for(kI = 0; kI < bindingKeys.length; kI += 1) {
+					if(remainingKeys.indexOf(bindingKeys[kI]) === -1) {
+						bindingKeysSatisfied = false;
+						break;
+					}
+				}
+				if(bindingKeysSatisfied && isSatisfiedCombo(binding.keyCombo)) {
+					activeBindings.push(binding);
+					for(kI = 0; kI < bindingKeys.length; kI += 1) {
+						index = remainingKeys.indexOf(bindingKeys[kI]);
+						if(index > -1) {
+							remainingKeys.splice(index, 1);
+							kI -= 1;
 						}
 					}
-
-					delete activeBindings[bindingCombo];
+					for(cI = 0; cI < binding.keyDownCallback.length; cI += 1) {
+						if (binding.keyDownCallback[cI](event, getActiveKeys(), binding.keyCombo) === false) {
+							killEventBubble = true;
+						}
+					}
+					if(killEventBubble === true) {
+						event.preventDefault();
+						event.stopPropagation();
+					}
 				}
 			}
 		}
-
-		return output;
 	}
 
 	/**
-	 * Binds a on key down and on key up callback to a key or key combo. Accepts a string containing the name of each
-	 * key you want to bind to comma separated. If you want to bind a combo the use the plus sign to link keys together.
-	 * Example: 'ctrl + x, ctrl + c' Will fire if Control and x or y are pressed at the same time.
-	 * @param keyCombo
-	 * @param callback
-	 * @param endCallback
+	 * Removes bindings that are no longer satisfied by the active keys. Also
+	 *  fires the key up callbacks.
+	 * @param  {KeyboardEvent}	event
 	 */
-	function bindKey(keyCombo, callback, endCallback) {
-
-		function clear() {
-			if(keys && keys.length) {
-				var keyBindingGroup = keyBindingGroups[keys.length];
-
-				if(keyBindingGroup.indexOf(keyBinding) > -1) {
-					var index = keyBindingGroups[keys.length].indexOf(keyBinding);
-					keyBindingGroups[keys.length].splice(index, 1);
+	function pruneBindings(event) {
+		var bI, cI, binding, killEventBubble;
+		for(bI = 0; bI < activeBindings.length; bI += 1) {
+			binding = activeBindings[bI];
+			if(isSatisfiedCombo(binding.keyCombo) === false) {
+				for(cI = 0; cI < binding.keyUpCallback.length; cI += 1) {
+					if (binding.keyUpCallback[cI](event, getActiveKeys(), binding.keyCombo) === false) {
+						killEventBubble = true;
+					}
+				}
+				if(killEventBubble === true) {
+					event.preventDefault();
+					event.stopPropagation();
 				}
+				activeBindings.splice(bI, 1);
+				bI -= 1;
 			}
 		}
+	}
 
-		//create an array of combos from the first argument
-		var bindSets = keyCombo.toLowerCase().replace(/\s/g, '').split(',');
-
-		//create a binding for each key combo
-		for(var i = 0; i < bindSets.length; i += 1) {
-
-			//split up the keys
-			var keys = bindSets[i].split('+');
-
-			//if there are keys in the current combo
-			if(keys.length) {
-				if(!keyBindingGroups[keys.length]) { keyBindingGroups[keys.length] = []; }
 
-				//define the
-				var keyBinding = {
-					"callback": callback,
-					"endCallback": endCallback,
-					"keyCombo": bindSets[i],
-					"keys": keys
-				};
+	///////////////////
+	// COMBO STRINGS //
+	///////////////////
 
-				//save the binding sorted by length
-				keyBindingGroups[keys.length].push(keyBinding);
+	/**
+	 * Compares two key combos returning true when they are functionally
+	 *  equivalent.
+	 * @param  {String}	keyComboArrayA keyCombo A key combo string or array.
+	 * @param  {String}	keyComboArrayB keyCombo A key combo string or array.
+	 * @return {Boolean}
+	 */
+	function compareCombos(keyComboArrayA, keyComboArrayB) {
+		var cI, sI, kI;
+		keyComboArrayA = parseKeyCombo(keyComboArrayA);
+		keyComboArrayB = parseKeyCombo(keyComboArrayB);
+		if(keyComboArrayA.length !== keyComboArrayB.length) { return false; }
+		for(cI = 0; cI < keyComboArrayA.length; cI += 1) {
+			if(keyComboArrayA[aI].length !== keyComboArrayB[aI].length) { return false; }
+			for(sI = 0; sI < keyComboArrayA[aI].length; sI += 1) {
+				if(keyComboArrayA[aI][sI].length !== keyComboArrayB[aI][sI].length) { return false; }
+				for(kI = 0; kI < keyComboArrayA[aI][sI].length; kI += 1) {
+					if(keyComboArrayB[aI][sI].indexOf(keyComboArrayA[aI][sI][kI]) === -1) { return false; }
+				}
 			}
 		}
-
-		return {
-			"clear": clear
-		}
+		return true;
 	}
 
 	/**
-	 * Binds keys or key combos to an axis. The keys should be in the following order; up, down, left, right. If any
-	 * of the the binded key or key combos are active the callback will fire. The callback will be passed an array
-	 * containing two numbers. The first represents x and the second represents y. Both have a possible range of -1,
-	 * 0, or 1 depending on the axis direction.
-	 * @param up
-	 * @param down
-	 * @param left
-	 * @param right
-	 * @param callback
+	 * Checks to see if a key combo string or key array is satisfied by the
+	 *  currently active keys. It does not take into account spent keys.
+	 * @param  {String}	keyCombo	A key combo string or array.
+	 * @return {Boolean}
 	 */
-	function bindAxis(up, down, left, right, callback) {
-
-		function clear() {
-			if(typeof clearUp === 'function') { clearUp(); }
-			if(typeof clearDown === 'function') { clearDown(); }
-			if(typeof clearLeft === 'function') { clearLeft(); }
-			if(typeof clearRight === 'function') { clearRight(); }
-			if(typeof timer === 'function') { clearInterval(timer); }
+	function isSatisfiedCombo(keyCombo) {
+		var cI, sI, stage, kI, stageOffset = 0, index, comboMatches;
+		keyCombo = parseKeyCombo(keyCombo);
+		for(cI = 0; cI < keyCombo.length; cI += 1) {
+			comboMatches = true;
+			stageOffset = 0;
+			for(sI = 0; sI < keyCombo[cI].length; sI += 1) {
+				stage = [].concat(keyCombo[cI][sI]);
+				for(kI = stageOffset; kI < activeKeys.length; kI += 1) {
+					index = stage.indexOf(activeKeys[kI]);
+					if(index > -1) {
+						stage.splice(index, 1);
+						stageOffset = kI;
+					}
+				}
+				if(stage.length !== 0) { comboMatches = false; break; }
+			}
+			if(comboMatches) { return true; }
 		}
+		return false;
+	}
 
-		var axis = [0, 0];
-
-		if(typeof callback !== 'function') {
-			return false;
+	/**
+	 * Accepts a key combo array or string and returns a flat array containing all keys referenced by
+	 * the key combo.
+	 * @param  {String}	keyCombo	A key combo string or array.
+	 * @return {Array}
+	 */
+	function extractComboKeys(keyCombo) {
+		var cI, sI, kI, keys = [];
+		keyCombo = parseKeyCombo(keyCombo);
+		for(cI = 0; cI < keyCombo.length; cI += 1) {
+			for(sI = 0; sI < keyCombo[cI].length; sI += 1) {
+				keys = keys.concat(keyCombo[cI][sI]);
+			}
 		}
+		return keys;
+	}
 
-		//up
-		var clearUp = bindKey(up, function () {
-			if(axis[0] === 0) {
-				axis[0] = -1;
-			}
-		}, function() {
-			axis[0] = 0;
-		}).clear;
-
-		//down
-		var clearDown = bindKey(down, function () {
-			if(axis[0] === 0) {
-				axis[0] = 1;
-			}
-		}, function() {
-			axis[0] = 0;
-		}).clear;
-
-		//left
-		var clearLeft = bindKey(left, function () {
-			if(axis[1] === 0) {
-				axis[1] = -1;
-			}
-		}, function() {
-			axis[1] = 0;
-		}).clear;
-
-		//right
-		var clearRight = bindKey(right, function () {
-			if(axis[1] === 0) {
-				axis[1] = 1;
+	/**
+	 * Parses a key combo string into a 3 dimensional array.
+	 * - Level 1 - sub combos.
+	 * - Level 2 - combo stages. A stage is a set of key name pairs that must
+	 *  be satisfied in the order they are defined.
+	 * - Level 3 - each key name to the stage.
+	 * @param  {String|Array}	keyCombo	A key combo string.
+	 * @return {Array}
+	 */
+	function parseKeyCombo(keyCombo) {
+		var s = keyCombo, i = 0, op = 0, ws = false, nc = false, combos = [], combo = [], stage = [], key = '';
+
+		if(typeof keyCombo === 'object' && typeof keyCombo.push === 'function') { return keyCombo; }
+		if(typeof keyCombo !== 'string') { throw new Error('Cannot parse "keyCombo" because its type is "' + (typeof keyCombo) + '". It must be a "string".'); }
+
+		//remove leading whitespace
+		while(s.charAt(i) === ' ') { i += 1; }
+		while(true) {
+			if(s.charAt(i) === ' ') {
+				//white space & next combo op
+				while(s.charAt(i) === ' ') { i += 1; }
+				ws = true;
+			} else if(s.charAt(i) === ',') {
+				if(op || nc) { throw new Error('Failed to parse key combo. Unexpected , at character index ' + i + '.'); }
+				nc = true;
+				i += 1;
+			} else if(s.charAt(i) === '+') {
+				//next key
+				if(key.length) { stage.push(key); key = ''; }
+				if(op || nc) { throw new Error('Failed to parse key combo. Unexpected + at character index ' + i + '.'); }
+				op = true;
+				i += 1;
+			} else if(s.charAt(i) === '>') {
+				//next stage op
+				if(key.length) { stage.push(key); key = ''; }
+				if(stage.length) { combo.push(stage); stage = []; }
+				if(op || nc) { throw new Error('Failed to parse key combo. Unexpected > at character index ' + i + '.'); }
+				op = true;
+				i += 1;
+			} else if(i < s.length - 1 && s.charAt(i) === '!' && (s.charAt(i + 1) === '>' || s.charAt(i + 1) === ',' || s.charAt(i + 1) === '+')) {
+				key += s.charAt(i + 1);
+				op = false;
+				ws = false;
+				nc = false;
+				i += 2;
+			} else if(i < s.length && s.charAt(i) !== '+' && s.charAt(i) !== '>' && s.charAt(i) !== ',' && s.charAt(i) !== ' ') {
+				//end combo
+				if(op === false && ws === true || nc === true) {
+					if(key.length) { stage.push(key); key = ''; }
+					if(stage.length) { combo.push(stage); stage = []; }
+					if(combo.length) { combos.push(combo); combo = []; }
+				}
+				op = false;
+				ws = false;
+				nc = false;
+				//key
+				while(i < s.length && s.charAt(i) !== '+' && s.charAt(i) !== '>' && s.charAt(i) !== ',' && s.charAt(i) !== ' ') {
+					key += s.charAt(i);
+					i += 1;
+				}
+			} else {
+				//unknown char
+				i += 1;
+				continue;
 			}
-		}, function() {
-			axis[1] = 0;
-		}).clear;
-
-		var timer = setInterval(function(){
-
-			//NO CHANGE
-			if(axis[0] === 0 && axis[1] === 0) {
-				return;
+			//end of combos string
+			if(i >= s.length) {
+				if(key.length) { stage.push(key); key = ''; }
+				if(stage.length) { combo.push(stage); stage = []; }
+				if(combo.length) { combos.push(combo); combo = []; }
+				break;
 			}
-
-			//run the callback
-			callback(axis);
-
-		}, 1);
-
-		return {
-			"clear": clear
 		}
+		return combos;
 	}
 
 	/**
-	 * Clears all key and key combo binds containing a given key or keys.
-	 * @param keys
+	 * Stringifys a key combo.
+	 * @param  {Array|String}	keyComboArray	A key combo array. If a key
+	 *  combo string is given it will be returned.
+	 * @return {String}
 	 */
-	function unbindKey(keys) {
-
-		if(keys === 'all') {
-			keyBindingGroups = [];
-			return;
+	function stringifyKeyCombo(keyComboArray) {
+		var cI, ccI, output = [];
+		if(typeof keyComboArray === 'string') { return keyComboArray; }
+		if(typeof keyComboArray !== 'object' || typeof keyComboArray.push !== 'function') { throw new Error('Cannot stringify key combo.'); }
+		for(cI = 0; cI < keyComboArray.length; cI += 1) {
+			output[cI] = [];
+			for(ccI = 0; ccI < keyComboArray[cI].length; ccI += 1) {
+				output[cI][ccI] = keyComboArray[cI][ccI].join(' + ');
+			}
+			output[cI] = output[cI].join(' > ');
 		}
+		return output.join(' ');
+	}
 
-		keys = keys.replace(/\s/g, '').split(',');
-
-		//loop through the key binding groups.
-		for(var iKCL = keyBindingGroups.length; iKCL > -1; iKCL -= 1) {
-			if(keyBindingGroups[iKCL]) {
-				var KeyBindingGroup = keyBindingGroups[iKCL];
-
-				//loop through the key bindings.
-				for(var iB = 0; iB < KeyBindingGroup.length; iB += 1) {
-					var keyBinding = KeyBindingGroup[iB],
-						remove = false;
 
-					//loop through the current key binding keys.
-					for(var iKB = 0; iKB < keyBinding.keys.length;  iKB += 1) {
-						var key = keyBinding.keys[iKB];
+	/////////////////
+	// ACTIVE KEYS //
+	/////////////////
 
-						//loop through the keys to be removed
-						for(var iKR = 0; iKR < keys.length; iKR += 1) {
-							var keyToRemove = keys[iKR];
-							if(keyToRemove === key) {
-								remove = true;
-								break;
-							}
-						}
-						if(remove) { break; }
-					}
-					if(remove) {
-						keyBindingGroups[iKCL].splice(iB, 1); iB -= 1;
-						if(keyBindingGroups[iKCL].length < 1) {
-							delete keyBindingGroups[iKCL];
-						}
-					}
-				}
-			}
-		}
+	/**
+	 * Returns the a copy of the active keys array.
+	 * @return {Array}
+	 */
+	function getActiveKeys() {
+		return [].concat(activeKeys);
 	}
 
 	/**
-	 * Gets an array of active keys
+	 * Adds a key to the active keys array, but only if it has not already been
+	 *  added.
+	 * @param {String}	keyName	The key name string.
 	 */
-	function getActiveKeys() {
-		return activeKeys;
+	function addActiveKey(keyName) {
+		if(keyName.match(/\s/)) { throw new Error('Cannot add key name ' + keyName + ' to active keys because it contains whitespace.'); }
+		if(activeKeys.indexOf(keyName) > -1) { return; }
+		activeKeys.push(keyName);
 	}
 
 	/**
-	 * Adds a new keyboard local not supported by keyboard JS
-	 * @param local
-	 * @param keys
+	 * Removes a key from the active keys array.
+	 * @param  {String}	keyNames	The key name string.
 	 */
-	function addLocale(local, keys) {
-		locals[local] = keys;
+	function removeActiveKey(keyName) {
+		var keyCode = getKeyCode(keyName);
+		if(keyCode === '91' || keyCode === '92') { activeKeys = []; } //remove all key on release of super.
+		else { activeKeys.splice(activeKeys.indexOf(keyName), 1); }
 	}
 
+
+	/////////////
+	// LOCALES //
+	/////////////
+
 	/**
-	 * Changes the keyboard local
-	 * @param local
+	 * Registers a new locale. This is useful if you would like to add support for a new keyboard layout. It could also be useful for
+	 * alternative key names. For example if you program games you could create a locale for your key mappings. Instead of key 65 mapped
+	 * to 'a' you could map it to 'jump'.
+	 * @param  {String}	localeName	The name of the new locale.
+	 * @param  {Object}	localeMap	The locale map.
 	 */
-	function setLocale(local) {
-		if(locals[local]) {
-			keys = locals[local];
-		}
+	function registerLocale(localeName, localeMap) {
+
+		//validate arguments
+		if(typeof localeName !== 'string') { throw new Error('Cannot register new locale. The locale name must be a string.'); }
+		if(typeof localeMap !== 'object') { throw new Error('Cannot register ' + localeName + ' locale. The locale map must be an object.'); }
+		if(typeof localeMap.map !== 'object') { throw new Error('Cannot register ' + localeName + ' locale. The locale map is invalid.'); }
 
+		//stash the locale
+		if(!localeMap.macros) { localeMap.macros = []; }
+		locales[localeName] = localeMap;
 	}
 
-	return {
-		"bind": {
-			"key": bindKey,
-			"axis": bindAxis
-		},
-		"activeKeys": getActiveKeys,
-		"unbind": {
-			"key": unbindKey
-		},
-		"locale": {
-			"add": addLocale,
-			"set": setLocale
+	/**
+	 * Swaps the current locale.
+	 * @param  {String}	localeName	The locale to activate.
+	 * @return {Object}
+	 */
+	function getSetLocale(localeName) {
+
+		//if a new locale is given then set it
+		if(localeName) {
+			if(typeof localeName !== 'string') { throw new Error('Cannot set locale. The locale name must be a string.'); }
+			if(!locales[localeName]) { throw new Error('Cannot set locale to ' + localeName + ' because it does not exist. If you would like to submit a ' + localeName + ' locale map for KeyboardJS please submit it at https://github.com/RobertWHurst/KeyboardJS/issues.'); }
+
+			//set the current map and macros
+			map = locales[localeName].map;
+			macros = locales[localeName].macros;
+
+			//set the current locale
+			locale = localeName;
 		}
+
+		//return the current locale
+		return locale;
 	}
-}));
+});