diff --git a/doc/ctlseqs.texi b/doc/ctlseqs.texi index a376456..470fd2b 100644 --- a/doc/ctlseqs.texi +++ b/doc/ctlseqs.texi @@ -252,8 +252,6 @@ configure a matcher. @example struct ctlseqs_matcher *matcher /* = ... */; char const *patterns[] = @{ - CTLSEQS_XTVERSION(), - CTLSEQS_CUP(CTLSEQS_PH_NUM, CTLSEQS_PH_NUM), // ... @}; struct ctlseqs_matcher_options options = @{ @@ -280,6 +278,69 @@ invalid, function behaviour is undefined. See @ref{Patterns} for details. @node Patterns @subsection Patterns +The @code{patterns} field in @code{struct ctlseqs_matcher_options} is an array +of NUL-terminated strings which indicates the desired patterns of control +functions for the current matcher. + +@cindex Control functions supported by the matcher +The following types of control functions are recognizable by the matcher: + +@itemize @bullet +@item Control sequences: @code{CSI [param...] [intmd...] final} +@item C1 functions with command string: @code{(APC|DCS|OSC|PM) [cmdstr] ST} +@item Single shifts: @code{(SS2|SS3) ch} +@item SOS function: @code{SOS [chrstr] ST} +@end itemize + +According to ECMA-48, CSI parameter bytes are of range @code{0x30} to +@code{0x3f}, intermediate bytes @code{0x20} to @code{0x2f}, and final byte +@code{0x40} to @code{0x7e}. Command string consists of printable characters and +characters of range @code{0x08} and @code{0x0e}. Character string can be any +bit combination which does not represent @code{SOS} or @code{ST}. + +A supported control function, either verbatim or combined with placeholders, +can be specified as a valid pattern. The terminating @code{NUL} character does +not count into the pattern. + +@cindex List of supported placeholders +A placeholder can only take place in the @code{param}, @code{intmd}, +@code{cmdstr} or @code{chrstr} fields, and can be one of the following values: + +@itemize @bullet +@item @code{CTLSEQS_PH_NUM}: A single unsigned integer. +@item @code{CTLSEQS_PH_NUMS}: An unsigned integer indicating the number of +extracted values, followed by unsigned integers of that many. +@item @code{CTLSEQS_PH_STR}: An unsigned integer indicating the number of +characters of the extracted string, followed by a string of printable +characters. +@item @code{CTLSEQS_PH_CMDSTR}: An unsigned integer indicating the number of +characters of the extracted string, followed by a string containing only +printable characters and characters of range @code{0x08} to @code{0x0d}. +@item @code{CTLSEQS_PH_CSI_PARAM}: An unsigned integer indicating the number of +characters of the extracted string, followed by a string of CSI parameter +bytes. +@item @code{CTLSEQS_PH_CSI_INTMD}: An unsigned integer indicating the number of +characters of the extracted string, followed by a string of CSI intermediate +bytes. +@item @code{CTLSEQS_PH_HEXNUM}: A single unsigned integer, which is the integer +value of extracted hexadecimal string. +@item @code{CTLSEQS_PH_CHRSTR}: An unsigned integer indicating the number of +characters of the extracted string, followed by a string of any bit combination +which does not represent @code{SOS} or @code{ST}. +@end itemize + +@cindex Control sequence matcher pattern example +The following code is a valid example of patterns: + +@example +const char *patterns[] = @{ + CTLSEQS_XTVERSION(), + CTLSEQS_CUP(CTLSEQS_PH_NUM, CTLSEQS_PH_NUM), + CTLSEQS_DECRQM("1000"), + // ... +@}; +@end example + @node Matching String @section Matching String