From 3db4333d0accb776d3d4c837e2be6187ef227ef8 Mon Sep 17 00:00:00 2001 From: CismonX Date: Tue, 16 Mar 2021 08:33:02 +0800 Subject: [PATCH] Update documentation for matcher. --- doc/ctlseqs.texi | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/doc/ctlseqs.texi b/doc/ctlseqs.texi index f91350e..d8919de 100644 --- a/doc/ctlseqs.texi +++ b/doc/ctlseqs.texi @@ -338,6 +338,48 @@ const char *patterns[] = @{ @node Matching String @section Matching String +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: + +@example +union ctlseqs_value @{ + char const *str; + size_t len; + unsigned long num; +@}; +@end example + +If the string contains a recognizable control function, or part of a control +function which is not yet terminated by the end of the string, the length of +control function will be stored at @code{len} field of match result buffer at +offset 0, and the pointer to the first character of the control funtion at the +@code{str} field at offset 1. + +If @code{ctlseqs_match} fails to find any control functions, returns +@code{CTLSEQS_NESEQ}. For a partial control function, returns +@code{CTLSEQS_PARTIAL}. If the matcher is not configured with a pattern of the +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. + @node Control Sequence Reading @chapter Control Sequence Reading