TERMKEY_INTERPRET_CSI(3)

💖 TERMKEY_INTERPRET_CSI(3) 💖

okay bestie, gather round, because this one is from the Library Functions Manual and it's lowkey one of the most useful little gremlins in the whole termkey family. it's termkey_interpret_csi, and it's here to decode the weirdo escape sequences that termkey was like "idk what this is" about. 🦋

✨ NAME ✨

termkey_interpret_csi — interpret unrecognised CSI sequence

🌸 SYNOPSIS 🌸

#include <termkey.h>

TermKeyResult termkey_interpret_csi(TermKey *tk, const TermKeyKey *key,
    long *args[], size_t *nargs, unsigned long *cmd);

Link with -ltermkey.

🎀 DESCRIPTION 🎀

so here's the tea, bestie. termkey_interpret_csi() fills in the variables behind the pointers you passed, based on the unrecognised CSI sequence event chillin' inside key. 🫶

you should call it when termkey_getkey(3) or one of its little friends hands you back a key event whose type is TERMKEY_TYPE_UNKNOWN_CSI.

⚠️ okay this part is IMPORTANT, like, do-not-skip-it important: you gotta call this function as soon as possible after you get a TERMKEY_TYPE_CSI key event. specifically, before you call termkey_getkey() or termkey_waitkey() again, because the next call will straight-up overwrite the buffer space that's currently holding this sequence. 💀 and then your sequence is gone. poof. not iconic.

now, the deets:

• the args array gets filled with the numerical arguments of the CSI sequence 📊
• the number of elements available in that array should be given as the initial value of the thing pointed to by nargs — and when the function returns, that value gets adjusted to tell you how many arguments were actually found. so it's like a lil in-and-out situation. cute.
• the cmd variable will contain the CSI command value 👑

and here's the fun bit, the byte math:

• if a leading byte was found (like '?') then it gets bitwise-ored with the command value, shifted up by 8 bits ✨
• if an intermediate byte was found (like '$') then it gets bitwise-ored with the command value, shifted up by 16 bits ✨

which, in code, is exactly this, no cap:

*cmd = command | (initial << 8) | (intermediate << 16);

💅 RETURN VALUE 💅

if you passed it a key event of the type TERMKEY_TYPE_UNKNOWN_CSI, this function returns TERMKEY_RES_KEY, and it'll mess with the variables whose pointers you handed over, exactly like we described above. slay. 🎉

for other event types? it returns TERMKEY_RES_NONE, and its effects on any of those pointer-variables are undefined. 🙈 which is a fancy way of saying: don't do that, bestie, we can't help you there.

🌈 SEE ALSO 🌈

• termkey_waitkey(3)
• termkey_getkey(3)
• termkey(7)

and that's the whole page, mwah 💋 — brought to you by the Library Functions Manual, starring TERMKEY_INTERPRET_CSI(3) herself. no date on this one, she's simply timeless. 👑