From edeec36ffac350bcb54786fac90e885b44595e84 Mon Sep 17 00:00:00 2001
From: Emile Clark-Boman <eclarkboman@gmail.com>
Date: Sun, 28 Sep 2025 22:35:28 +1000
Subject: [PATCH] add minimal ANSI reference

---
 src/ansi.h | 95 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 95 insertions(+)

diff --git a/src/ansi.h b/src/ansi.h
index 7cce8ab..cad2d2b 100644
--- a/src/ansi.h
+++ b/src/ansi.h
@@ -1,6 +1,101 @@
+/* ANSI Escape Sequence Macro Definitions
+ *
+ * - use `#define CT_RIGHTTOLEFT` to modify the behaviour
+ *   of ANSI_CMR[N(n)] and ANSI_CML[N(n)] if your application
+ *   can expect a Right-To-Left console (ie Arabic/Hebrew)
+ *   at compile time.
+ * TODO: implement a runtime dependent mode that checks the terminfo database
+ *
+ * REF: https://ansi.tools/lookup
+ */
 #ifndef CURSETREE_ANSI_H
 #define CURSETREE_ANSI_H
 
+/* Escape (ESC) C0 Control Codes:
+ *   \e    (C styled)
+ *   \x1B  (Hex)
+ *   \033  (Octal)
+ *
+ * Control Sequence Introducer (CSI):
+ *   \e[   (C styled)
+ *   \x9B  (Hex)
+ */
+/* TODO: try replace \e[ with \x9B */
+#define _ESC(code) "\033" #code
+#define _CSI(code) "\033[" #code
 
 
+/* MNEMONIC: (ALTernate/REGular) BUFfer
+ * \033[?1049l & \033[?1049h were introduce by xterm
+ * to enable and disable (respectively) an alternate
+ * screen buffer. This is how libraries like ncurses
+ * do their magic!!
+ * NOTE: \033[?1049h saves the cursor position and \033[?1049l
+ * NOTE: automatically restores it so you don't have to
+ */
+#define ANSI_ALTBUF _CSI(?1049h)
+#define ANSI_REGBUF _CSI(?1049l)
+
+/* MNEMONIC: Cursor Move (Up/Down/Forward/Back) N
+ * Move the cursor up(A) down(B) forward(C) back(D) by n chars
+ * WARNING: Forward/back are NOT always right/left (respectively),
+ * WARNING: specifically consider right-to-left languages like Arabic/Hebrew.
+ * TODO: rename these to ANSI_MV#N?
+ */
+#define ANSI_CMUN(n) _CSI(n ## A)
+#define ANSI_CMDN(n) _CSI(n ## B)
+#define ANSI_CMFN(n) _CSI(n ## C)
+#define ANSI_CMBN(n) _CSI(n ## D)
+/* MNEMONIC: Cursor Move (Up/Down/Forward/Back)
+ * Move the cursor up(A) down(B) forward(C) back(D) by 1 char
+ * NOTE: this escape sequence uses 1 less char (yippie)
+ */
+#define ANSI_CMU ANSI_CMUN()
+#define ANSI_CMD ANSI_CMDN()
+#define ANSI_CMF ANSI_CMFN()
+#define ANSI_FMB ANSI_CMBN()
+
+/* Cursetree uses CT_RIGHTTOLEFT to flag whether the application
+ * expects to be in a right-to-left (ie Arabic/Hebrew) configuration.
+ * NOTE: If your application needs to configure this at runtime
+ * NOTE: then you'll need to implement the functions yourself (simple).
+ */
+#ifdef CT_RIGHTOTLEFT
+# define ANSI_CMRN(n) ANSI_CMBN(n)
+# define ANSI_CMLN(n) ANSI_CMFN(n)
+#else
+# define ANSI_CMRN(n) ANSI_CMFN(n)
+# define ANSI_CMLN(n) ANSI_CMBN(n)
+#endif
+#define ANSI_CMR ANSI_CMRN()
+#define ANSI_CML ANSI_CMLN()
+
+/* MNEUMONIC:
+ * 
+ */
+#define ANSI_HOME _CSI(H)
+
+/* Scroll Screen Buffer Up/Down
+ * TODO: find better names for these */
+#define ANSI_BUFUN(n) _CSI(n ## S)
+#define ANSI_BUFU ANSI_BUFUN()
+#define ANSI_BUFDN(n) _CSI(n ## T)
+#define ANSI_BUFD ANSI_BUFDN()
+
+
+/* MNEMONIC: Cursor (SAVE/GOTO)
+ * Save/Restore(goto) cursor position & state in SCO/DEC console mode.
+ */
+#define ANSI_CSAVE_DEC _ESC(7)
+#define ANSI_CSAVE_SCO _CSI(s)
+#define ANSI_CSAVE ANSI_CSAVE_SCO
+#define ANSI_CGOTO_DEC _ESC(8)
+#define ANSI_CGOTO_SCO _CSI(u)
+#define ANSI_CGOTO ANSI_CGOTO_SCO
+/* MNEMONIC: Cursor SHOW/HIDE
+ * Enable/disable the cursor.
+ */
+#define ANSI_CSHOW _CSI(25h)
+#define ANSI_CHIDE _CSI(25l)
+
 #endif /* CURSETREE_ANSI_H */