Add manual for control sequence matcher patterns.

This commit is contained in:
CismonX 2021-03-02 20:33:09 +08:00
parent 5330196f6e
commit 85e40f6ceb
Signed by: cismonx
GPG Key ID: 3094873E29A482FB
1 changed files with 63 additions and 2 deletions

View File

@ -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