Implement Text Replacement module

docs/text_replacement.md

@@ -0,0 +1,34 @@
+# Text Replacement
+
+The Text Replacement module lets a user replace one typed sequence of characters with another.
+
+Potential uses:
+
+- Rudimentary auto-correct: replace `yuo` with `you`
+- Text expansion, à la [espanso](https://github.com/federico-terzi/espanso): when `:sig` is typed, replace it with `John Doe`, or turn `idk` into `I don't know`
+
+## Usage
+
+```python
+from kmk.modules.text_replacement import TextReplacement
+
+my_dictionary = {
+    'yuo': 'you',
+    ':sig': 'John Doe',
+    'idk': "I don't know"
+}
+text_replacement = TextReplacement(dictionary=my_dictionary)
+keyboard.modules.append(text_replacement)
+```
+
+### Recommendations
+
+1. Consider prefixing text expansion entries with a symbol to prevent accidental activations.
+2. If you want multiple similar replacements, consider adding a number to prevent unreachable matches: `replaceme1`, `replaceme2`, etc.
+
+### Limitations
+
+1. Since this runs on your keyboard, it is not context-aware. It can't tell if you are typing in a valid text field or not.
+2. In the interest of a responsive typing experience, the first valid match will be used as soon as it is found. If there is a dictionary entry named `abc` and another named `abcd`, the substitution for `abc` will be sent as soon as you type `abc` and the matching algorithm will reset before you type `d`.
+3. Like is the case with [Sequences](https://github.com/KMKfw/kmk_firmware/blob/master/docs/sequences.md) and [Dynamic Sequences](https://github.com/KMKfw/kmk_firmware/blob/master/docs/dynamic_sequences.md), characters are sent at a rate of 1 every 10 milliseconds. The replacement will not happen instantly.
+4. The text to be replaced is removed by sending backspace taps. As with the previous limitation, this happens at a rate of 1 tap every 10 milliseconds.