Improve state/chord handling and clean up namespace0.6.5

Some values that can never, ever, change were held in local
variables, rather than in PROGMEM. Fixed.

Change "pressed" to a signed int so the test for < 0 makes
sense, and to avoid possible weird failure modes in the
case where a key release comes in when pressed is already
zero. (Shouldn't happen, sure, but computers are weird.)

A lot of things in process_steno had external linkage for no
particular reason. They've been marked static. Stuff still
builds.

Distinguish between currently-held keys and keys that have
been held, and expose these values through a nicely-named API
so other code could, say, check on the current set of steno
chording in order to make displays. Also in passing fix up the
"state" value having external linkage so it could clash with
other people's variable declarations.

The API also provides hooks for key processing and steno chord
events, so you can monitor those events without having to
run in matrix_scan_user and recheck the values directly. Also
document these.

There is no path through processing a key that doesn't
end with a return false, so the nested return foo() are
gone and we just return false.

3 files changed, 115 insertions, 49 deletions

diff --git a/docs/feature_stenography.md b/docs/feature_stenography.md
index 9fb224b5da..0b2c82422b 100644
--- a/docs/feature_stenography.md
+++ b/docs/feature_stenography.md
@@ -56,6 +56,29 @@ On the display tab click 'Open stroke display'. With Plover disabled you should
 * [Steno Jig](https://joshuagrams.github.io/steno-jig/)
 * More resources at the Plover [Learning Stenography](https://github.com/openstenoproject/plover/wiki/Learning-Stenography) wiki
 
+## Interfacing with the code
+
+The steno code has three interceptible hooks. If you define these functions, they will be called at certain points in processing; if they return true, processing continues, otherwise it's assumed you handled things.
+
+```C
+bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[6]);
+```
+
+This function is called when a chord is about to be sent. Mode will be one of `STENO_MODE_BOLT` or `STENO_MODE_GEMINI`. This represents the actual chord that would be sent via whichever protocol. You can modify the chord provided to alter what gets sent. Remember to return true if you want the regular sending process to happen.
+
+```C
+bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; }
+```
+
+This function is called when a keypress has come in, before it is processed. The keycode should be one of `QK_STENO_BOLT`, `QK_STENO_GEMINI`, or one of the `STN_*` key values.
+
+```C
+bool postprocess_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed);
+```
+
+This function is called after a key has been processed, but before any decision about whether or not to send a chord. If `IS_PRESSED(record->event)` is false, and `pressed` is 0 or 1, the chord will be sent shortly, but has not yet been sent. This is where to put hooks for things like, say, live displays of steno chords or keys.
+
+
 ## Keycode Reference
 
 As defined in `keymap_steno.h`.
@@ -106,3 +129,4 @@ As defined in `keymap_steno.h`.
 |`STN_RES1`||(GeminiPR only)|
 |`STN_RES2`||(GeminiPR only)|
 |`STN_PWR`||(GeminiPR only)|
+
diff --git a/quantum/process_keycode/process_steno.c b/quantum/process_keycode/process_steno.c
index 16bbf154fd..3051fade91 100644
--- a/quantum/process_keycode/process_steno.c
+++ b/quantum/process_keycode/process_steno.c
@@ -18,6 +18,7 @@
 #include "eeprom.h"
 #include "keymap_steno.h"
 #include "virtser.h"
+#include <string.h>
 
 // TxBolt Codes
 #define TXB_NUL 0
@@ -57,11 +58,12 @@
 #define GEMINI_STATE_SIZE 6
 #define MAX_STATE_SIZE GEMINI_STATE_SIZE
 
-uint8_t state[MAX_STATE_SIZE] = {0};
-uint8_t pressed = 0;
-steno_mode_t mode;
+static uint8_t state[MAX_STATE_SIZE] = {0};
+static uint8_t chord[MAX_STATE_SIZE] = {0};
+static int8_t pressed = 0;
+static steno_mode_t mode;
 
-uint8_t boltmap[64] = {
+static const uint8_t boltmap[64] PROGMEM = {
   TXB_NUL, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM,
   TXB_S_L, TXB_S_L, TXB_T_L, TXB_K_L, TXB_P_L, TXB_W_L, TXB_H_L,
   TXB_R_L, TXB_A_L, TXB_O_L, TXB_STR, TXB_STR, TXB_NUL, TXB_NUL,
@@ -70,8 +72,17 @@ uint8_t boltmap[64] = {
   TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_NUM, TXB_Z_R
 };
 
-void steno_clear_state(void) {
-  __builtin_memset(state, 0, sizeof(state));
+static void steno_clear_state(void) {
+  memset(state, 0, sizeof(state));
+  memset(chord, 0, sizeof(chord));
+}
+
+static void send_steno_state(uint8_t size, bool send_empty) {
+  for (uint8_t i = 0; i < size; ++i) {
+    if (chord[i] || send_empty) {
+      virtser_send(chord[i]);
+    }
+  }
 }
 
 void steno_init() {
@@ -87,79 +98,108 @@ void steno_set_mode(steno_mode_t new_mode) {
   eeprom_update_byte(EECONFIG_STENOMODE, mode);
 }
 
-void send_steno_state(uint8_t size, bool send_empty) {
-  for (uint8_t i = 0; i < size; ++i) {
-    if (state[i] || send_empty) {
-      virtser_send(state[i]);
+/* override to intercept chords right before they get sent.
+ * return zero to suppress normal sending behavior.
+ */
+__attribute__ ((weak))
+bool send_steno_chord_user(steno_mode_t mode, uint8_t chord[6]) { return true; }
+
+__attribute__ ((weak))
+bool postprocess_steno_user(uint16_t keycode, keyrecord_t *record, steno_mode_t mode, uint8_t chord[6], int8_t pressed) { return true; }
+
+__attribute__ ((weak))
+bool process_steno_user(uint16_t keycode, keyrecord_t *record) { return true; }
+
+static void send_steno_chord(void) {
+  if (send_steno_chord_user(mode, chord)) {
+    switch(mode) {
+      case STENO_MODE_BOLT:
+	send_steno_state(BOLT_STATE_SIZE, false);
+	virtser_send(0); // terminating byte
+	break;
+      case STENO_MODE_GEMINI:
+	chord[0] |= 0x80; // Indicate start of packet
+	send_steno_state(GEMINI_STATE_SIZE, true);
+	break;
     }
   }
   steno_clear_state();
 }
 
-bool update_state_bolt(uint8_t key) {
-  uint8_t boltcode = boltmap[key];
-  state[TXB_GET_GROUP(boltcode)] |= boltcode;
-  return false;
+uint8_t *steno_get_state(void) {
+  return &state[0];
 }
 
-bool send_state_bolt(void) {
-  send_steno_state(BOLT_STATE_SIZE, false);
-  virtser_send(0); // terminating byte
-  return false;
+uint8_t *steno_get_chord(void) {
+  return &chord[0];
 }
 
-bool update_state_gemini(uint8_t key) {
-  state[key / 7] |= 1 << (6 - (key % 7));
+static bool update_state_bolt(uint8_t key, bool press) {
+  uint8_t boltcode = pgm_read_byte(boltmap + key);
+  if (press) {
+    state[TXB_GET_GROUP(boltcode)] |= boltcode;
+    chord[TXB_GET_GROUP(boltcode)] |= boltcode;
+  } else {
+    state[TXB_GET_GROUP(boltcode)] &= ~boltcode;
+  }
   return false;
 }
 
-bool send_state_gemini(void) {
-  state[0] |= 0x80; // Indicate start of packet
-  send_steno_state(GEMINI_STATE_SIZE, true);
+static bool update_state_gemini(uint8_t key, bool press) {
+  int idx = key / 7;
+  uint8_t bit = 1 << (6 - (key % 7));
+  if (press) {
+    state[idx] |= bit;
+    chord[idx] |= bit;
+  } else {
+    state[idx] &= ~bit;
+  }
   return false;
 }
 
 bool process_steno(uint16_t keycode, keyrecord_t *record) {
   switch (keycode) {
     case QK_STENO_BOLT:
+      if (!process_steno_user(keycode, record)) {
+	return false;
+      }
       if (IS_PRESSED(record->event)) {
         steno_set_mode(STENO_MODE_BOLT);
       }
       return false;
 
     case QK_STENO_GEMINI:
+      if (!process_steno_user(keycode, record)) {
+	return false;
+      }
       if (IS_PRESSED(record->event)) {
         steno_set_mode(STENO_MODE_GEMINI);
       }
       return false;
 
     case STN__MIN...STN__MAX:
-      if (IS_PRESSED(record->event)) {
-        uint8_t key = keycode - QK_STENO;
-        ++pressed;
-        switch(mode) {
-          case STENO_MODE_BOLT:
-            return update_state_bolt(key);
-          case STENO_MODE_GEMINI:
-            return update_state_gemini(key);
-          default:
-            return false;
-        }
-      } else {
-        --pressed;
-        if (pressed <= 0) {
-          pressed = 0;
-          switch(mode) {
-            case STENO_MODE_BOLT:
-              return send_state_bolt();
-            case STENO_MODE_GEMINI:
-              return send_state_gemini();
-            default:
-              return false;
-          }
-        }
+      if (!process_steno_user(keycode, record)) {
+	return false;
       }
-
+      switch(mode) {
+	case STENO_MODE_BOLT:
+	  update_state_bolt(keycode - QK_STENO, IS_PRESSED(record->event));
+	case STENO_MODE_GEMINI:
+	  update_state_gemini(keycode - QK_STENO, IS_PRESSED(record->event));
+      }
+      // allow postprocessing hooks
+      if (postprocess_steno_user(keycode, record, mode, chord, pressed)) {
+	if (IS_PRESSED(record->event)) {
+	  ++pressed;
+	} else {
+	  --pressed;
+	  if (pressed <= 0) {
+	    pressed = 0;
+	    send_steno_chord();
+	  }
+	}
+      }
+      return false;
   }
   return true;
 }
diff --git a/quantum/process_keycode/process_steno.h b/quantum/process_keycode/process_steno.h
index 3bbcbeaaf8..71f9731224 100644
--- a/quantum/process_keycode/process_steno.h
+++ b/quantum/process_keycode/process_steno.h
@@ -27,5 +27,7 @@ typedef enum { STENO_MODE_BOLT, STENO_MODE_GEMINI } steno_mode_t;
 bool process_steno(uint16_t keycode, keyrecord_t *record);
 void steno_init(void);
 void steno_set_mode(steno_mode_t mode);
+uint8_t *steno_get_state(void);
+uint8_t *steno_get_chord(void);
 
-#endif
\ No newline at end of file
+#endif