Change to be an extension

docs/config_and_keymap.md

@@ -2,9 +2,9 @@
 
 KMK is configured through a rather large plain-old-Python class called
 `KMKKeyboard`. Subclasses of this configuration exist which pre-fill defaults
-for various known keyboards (for example, many QMK, TMK, or ZMK keyboards
+for various known keyboards (for example, many QMK, TMK, or ZMK keyboards 
-are supported with a nice!nano, or through our ItsyBitsy to Pro Micro pinout adapter.
+are supported with a nice!nano, or through our ItsyBitsy to Pro Micro pinout adapter. 
-This class is the main interface between end users and the inner workings of KMK.
+This class is the main interface between end users and the inner workings of KMK. 
 Let's dive in!
 
 - Edit or create a file called `main.py` on your `CIRCUITPY` drive. You can also
@@ -73,13 +73,6 @@ print(dir(board))
 keyboard.keymap = [[KC.A, KC.B]]
 ```
 
-- You can also define the keymap with strings. They get replaced with `Key` objects
-  when the keyboard is started:
-
-```python
-keyboard.keymap = [['A', 'B']]
-```
-
 You can further define a bunch of other stuff:
 
 - `keyboard.debug_enabled` which will spew a ton of debugging information to the serial

docs/extension_keymap_string_keynames.md

@@ -0,0 +1,29 @@
+# Keymap String KeyNames
+
+Enables referring to keys by 'NAME' rather than KC.NAME.
+
+For example:
+
+```python
+from kmk.extensions.keymap_string_keynames import keymap_string_keynames
+
+# Normal
+# keyboard.keymap = [[ KC.A, KC.B, KC.RESET ]]
+
+# Indexed
+# keyboard.keymap = [[ KC['A'], KC['B'], KC['RESET'] ]]
+
+# String names
+keyboard.keymap = [[ 'A' , 'B', 'RESET' ]]
+
+keymap_string_keynames = keymap_string_keynames()
+
+# Enabling debug will show each replacement or failure.
+# This is recommended during the initial development of a keyboard.
+# keymap_string_keynames.debug_enable = True
+
+keyboard.extensions.append(keymap_string_keynames)
+```
+
+It should be noted that these are **not** ASCII. The string is **not** what
+will be sent to the computer. The examples above have no functional difference.

docs/extensions.md

@@ -1,9 +1,11 @@
 # Extensions
+
 Extensions add features that change the experience, but not the core features of
 the keyboard. They are meant to be easy to add, and create your own. These live in
 a sandbox to help prevent any bad code from crashing your keyboard.
 
 ## Core Extensions
+
 These extensions are provided in all builds and can be enabled. Currently offered
 extensions are
 
@@ -12,5 +14,6 @@ extensions are
 - [LockStatus](lock_status.md): Exposes host-side locks like caps or num lock.
 - [MediaKeys](media_keys.md): Adds support for media keys such as volume
 - [RGB](rgb.md): RGB lighting for underglow. Will work on most matrix RGB as will
-be treated the same as underglow.
+  be treated the same as underglow.
 - [Status LED](extension_statusled.md): Indicates which layer you are on with an array of single leds.
+- [KeyMap String KeyNames](extension_keymap_string_keynames): Enables referring to keys by 'NAME' rather than KC.NAME

docs/ptBR/config_and_keymap.md

@@ -19,11 +19,11 @@ mergulhar!
   ter problemas de corrupção. ou você pode estar em um dia ruim e apagar o
   arquivo errado.
 
-- Atribuir uma instância `KMKKeyboard` a uma variável, por exemplo,
+- Atribuir uma instância `KMKKeyboard` a uma variável, por exemplo, `keyboard =
-  `keyboard = KMKKeyboard()` (note os parênteses).
+  KMKKeyboard()` (note os parênteses).
 
 - Certificar-se quie esta instância de `KMKKeyboard` é realmente executada ao
-  fim do arquivo usando um bloco como este:
+fim do arquivo usando um bloco como este:
 
 ```python
 if __name__ == '__main__':
@@ -75,13 +75,6 @@ print(dir(board))
 keyboard.keymap = [[KC.A, KC.B]]
 ```
 
-- Você também pode definir o mapa de teclas com strings. Eles são substituídos por
-  `Key` objetos quando o teclado é iniciado:
-
-```python
-keyboard.keymap = [['A', 'B']]
-```
-
 Você pode definir um monte de outras coisas
 
 - `keyboard.debug_enabled` que vai atirar um monte de informação de depuração

kmk/extensions/keymap_string_keynames.py

@@ -0,0 +1,46 @@
+from kmk.extensions import Extension
+from kmk.keys import KC
+
+
+class keymap_string_keynames(Extension):
+    #####
+    # User-configurable
+    debug_enabled = False
+
+    def on_runtime_enable(self, keyboard):
+        return
+
+    def on_runtime_disable(self, keyboard):
+        return
+
+    def during_bootup(self, keyboard):
+        for _, layer in enumerate(keyboard.keymap):
+            for key_idx, key in enumerate(layer):
+                if isinstance(key, str):
+                    try:
+                        replacement = KC[key]
+                        layer[key_idx] = replacement
+                        if self.debug_enabled:
+                            print(f"Replacing '{key}' with {replacement}")
+                    except KeyError:
+                        layer[key_idx] = KC.NO
+                        if self.debug_enabled:
+                            print(f"Failed replacing '{key}'. Using KC.NO")
+
+    def before_matrix_scan(self, keyboard):
+        return
+
+    def after_matrix_scan(self, keyboard):
+        return
+
+    def before_hid_send(self, keyboard):
+        return
+
+    def after_hid_send(self, keyboard):
+        return
+
+    def on_powersave_enable(self, keyboard):
+        return
+
+    def on_powersave_disable(self, keyboard):
+        return

kmk/kmk_keyboard.py

@@ -293,15 +293,6 @@ class KMKKeyboard:
                 cm.extend(m.coord_mapping)
             self.coord_mapping = tuple(cm)
 
-    def _init_replace_strings_in_keymap_with_keys(self):
-        for _, layer in enumerate(self.keymap):
-            for key_idx, key in enumerate(layer):
-                if isinstance(key, str):
-                    replacement = KC[key]
-                    layer[key_idx] = replacement
-                    if self.debug_enabled:
-                        print(f"Replacing '{key}' with {replacement}")
-
     def _init_hid(self):
         if self.hid_type == HIDModes.NOOP:
             self._hid_helper = AbstractHID
@@ -484,7 +475,6 @@ class KMKKeyboard:
         self._init_sanity_check()
         self._init_hid()
         self._init_matrix()
-        self._init_replace_strings_in_keymap_with_keys()
         self._init_coord_mapping()
 
         for module in self.modules:

tests/keyboard_test.py

@@ -16,7 +16,12 @@ class DigitalInOut(Mock):
 
 class KeyboardTest:
     def __init__(
-        self, modules, keymap, keyboard_debug_enabled=False, debug_enabled=False
+        self,
+        modules,
+        keymap,
+        keyboard_debug_enabled=False,
+        debug_enabled=False,
+        extensions={},
     ):
         self.debug_enabled = debug_enabled
 
@@ -24,6 +29,7 @@ class KeyboardTest:
         self.keyboard.debug_enabled = keyboard_debug_enabled
 
         self.keyboard.modules = modules
+        self.keyboard.extensions = extensions
 
         self.pins = tuple(DigitalInOut() for k in keymap[0])
 

tests/test_kmk_extension_keymap_string_keynames.py

@@ -0,0 +1,25 @@
+import unittest
+
+from kmk.extensions.keymap_string_keynames import keymap_string_keynames
+from kmk.keys import KC
+from tests.keyboard_test import KeyboardTest
+
+
+class Test_extension_keymap_string_keynames(unittest.TestCase):
+    def test_basic_kmk_keyboard_replace_string_primary_name(self):
+        keyboard = KeyboardTest(
+            [], [['1', '2', '3', '4']], extensions={keymap_string_keynames()}
+        )
+
+        keyboard.test('Simple key press', [(0, True), (0, False)], [{KC.N1}, {}])
+
+    def test_basic_kmk_keyboard_replace_string_secondary_name(self):
+        keyboard = KeyboardTest(
+            [], [['N1', 'N2', 'N3', 'N4']], extensions={keymap_string_keynames()}
+        )
+
+        keyboard.test('Simple key press', [(0, True), (0, False)], [{KC.N1}, {}])
+
+
+if __name__ == '__main__':
+    unittest.main()

tests/test_kmk_keyboard.py

@@ -10,20 +10,6 @@ class TestKmkKeyboard(unittest.TestCase):
 
         keyboard.test('Simple key press', [(0, True), (0, False)], [{KC.N1}, {}])
 
-    def test_basic_kmk_keyboard_replace_string_primary_name(self):
-        keyboard = KeyboardTest([], [['1', '2', '3', '4']])
-
-        keyboard.test('Simple key press', [(0, True), (0, False)], [{KC.N1}, {}])
-
-    def test_basic_kmk_keyboard_replace_string_secondary_name(self):
-        keyboard = KeyboardTest([], [['N1', 'N2', 'N3', 'N4']])
-
-        keyboard.test('Simple key press', [(0, True), (0, False)], [{KC.N1}, {}])
-
-    def test_basic_kmk_keyboard_unknown_replacement_string(self):
-        with self.assertRaises(ValueError):
-            KeyboardTest([], [['UNKNOWN1', 'UNKNOWN2', 'UNKNOWN3', 'UNKNOWN4']])
-
 
 if __name__ == '__main__':
     unittest.main()