From 0ebc0054c41238de71d6f91ca208bd99dd80372f Mon Sep 17 00:00:00 2001 From: CismonX Date: Fri, 19 Mar 2021 20:58:33 +0800 Subject: [PATCH] Update documentation for matcher. --- doc/ctlseqs.texi | 56 +++++++++++++++++++++++++++++++++------------ man/ctlseqs_match.3 | 41 ++++++++++----------------------- 2 files changed, 53 insertions(+), 44 deletions(-) diff --git a/doc/ctlseqs.texi b/doc/ctlseqs.texi index d8919de..77ef13f 100644 --- a/doc/ctlseqs.texi +++ b/doc/ctlseqs.texi @@ -221,7 +221,7 @@ provided by ctlseqs. The @code{struct ctlseqs_matcher *} is a pointer to an opaque type which represents an instance of control sequence matcher. Before using, the matcher -should be initialized with @code{ctlseqs_matcher_init}. After using, it should +should be initialized with @code{ctlseqs_matcher_init}. After used, it should be deallocated with @code{ctlseqs_matcher_free}. @cindex Control sequence matcher initialization example @@ -267,8 +267,10 @@ the data generated from the last invocation. Upon success, the function returns @code{CTLSEQS_OK}. If the function fails to allocate enough memory, returns @code{CTLSEQS_NOMEM}. +@quotation Caution If the @code{patterns} field in @code{struct ctlseqs_matcher_options} is invalid, function behaviour is undefined. See @ref{Patterns} for details. +@end quotation @menu * Patterns:: Supported control squence pattern formats @@ -327,8 +329,8 @@ The following code is a valid example of patterns: @example const char *patterns[] = @{ - CTLSEQS_XTVERSION(), CTLSEQS_CUP(CTLSEQS_PH_NUM, CTLSEQS_PH_NUM), + CTLSEQS_XTVERSION(), CTLSEQS_DECRQM("1000"), // ... @}; @@ -342,17 +344,6 @@ Function @code{ctlseqs_match} matches a given character string to a matcher. The function accepts four arguments: the matcher, the string to match, length of the string to match, and a buffer which stores the match result. -The following code is an example of invoking @code{ctlseqs_match}: - -@example -struct ctlseqs_matcher *matcher /* = ... */; -// ... -char const *str = CTLSEQS_CUP("2", "4"); -size_t str_len = sizeof(CTLSEQS_CUP("2", "4")) - 1; -union ctlseqs_value buffer[4]; -ssize_t result = ctlseqs_match(matcher, str, str_len, buffer); -@end example - Before matching, a buffer which is large enough to store the match result should be allocated. The buffer is an array of @code{union ctlseqs_value}, whose definition is shown below: @@ -377,8 +368,43 @@ If @code{ctlseqs_match} fails to find any control functions, returns control function, the function returns @code{CTLSEQS_NOMATCH}. If the control function matches a pattern configured in the matcher, returns -the offset of the matched pattern, and store the extracted values to the result -buffer according to each of the placeholders, starting from offset 2. +the offset of the matched pattern, and stores the extracted values to the +result buffer according to each of the placeholders, starting from offset 2: + +@itemize @bullet +@item @code{CTLSEQS_PH_NUM}, @code{CTLSEQS_PH_HEXNUM}: The integer is stored in +field @code{num}. +@item @code{CTLSEQS_PH_NUMS}: The number of integers is stored in field +@code{len}, followed by that many integers stored in field @code{num}. +@item @code{CTLSEQS_PH_CSI_PARAM}, @code{CTLSEQS_PH_CSI_INTMD}, +@code{CTLSEQS_PH_STR}, @code{CTLSEQS_PH_CMDSTR}, @code{CTLSEQS_PH_CHRSTR}: The +length of the string is stored in field @code{len}, followed by a pointer to +the first character of the string stored in field @code{str}. +@end itemize + +The following code is an example of invoking @code{ctlseqs_match}: + +@example +struct ctlseqs_matcher *matcher /* = ... */; +// ... +union ctlseqs_value buffer[4]; +char const *str = "foo" CTLSEQS_CUP("2", "4"); +size_t str_len = sizeof("foo" CTLSEQS_CUP("2", "4")) - 1; +ssize_t result = ctlseqs_match(matcher, str, str_len, buffer); + +assert(result == 0); +assert(buffer[0].len == 6 && buffer[1].str == str + 3); +assert(buffer[2].num == 2 && buffer[3].num == 4); +@end example + +Function @code{ctlseqs_match} allows @code{NULL} value for argument +@code{matcher}, in which case it behaves like a matcher configured with zero +patterns is provided. + +@quotation Caution +If the given string can match multiple patterns in the matcher, it is +unspecified which of them will be the final match result. +@end quotation @node Control Sequence Reading diff --git a/man/ctlseqs_match.3 b/man/ctlseqs_match.3 index 002ccb4..df74e7d 100644 --- a/man/ctlseqs_match.3 +++ b/man/ctlseqs_match.3 @@ -37,7 +37,6 @@ at offset 0, and the pointer to the starting ESC character at offset 1. Otherwise, .I buffer value at offset 0 and 1 is unspecified. -. .SS Match results If the control sequence matches a pattern in .IR matcher , @@ -62,37 +61,21 @@ union ctlseqs_value { .PP A group can contain one or multiple values, depending on different placeholders: .TP -.B CTLSEQS_PH_NUM -A single unsigned integer. +.BR CTLSEQS_PH_NUM ", " CTLSEQS_PH_HEXNUM +The integer is stored in field +.IR num . .TP .B CTLSEQS_PH_NUMS -An unsigned integer indicating the number of extracted values, followed by unsigned integers of that many. +The number of integers is stored in field +.IR len , +followed by that many integers stored in field +.IR num . .TP -.B CTLSEQS_PH_STR -An unsigned integer indicating the number of characters of the extracted string, followed by a string of printable characters. -.TP -.B 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 0x08\(ti0x0d. -.TP -.B CTLSEQS_PH_CSI_PARAM -An unsigned integer indicating the number of characters of the extracted string, followed by a string of CSI parameter bytes (range 0x30\(ti0x3f). -.TP -.B CTLSEQS_PH_CSI_INTMD -An unsigned integer indicating the number of characters of the extracted string, followed by a string of CSI intermediate bytes (range 0x20\(ti0x2f). -.TP -.B CTLSEQS_PH_HEXNUM -A single unsigned integer, which is the integer value of extracted hexadecimal string. -.TP -.B 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 SOS or ST. -.PP -The -.I len -field of -.B "union ctlseqs_value" -should be used instead of -.I num -when the unsigned integer refers to the length of the following string or number of following values. +.BR CTLSEQS_PH_STR ", " CTLSEQS_PH_CMDSTR ", " CTLSEQS_PH_CSI_PARAM ", " CTLSEQS_PH_CSI_INTMD ", " CTLSEQS_PH_CHRSTR +The length of the string is stored in field +.IR len , +followed by a pointer to the first character of the string stored in field +.IR str . . .SH RETURN VALUES If