Update documentation for matcher.
continuous-integration/drone/push Build is passing Details

This commit is contained in:
CismonX 2021-03-19 20:58:33 +08:00
parent 3db4333d0a
commit 0ebc0054c4
Signed by: cismonx
GPG Key ID: 3094873E29A482FB
2 changed files with 53 additions and 44 deletions

View File

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

View File

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