Update `ctlseqs_match()`.

man/Makefile.am

@@ -9,6 +9,7 @@
 dist_man3_MANS = \
     ctlseqs_matcher_init.3 \
     ctlseqs_matcher_config.3 \
+    ctlseqs_match.3 \
     ctlseqs_matcher_free.3 \
     ctlseqs_reader_init.3 \
     ctlseqs_reader_config.3 \

man/ctlseqs_match.3

@@ -0,0 +1,98 @@
+.TH CTLSEQS_MATCH 3 "Sep 01, 2020" 0.1.0 "ctlseqs Library Manual"
+.
+.SH NAME
+ctlseqs_match - match control sequence
+.
+.SH SYNOPSYS
+.nf
+.B #include <ctlseqs.h>
+.PP
+.BI "ssize_t ctlseqs_match(struct ctlseqs_reader const *" matcher ", char const **" seq_ptr ,
+.BI "    size_t " seq_len ", union ctlseqs_value *" result );
+.fi
+.
+.SH DESCRIPTION
+Matches string against the patterns specified in
+.IR matcher .
+Stops when a valid control sequence is found, or when
+.I seq_len
+number of characters are processed.
+.PP
+Argument
+.I seq_ptr
+is the pointer to the string to be matched, which will point to the character next to the last one processed, when the function returns.
+.SS Match results
+Once a sequence is successfully matched, a group of values is extracted from the sequence for each placeholder, and stored into
+.I result
+sequentially.
+.PP
+An extracted value can be either a string (not guaranteed to be NUL-terminated), or an unsigned integer, as in
+.BR "union ctlseqs_value" :
+.PP
+.nf
+.in +4n
+.EX
+union ctlseqs_value {
+    char const    *str;
+    unsigned long  num;
+};
+.EE
+.in
+.fi
+.PP
+A group can contain one or multiple values, depending on different placeholders:
+.TP
+.B CTLSEQS_PH_NUM
+A single unsigned integer.
+.TP
+.B CTLSEQS_PH_NUMS
+An unsigned integer indicating the number of extracted values, followed by unsigned integers of that many.
+.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.
+.
+.SH RETURN VALUES
+.PP
+If the string specified by
+.I seq_ptr
+is a valid control sequence, and matches at least one pattern in
+.IR matcher ,
+returns a non-negative integer representing the offset of a matching pattern.
+.PP
+Otherwise, returns a negative value:
+.TP
+.B CTLSEQS_NOMATCH
+The string (or part of the string) is a valid control sequence, but fails to match any pattern in
+.IR matcher .
+.TP
+.B CTLSEQS_PARTIAL
+The string can be recognized as part of a control sequence, but is not yet terminated.
+.TP
+.B CTLSEQS_NOSEQ
+The string cannot be recognized as a valid control sequence.
+.
+.SH COPYRIGHT
+Copyright (c)  2020  CismonX <admin@cismon.net>
+.PP
+Copying and distribution of this file, with or without modification, are permitted in any medium without royalty, provided the copyright notice and this notice are preserved.
+This file is offered as-is, without any warranty.
+.
+.SH SEE ALSO
+.BR ctlseqs_matcher_config (3),
+.BR ctlseqs_reader_config (3),
+.BR ctlseqs_read (3)

src/ctlseqs.c

@@ -492,15 +492,17 @@ ctlseqs_matcher_config(struct ctlseqs_matcher *matcher, struct ctlseqs_matcher_o
 }
 
 CTLSEQS_HOT ssize_t
-ctlseqs_match(struct ctlseqs_matcher const *matcher, char const *seq, size_t seq_len, union ctlseqs_value *result)
+ctlseqs_match(struct ctlseqs_matcher const *matcher, char const **seq_ptr, size_t seq_len, union ctlseqs_value *result)
 {
     struct ctlseqs_match_args args = {
-        .seq      = seq,
+        .seq      = *seq_ptr,
         .seq_len  = seq_len,
         .result   = result,
-        .save_seq = true,
+        .save_seq = false,
     };
-    return ctlseqs_do_match(matcher, &args);
+    ssize_t retval = ctlseqs_do_match(matcher, &args);
+    *seq_ptr += args.result_idx;
+    return retval;
 }
 
 CTLSEQS_COLD void

src/ctlseqs.h

@@ -407,7 +407,7 @@ void
 ctlseqs_matcher_free(struct ctlseqs_matcher *matcher);
 
 ssize_t
-ctlseqs_match(struct ctlseqs_matcher const *matcher, char const *seq, size_t seq_len, union ctlseqs_value *result);
+ctlseqs_match(struct ctlseqs_matcher const *matcher, char const **seq_ptr, size_t seq_len, union ctlseqs_value *result);
 
 struct ctlseqs_reader *
 ctlseqs_reader_init();