Merge remote-tracking branch 'plugin/Ranges/f/monorepo' into f/monorepo-stage2

doc/plugin/Ranges.md

@@ -0,0 +1,39 @@
+# Kaleidoscope-Ranges
+
+## kaleidoscope::ranges enum
+
+This plugin defines the `ranges` enum that many plugins use.
+
+To explain its purpose, first a brief digression to explain how Kaleidoscope implements keys.
+
+Keys in Kaleidoscope are defined as follows:
+
+```c++
+// in Kaleidoscope/src/key_defs.h
+typedef union Key_ {
+
+  struct {
+    uint8_t keyCode;
+    uint8_t flags;
+  };
+  uint16_t raw;
+// bunch of operator overloads elided...
+} Key;
+```
+That is, a key is a 16-bit integer that, by default, has 8 bits for the keyCode and 8 bits for flags.
+For normal keypresses, this is straightforward: the 8-bit keyCode is the normal HID code corresponding to a normal keyboard key and the flags are used to indicate the modifiers being held.
+
+However, many plugins want to be able to make key presses do something special and need some way of indicating that a key is not just an ordinary key.
+To do this, we take advantage of the fact that our flags field is 8 bits, but there are only five normal modifiers (control, shift, GUI, right alt, and left alt).
+<!-- question: does bit six have any signicance? it seems to be unused
+--> Therefore, we can use a bit to indicate that something special is happening with a given key:
+In this case, by setting the high bit of the flags field, we indicate that this is a reserved key and isn't going to be interpreted normally.
+
+This way, a plugin can make a key be sent with the high bit of the flags field set, then it is free to use the rest of the 16 bits as it sees fit and be assured that it won't conflict with the built-in keys.
+
+However, there is a problem with this:
+Many plugins will want to do this, so how can they be sure that the key codes they make won't be interpreted by another plugin?
+Thus, we come to the purpose of this enum: 
+The `range` enum gives the ranges of possible raw key values that each plugin will use; by referring to it, plugins can be sure none of them will step on each others' toes.
+
+**In summary, the values in the enum here gives the possible raw keycode values that the various plugins will inject; if you're trying to make a plugin that will be injecting special key events, you should probably add yourself to the enum here.**

src/Kaleidoscope-Ranges.h

@@ -0,0 +1,56 @@
+/* -*- mode: c++ -*-
+ * Kaleidoscope-Ranges -- Common ranges, used by a number of Kaleidoscope plugins.
+ * Copyright (C) 2016, 2017  Keyboard.io, Inc
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License as published by the Free Software
+ * Foundation, version 3.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along with
+ * this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
+#pragma once
+
+namespace kaleidoscope {
+namespace ranges {
+
+enum : uint16_t {
+  FIRST       = 0xc000,
+  KALEIDOSCOPE_FIRST = FIRST,
+  OS_FIRST,
+  OSM_FIRST   = OS_FIRST,
+  OSM_LAST    = OSM_FIRST + 7,
+  OSL_FIRST,
+  OSL_LAST    = OSL_FIRST + 7,
+  OS_LAST     = OSL_LAST,
+  DU_FIRST,
+  DUM_FIRST   = DU_FIRST,
+  DUM_LAST    = DUM_FIRST + (8 << 8),
+  DUL_FIRST,
+  DUL_LAST    = DUL_FIRST + (8 << 8),
+  DU_LAST     = DUL_LAST,
+  TD_FIRST,
+  TD_LAST     = TD_FIRST + 15,
+  LEAD_FIRST,
+  LEAD_LAST   = LEAD_FIRST + 7,
+  CYCLE,
+  SYSTER,
+  TT_FIRST,
+  TT_LAST     = TT_FIRST + 255,
+  STENO_FIRST,
+  STENO_LAST  = STENO_FIRST + 42,
+  SC_FIRST,
+  SC_LAST,
+
+  SAFE_START,
+  KALEIDOSCOPE_SAFE_START = SAFE_START
+};
+
+}
+}