Return a real key type for unrecognised CSI sequences; allow accessing them by termkey_interpret_csi()

2 files changed, 30 insertions, 1 deletions

diff --git a/man/termkey.7 b/man/termkey.7
index bafa0b8..c96c4b4 100644
--- a/man/termkey.7
+++ b/man/termkey.7
@@ -51,7 +51,10 @@ a symbolic key. This value indicates that \fIcode.sym\fP is valid, and contains
 a mouse button press, release, or movement. The \fIcode.mouse\fP array should be considered opaque.
 .TP
 .B TERMKEY_TYPE_POSITION
-a cursor position report.
+a cursor position report. The structure should be considered opaque; \fBtermkey_interpret_position\fP(3) may be used to interpret it.
+.TP
+.B TERMKEY_TYPE_UNKNOWN_CSI
+an unrecognised CSI sequence. The structure should be considered opaque; \fBtermkey_interpret_csi\fP(3) may be used to interpret it.
 .PP
 The \fImodifiers\fP bitmask is composed of a bitwise-or of the constants \fBTERMKEY_KEYMOD_SHIFT\fP, \fBTERMKEY_KEYMOD_CTRL\fP and \fBTERMKEY_KEYMOD_ALT\fP.
 .PP
@@ -130,6 +133,8 @@ protocol (\f(CWCSI M\fP followed by three bytes),
 encoding (\f(CWCSI < ... M\fP, as requested by \f(CWCSI ? 1006 h\fP), and rxvt encoding (\f(CWCSI ... M\fP, as requested by \f(CWCSI ? 1015 h\fP). Which encoding is in use is inferred automatically by \fBtermkey\fP, and does not need to be specified explicitly.
 .SS Position Events
 The \fBTERMKEY_TYPE_POSITION\fP event type indicates a cursor position report. This is typically sent by a terminal in response to the Report Cursor Position command (\f(CWCSI 6 n\fP). The event bytes are opaque, but can be obtained by calling \fBtermkey_interpret_position\fP(3) passing the event structure and pointers to integers to store the result in.
+.SS Unrecognised CSIs
+The \fBTERMKEY_TYPE_UNKNOWN_CSI\fP event type indicates a CSI sequence that the \fBtermkey\fP does not recognise. It will have been extracted from the stream, but is available to the application to inspect by calling \fBtermkey_interpret_csi\fP(3). It is important that if the application wishes to inspect this sequence it is done immediately, before any other IO operations on the \fBtermkey\fP instance (specifically, before calling \fBtermkey_waitkey\fP() or \fBtermkey_getkey\fP() again), otherwise the buffer space consumed by the sequence will be overwritten.
 .SH "SEE ALSO"
 .BR termkey_new (3),
 .BR termkey_waitkey (3),
diff --git a/man/termkey_interpret_csi.3 b/man/termkey_interpret_csi.3
new file mode 100644
index 0000000..fa0444d
--- /dev/null
+++ b/man/termkey_interpret_csi.3
@@ -0,0 +1,24 @@
+.TH TERMKEY_INTERPRET_CSI 3
+.SH NAME
+termkey_interpret_csi \- interpret unrecognised CSI sequence
+.SH SYNOPSIS
+.nf
+.B #include <termkey.h>
+.sp
+.BI "TermKeyResult termkey_interpret_csi(TermKey *" tk ", const TermKeyKey *" key ", "
+.BI "    long *" args "[], size_t *" nargs ", unsigned long *" cmd );
+.fi
+.sp
+Link with \fI-ltermkey\fP.
+.SH DESCRIPTION
+\fBtermkey_interpret_csi\fP() fills in variables in the passed pointers according to the unrecognised CSI sequence event found in \fIkey\fP. It should be called if \fBtermkey_getkey\fP(3) or similar have returned a key event with the type of \fBTERMKEY_TYPE_UNKNOWN_CSI\fP. Note that it is important to call this function as soon as possible after obtaining a \fBTERMKEY_TYPE_CSI\fP key event; specifically, before calling \fBtermkey_getkey\fP() or \fBtermkey_waitkey\fP() again, as a subsequent call will overwrite the buffer space currently containing this sequence.
+.PP
+The \fIargs\fP array will be filled with the numerical arguments of the CSI sequence. The number of elements available in this array should be given as the initial value of the value pointed to by \fInargs\fP, which will be adjusted to give the number of arguments actually found when the function returns. The \fIcmd\fP variable will contain the CSI command value. If a leading byte was found (such as '\f(CW$\fP') then it will be bitwise-ored with the command value, shifted up by 8 bits.
+.SH "RETURN VALUE"
+If passed a \fIkey\fP event of the type \fBTERMKEY_TYPE_UNKNOWN_CSI\fP, this function will return \fBTERMKEY_RES_KEY\fP and will affect the variables whose pointers were passed in, as described above.
+.PP
+For other event types it will return \fBTERMKEY_RES_NONE\fP, and its effects on any variables whose pointers were passed in, are undefined.
+.SH "SEE ALSO"
+.BR termkey_waitkey (3),
+.BR termkey_getkey (3),
+.BR termkey (7)