Update documentation for matcher.

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